Support higher-resolution time stamps.

[bpt/emacs.git] / doc / lispref / os.texi

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index e604d92..6431ac8 100644 (file)
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1166,7 +1166,9 @@ The value may be a floating point number.
 zone.
 
 @cindex epoch
-  Most of these functions represent time as a list of either three
+  Most of these functions represent time as a list of either four
+integers, @code{(@var{sec-high} @var{sec-low} @var{microsec}
+@var{picosec})}, or of three
 integers, @code{(@var{sec-high} @var{sec-low} @var{microsec})}, or of
 two integers, @code{(@var{sec-high} @var{sec-low})}.  The integers
 @var{sec-high} and @var{sec-low} give the high and low bits of an
@@ -1181,12 +1183,15 @@ is the number of seconds from the @dfn{epoch} (0:00 January 1, 1970
 UTC) to the specified time.  The third list element @var{microsec}, if
 present, gives the number of microseconds from the start of that
 second to the specified time.
+Similarly, the fourth list element @var{picosec}, if present, gives
+the number of picoseconds from the start of that microsecond to the
+specified time.
 
   The return value of @code{current-time} represents time using three
-integers, while the timestamps in the return value of
-@code{file-attributes} use two integers (@pxref{Definition of
+integers, as do the timestamps in the return value of
+@code{file-attributes} (@pxref{Definition of
 file-attributes}).  In function arguments, e.g.@: the @var{time-value}
-argument to @code{current-time-string}, both two- and three-integer
+argument to @code{current-time-string}, two-, three-, and four-integer
 lists are accepted.  You can convert times from the list
 representation into standard human-readable strings using
 @code{current-time}, or to other forms using the @code{decode-time}
@@ -1216,9 +1221,12 @@ The argument @var{time-value}, if given, specifies a time to format
 @end defun
 
 @defun current-time
-This function returns the current time, represented as a list of three
-integers @code{(@var{sec-high} @var{sec-low} @var{microsec})}.  On
-systems with only one-second time resolutions, @var{microsec} is 0.
+This function returns the current time, represented as a list of four
+integers @code{(@var{sec-high} @var{sec-low} @var{microsec} @var{picosec})}.
+These integers have trailing zeros on systems that return time with
+lower resolutions.  On all current machines @var{picosec} is a
+multiple of 1000, but this may change as higher-resolution clocks
+become available.
 @end defun
 
 @defun float-time &optional time-value
@@ -1259,7 +1267,7 @@ time zone.
 @node Time Conversion
 @section Time Conversion
 
-  These functions convert time values (lists of two or three integers,
+  These functions convert time values (lists of two to four integers,
 as explained in the previous section) into calendrical information and
 vice versa.
 
@@ -1410,8 +1418,6 @@ This stands for a newline.
 This stands for the nanoseconds (000000000-999999999).  To ask for
 fewer digits, use @samp{%3N} for milliseconds, @samp{%6N} for
 microseconds, etc.  Any excess digits are discarded, without rounding.
-Currently Emacs time stamps are at best microsecond resolution so the
-last three digits generated by plain @samp{%N} are always zero.
 @item %p
 This stands for @samp{AM} or @samp{PM}, as appropriate.
 @item %r
@@ -1563,18 +1569,9 @@ When called interactively, it prints the uptime in the echo area.
 
 @defun get-internal-run-time
 This function returns the processor run time used by Emacs as a list
-of three integers: @code{(@var{high} @var{low} @var{microsec})}.  The
-integers @var{high} and @var{low} combine to give the number of
-seconds, which is
-@ifnottex
-@var{high} * 2**16 + @var{low}.
-@end ifnottex
-@tex
-$high*2^{16}+low$.
-@end tex
-
-The third element, @var{microsec}, gives the microseconds (or 0 for
-systems that return time with the resolution of only one second).
+of four integers: @code{(@var{high} @var{low} @var{microsec}
+@var{picosec})}, using the same format as @code{current-time}
+(@pxref{Time of Day}).
 
 Note that the time returned by this function excludes the time Emacs
 was not using the processor, and if the Emacs process has several
@@ -1817,10 +1814,9 @@ set up to repeat will subsequently run another time, one by one.
 
 @defun current-idle-time
 If Emacs is idle, this function returns the length of time Emacs has
-been idle, as a list of three integers: @code{(@var{sec-high}
-@var{sec-low} @var{microsec})}, where @var{high} and @var{low} are the
-high and low bits for the number of seconds and @var{microsec} is the
-additional number of microseconds (@pxref{Time of Day}).
+been idle, as a list of four integers: @code{(@var{sec-high}
+@var{sec-low} @var{microsec} @var{picosec})}, using the same format as
+@code{current-time} (@pxref{Time of Day}).
 
 When Emacs is not idle, @code{current-idle-time} returns @code{nil}.
 This is a convenient way to test whether Emacs is idle.