[PATCH 3/7] Doc patches for ns-resolution time stamps

[Paul Eggert]

Document the change to nanosecond-resolution time stamps.
* os.texi (Time of Day, Time Parsing, Processor Run Time)
(Idle Timers):
* processes.texi (System Processes):
Time stamp resolution is now nanosecond, not microsecond.
=== modified file 'doc/lispref/os.texi'
--- doc/lispref/os.texi 2011-06-03 18:49:33 +0000
+++ doc/lispref/os.texi 2011-07-01 05:24:03 +0000
@@ -1111,7 +1111,7 @@
 as the times obtained from @code{current-time} (see below) and from
 @code{file-attributes} (@pxref{Definition of file-attributes}).  It
 should be a list whose first two elements are integers; a third
-(microsecond) element, if present, is ignored.  @var{time-value} can
+(nanosecond) element, if present, is ignored.  @var{time-value} can
 also be a cons of two integers, but this usage is obsolete.

 @example
@@ -1124,7 +1124,7 @@

 @defun current-time
 This function returns the system's time value as a list of three
-integers: @code{(@var{high} @var{low} @var{microsec})}.  The integers
+numbers: @code{(@var{high} @var{low} @var{nanosec})}.  The numbers
 @var{high} and @var{low} combine to give the number of seconds since
 0:00 January 1, 1970 UTC (Coordinated Universal Time), which is
 @ifnottex
@@ -1134,11 +1134,14 @@
 $high*2^{16}+low$.
 @end tex

-The third element, @var{microsec}, gives the microseconds since the
-start of the current second (or 0 for systems that return time with
-the resolution of only one second).
-
-The first two elements can be compared with file time values such as you
+The third number, @var{nanosec}, gives the nanoseconds since the
+start of the current second.  It may have trailing zeros on systems
+that return time with lower resolutions.
+
+The numbers are normally integers, but they are floating-point numbers
+if they are outside the integer range.
+
+The list can be compared with file time values such as you
 get with the function @code{file-attributes}.
 @xref{Definition of file-attributes}.
 @end defun
@@ -1340,8 +1343,6 @@
 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
@@ -1493,18 +1494,8 @@

 @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
address@hidden
address@hidden * 2**16 + @var{low}.
address@hidden ifnottex
address@hidden
-$high*2^{16}+low$.
address@hidden tex
-
-The third element, @var{microsec}, gives the microseconds (or 0 for
-systems that return time with the resolution of only one second).
+of three numbers: @code{(@var{high} @var{low} @var{nanosec})}, 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
@@ -1748,19 +1739,9 @@
 @c Emacs 19 feature
 @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{high} @var{low}
address@hidden)}.  The integers @var{high} and @var{low} combine to
-give the number of seconds of idleness, which is
address@hidden
address@hidden * 2**16 + @var{low}.
address@hidden ifnottex
address@hidden
-$high*2^{16}+low$.
address@hidden tex
-
-The third element, @var{microsec}, gives the microseconds since the
-start of the current second (or 0 for systems that return time with
-the resolution of only one second).
+been idle, as a list of three numbers: @code{(@var{high} @var{low}
address@hidden)}, 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.

=== modified file 'doc/lispref/processes.texi'
--- doc/lispref/processes.texi  2011-06-15 17:30:41 +0000
+++ doc/lispref/processes.texi  2011-07-01 05:24:03 +0000
@@ -1770,7 +1770,7 @@
 @item utime
 Time spent by the process in the user context, for running the
 application's code.  The corresponding @var{value} is in the
address@hidden@code{(@var{high} @var{low} @var{microsec})}} format, the same
address@hidden@code{(@var{high} @var{low} @var{nanosec})}} format, the same
 format used by functions @code{current-time} (@pxref{Time of Day,
 current-time}) and @code{file-attributes} (@pxref{File Attributes}).

@@ -1801,12 +1801,12 @@

 @item start
 The time when the process was started, in the same
address@hidden@code{(@var{high} @var{low} @var{microsec})}} format used by
address@hidden@code{(@var{high} @var{low} @var{nanosec})}} format used by
 @code{current-time} and @code{file-attributes}.

 @item etime
 The time elapsed since the process started, in the @address@hidden(@var{high}
address@hidden @var{microsec})}} format.
address@hidden @var{nanosec})}} format.

 @item vsize
 The virtual memory size of the process, measured in kilobytes.