Revise the documentation of simple calendar time.

This is a thorough revision of all the material relating to the
functions time, stime, gettimeofday, settimeofday, clock_gettime,
clock_getres, clock_settime, and difftime, spilling over into the
discussion of time-related data types (which now get their own
section) and touching the adjtime family as well (which deserves its
own thorough revision, but I'd have to do a bunch of research first).

Substantive changes are:

 * Document clock_gettime, clock_getres, and clock_settime.  (Only
   CLOCK_REALTIME and CLOCK_MONOTONIC are documented; the others are
   either a bit too Linux-specific, or have more to do with measuring
   CPU/processor time.  That section _also_ deserves its own thorough
   revision but again I'd have to do a bunch of research first.)

 * Present gettimeofday, settimeofday, and struct timeval as obsolete
   relative to clock_*.

 * Remove the documentation of struct timezone.  Matching POSIX,
   say that the type of the second argument to gettimeofday and
   settimeofday is [const] void *.

 * Clarify ISO C and POSIX's requirements on time_t.  Clarify the
   circumstances under which difftime is equivalent to simple
   subtraction.

 * Consolidate documentation of most of the time-related data types
   into a new section "Time Types," right after "Time Basics."  (The
   exceptions are struct tm, which stays in "Broken-down Time," and
   struct times, which stays in "Processor And CPU Time."

 * The "Elapsed Time" section is now called "Calculating Elapsed Time"
   and includes only difftime and the discussion of how to compute
   timeval differences by hand.

 * Fold the "Simple Calendar Time," "High Resolution Calendar," and
   "High Accuracy Clock" sections together into two new sections titled
   "Getting the Time" and "Setting and Adjusting the Time."

4 files changed, 611 insertions, 471 deletions

diff --git a/manual/filesys.texi b/manual/filesys.texi
index d31dbb24b4..73e630842e 100644
--- a/manual/filesys.texi
+++ b/manual/filesys.texi
@@ -2899,7 +2899,7 @@ which extends its resolution.  These fields are called
 @code{st_atime_usec}, @code{st_mtime_usec}, and @code{st_ctime_usec};
 each has a value between 0 and 999,999, which indicates the time in
 microseconds.  They correspond to the @code{tv_usec} field of a
-@code{timeval} structure; see @ref{High-Resolution Calendar}.
+@code{timeval} structure; see @ref{Time Types}.
 
 The @code{utimes} function is like @code{utime}, but also lets you specify
 the fractional part of the file times.  The prototype for this function is
diff --git a/manual/llio.texi b/manual/llio.texi
index 447126b7eb..fe59002915 100644
--- a/manual/llio.texi
+++ b/manual/llio.texi
@@ -2094,11 +2094,11 @@ descriptors.  The usual thing is to pass @code{FD_SETSIZE} as the value
 of this argument.
 
 The @var{timeout} specifies the maximum time to wait.  If you pass a
-null pointer for this argument, it means to block indefinitely until one
-of the file descriptors is ready.  Otherwise, you should provide the
-time in @code{struct timeval} format; see @ref{High-Resolution
-Calendar}.  Specify zero as the time (a @code{struct timeval} containing
-all zeros) if you want to find out which descriptors are ready without
+null pointer for this argument, it means to block indefinitely until
+one of the file descriptors is ready.  Otherwise, you should provide
+the time in @code{struct timeval} format; see @ref{Time Types}.
+Specify zero as the time (a @code{struct timeval} containing all
+zeros) if you want to find out which descriptors are ready without
 waiting if none are ready.
 
 The normal return value from @code{select} is the total number of ready file
diff --git a/manual/threads.texi b/manual/threads.texi
index 0e5e84ab0a..bfe1e5b50b 100644
--- a/manual/threads.texi
+++ b/manual/threads.texi
@@ -128,7 +128,7 @@ function returns @math{0}; otherwise, the return value is non-zero.
 least until the elapsed time pointed to by @var{time_point} has been
 reached.  This function does not take an absolute time, but a duration
 that the thread is required to be blocked.  @xref{Time Basics}, and
-@ref{Elapsed Time}.
+@ref{Time Types}.
 
 The thread may wake early if a signal that is not ignored is received.
 In such a case, if @code{remaining} is not NULL, the remaining time
diff --git a/manual/time.texi b/manual/time.texi
index c5f5b94b67..164c150f64 100644
--- a/manual/time.texi
+++ b/manual/time.texi
@@ -8,7 +8,8 @@ between different time representations.
 
 @menu
 * Time Basics::                 Concepts and definitions.
-* Elapsed Time::                Data types to represent elapsed times
+* Time Types::                  Data types to represent time.
+* Calculating Elapsed Time::    How to calculate the length of an interval.
 * Processor And CPU Time::      Time a program has spent executing.
 * Calendar Time::               Manipulation of ``real'' dates and times.
 * Setting an Alarm::            Sending a signal after a specified time.
@@ -55,100 +56,186 @@ especially when they are part of a sequence of regularly repeating
 events.
 @cindex period of time
 
-@dfn{CPU time} is like calendar time, except that it is based on the
-subset of the time continuum when a particular process is actively
-using a CPU.  CPU time is, therefore, relative to a process.
+A @dfn{simple calendar time} is a calendar time represented as an
+elapsed time since a fixed, implementation-specific calendar time
+called the @dfn{epoch}.  This representation is convenient for doing
+calculations on calendar times, such as finding the elapsed time
+between two calendar times.  Simple calendar times are independent of
+time zone; they represent the same instant in time regardless of where
+on the globe the computer is.
+
+POSIX says that simple calendar times do not include leap seconds, but
+some (otherwise POSIX-conformant) systems can be configured to include
+leap seconds in simple calendar times.
+@cindex leap seconds
+@cindex seconds, leap
+@cindex simple time
+@cindex simple calendar time
+@cindex calendar time, simple
+@cindex epoch
+
+A @dfn{broken-down time} is a calendar time represented by its
+components in the Gregorian calendar: year, month, day, hour, minute,
+and second.  A broken-down time value is relative to a specific time
+zone, and so it is also sometimes called a @dfn{local time}.
+Broken-down times are most useful for input and output, as they are
+easier for people to understand, but more difficult to calculate with.
+@cindex broken-down time
+@cindex local time
+@cindex Gregorian calendar
+@cindex calendar, Gregorian
+
+@dfn{CPU time} measures the amount of time that a single process has
+actively used a CPU to perform computations.  It does not include the
+time that process has spent waiting for external events.  The system
+tracks the CPU time used by each process separately.
 @cindex CPU time
 
-@dfn{Processor time} is an amount of time that a CPU is in use.  In
-fact, it's a basic system resource, since there's a limit to how much
-can exist in any given interval (that limit is the elapsed time of the
-interval times the number of CPUs in the processor).  People often call
-this CPU time, but we reserve the latter term in this manual for the
-definition above.
+@dfn{Processor time} measures the amount of time @emph{any} CPU has
+been in use by @emph{any} process.  It is a basic system resource,
+since there's a limit to how much can exist in any given interval (the
+elapsed time of the interval times the number of CPUs in the computer)
+
+People often call this CPU time, but we reserve the latter term in
+this manual for the definition above.
 @cindex processor time
 
-@node Elapsed Time
-@section Elapsed Time
-@cindex elapsed time
+@node Time Types
+@section Time Types
 
-One way to represent an elapsed time is with a simple arithmetic data
-type, as with the following function to compute the elapsed time between
-two calendar times.  This function is declared in @file{time.h}.
+ISO C and POSIX define several data types for representing elapsed
+times, simple calendar times, and broken-down times.
 
-@deftypefun double difftime (time_t @var{time1}, time_t @var{time0})
+@deftp {Data Type} clock_t
 @standards{ISO, time.h}
-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-The @code{difftime} function returns the number of seconds of elapsed
-time between calendar time @var{time1} and calendar time @var{time0}, as
-a value of type @code{double}.  The difference ignores leap seconds
-unless leap second support is enabled.
+@code{clock_t} is used to measure processor and CPU time.
+It may be an integer or a floating-point type.
+Its values are counts of @dfn{clock ticks} since some arbitrary event
+in the past.
+The number of clock ticks per second is system-specific.
+@xref{Processor And CPU Time}, for further detail.
+@cindex clock ticks
+@cindex ticks, clock
+@end deftp
 
-In @theglibc{}, you can simply subtract @code{time_t} values.  But on
-other systems, the @code{time_t} data type might use some other encoding
-where subtraction doesn't work directly.
-@end deftypefun
+@deftp {Data Type} time_t
+@standards{ISO, time.h}
+@code{time_t} is the simplest data type used to represent simple
+calendar time.
+
+In ISO C, @code{time_t} can be either an integer or a floating-point
+type, and the meaning of @code{time_t} values is not specified.  The
+only things a strictly conforming program can do with @code{time_t}
+values are: pass them to @code{difftime} to get the elapsed time
+between two simple calendar times (@pxref{Calculating Elapsed Time}),
+and pass them to the functions that convert them to broken-down time
+(@pxref{Broken-down Time}).
+
+On POSIX-conformant systems, @code{time_t} is an integer type and its
+values represent the number of seconds elapsed since the @dfn{epoch},
+which is 00:00:00 on January 1, 1970, Coordinated Universal Time.
+
+@Theglibc{} additionally guarantees that @code{time_t} is a signed
+type, and that all of its functions operate correctly on negative
+@code{time_t} values, which are interpreted as times before the epoch.
+@cindex epoch
+@end deftp
+
+@deftp {Data Type} {struct timespec}
+@standards{POSIX.1, time.h}
+@cindex timespec
+@code{struct timespec} represents a simple calendar time, or an
+elapsed time, with sub-second resolution.  It is declared in
+@file{time.h} and has the following members:
 
-@Theglibc{} provides two data types specifically for representing
-an elapsed time.  They are used by various @glibcadj{} functions, and
-you can use them for your own purposes too.  They're exactly the same
-except that one has a resolution in microseconds, and the other, newer
-one, is in nanoseconds.
+@table @code
+@item time_t tv_sec
+The number of whole seconds elapsed since the epoch (for a simple
+calendar time) or since some other starting point (for an elapsed
+time).
+
+@item long int tv_nsec
+The number of nanoseconds elapsed since the time given by the
+@code{tv_sec} member.
+
+When @code{struct timespec} values are produced by @glibcadj{}
+functions, the value in this field will always be greater than or
+equal to zero, and less than 1,000,000,000.
+When @code{struct timespec} values are supplied to @glibcadj{}
+functions, the value in this field must be in the same range.
+@end table
+@end deftp
 
 @deftp {Data Type} {struct timeval}
 @standards{BSD, sys/time.h}
 @cindex timeval
-The @code{struct timeval} structure represents an elapsed time.  It is
-declared in @file{sys/time.h} and has the following members:
+@code{struct timeval} is an older type for representing a simple
+calendar time, or an elapsed time, with sub-second resolution. It is
+almost the same as @code{struct timespec}, but provides only
+microsecond resolution.  It is declared in @file{sys/time.h} and has
+the following members:
 
 @table @code
 @item time_t tv_sec
-This represents the number of whole seconds of elapsed time.
+The number of whole seconds elapsed since the epoch (for a simple
+calendar time) or since some other starting point (for an elapsed
+time).
 
 @item long int tv_usec
-This is the rest of the elapsed time (a fraction of a second),
-represented as the number of microseconds.  It is always less than one
-million.
-
+The number of microseconds elapsed since the time given by the
+@code{tv_sec} member.
+
+When @code{struct timeval} values are produced by @glibcadj{}
+functions, the value in this field will always be greater than or
+equal to zero, and less than 1,000,000.
+When @code{struct timeval} values are supplied to @glibcadj{}
+functions, the value in this field must be in the same range.
 @end table
 @end deftp
 
-@deftp {Data Type} {struct timespec}
-@standards{POSIX.1, sys/time.h}
-@cindex timespec
-The @code{struct timespec} structure represents an elapsed time.  It is
-declared in @file{time.h} and has the following members:
+@deftp {Data Type} {struct tm}
+@standards{ISO, time.h}
+This is the data type used to represent a broken-down time.  It has
+separate fields for year, month, day, and so on.
+@xref{Broken-down Time}, for further details.
+@end deftp
 
-@table @code
-@item time_t tv_sec
-This represents the number of whole seconds of elapsed time.
+@node Calculating Elapsed Time
+@section Calculating Elapsed Time
 
-@item long int tv_nsec
-This is the rest of the elapsed time (a fraction of a second),
-represented as the number of nanoseconds.  It is always less than one
-billion.
+Often, one wishes to calculate an elapsed time as the difference
+between two simple calendar times.  @Theglibc{} provides only one
+function for this purpose.
 
-@end table
-@end deftp
+@deftypefun double difftime (time_t @var{end}, time_t @var{begin})
+@standards{ISO, time.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+The @code{difftime} function returns the number of seconds of elapsed
+time from calendar time @var{begin} to calendar time @var{end}, as
+a value of type @code{double}.
+
+On POSIX-conformant systems, the advantage of using
+@samp{difftime (@var{end}, @var{begin})} over @samp{@var{end} - @var{begin}}
+is that it will produce the mathematically correct result even if
+@var{end} and @var{begin} are so far apart that a simple subtraction
+would overflow.  However, if they are so far apart that a @code{double}
+cannot exactly represent the difference, the result will be inexact.
+
+On other systems, @code{time_t} values might be encoded in a way that
+prevents subtraction from working directly, and then @code{difftime}
+would be the only way to compute their difference.
+@end deftypefun
 
-It is often necessary to subtract two values of type @w{@code{struct
-timeval}} or @w{@code{struct timespec}}.  Here is the best way to do
-this.  It works even on some peculiar operating systems where the
-@code{tv_sec} member has an unsigned type.
+@Theglibc{} does not provide any functions for computing the
+difference between two values of type @w{@code{struct timeval}} or
+@w{@code{struct timespec}}.  Here is the recommended way to do this
+calculation by hand.  It works even on some peculiar operating systems
+where the @code{tv_sec} member has an unsigned type.
 
 @smallexample
 @include timeval_subtract.c.texi
 @end smallexample
 
-Common functions that use @code{struct timeval} are @code{gettimeofday}
-and @code{settimeofday}.
-
-
-There are no @glibcadj{} functions specifically oriented toward
-dealing with elapsed times, but the calendar time, processor time, and
-alarm and sleeping functions have a lot to do with them.
-
-
 @node Processor And CPU Time
 @section Processor And CPU Time
 
@@ -233,12 +320,6 @@ by the @code{clock} function.  POSIX requires that this value be one
 million independent of the actual resolution.
 @end deftypevr
 
-@deftp {Data Type} clock_t
-@standards{ISO, time.h}
-This is the type of the value returned by the @code{clock} function.
-Values of type @code{clock_t} are numbers of clock ticks.
-@end deftp
-
 @deftypefun clock_t clock (void)
 @standards{ISO, time.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
@@ -331,43 +412,15 @@ and @code{tms_stime} fields returned by @code{times}.
 @node Calendar Time
 @section Calendar Time
 
-This section describes facilities for keeping track of calendar time.
-@xref{Time Basics}.
-
-@Theglibc{} represents calendar time three ways:
-
-@itemize @bullet
-@item
-@dfn{Simple time} (the @code{time_t} data type) is a compact
-representation, typically giving the number of seconds of elapsed time
-since some implementation-specific base time.
-@cindex simple time
-
-@item
-There is also a "high-resolution time" representation.  Like simple
-time, this represents a calendar time as an elapsed time since a base
-time, but instead of measuring in whole seconds, it uses a @code{struct
-timeval} data type, which includes fractions of a second.  Use this time
-representation instead of simple time when you need greater precision.
-@cindex high-resolution time
-
-@item
-@dfn{Local time} or @dfn{broken-down time} (the @code{struct tm} data
-type) represents a calendar time as a set of components specifying the
-year, month, and so on in the Gregorian calendar, for a specific time
-zone.  This calendar time representation is usually used only to
-communicate with people.
-@cindex local time
-@cindex broken-down time
-@cindex Gregorian calendar
-@cindex calendar, Gregorian
-@end itemize
+This section describes the functions for getting, setting, and
+manipulating calendar times.
 
 @menu
-* Simple Calendar Time::        Facilities for manipulating calendar time.
-* High-Resolution Calendar::    A time representation with greater precision.
+* Getting the Time::            Functions for finding out what time it is.
+* Setting and Adjusting the Time::
+                                Functions for setting and adjusting
+                                  the system clock.
 * Broken-down Time::            Facilities for manipulating local time.
-* High Accuracy Clock::         Maintaining a high accuracy system clock.
 * Formatting Calendar Time::    Converting times to strings.
 * Parsing Date and Time::       Convert textual time and date information back
                                  into broken-down time values.
@@ -377,175 +430,419 @@ communicate with people.
 				 the time functions.
 @end menu
 
-@node Simple Calendar Time
-@subsection Simple Calendar Time
-
-This section describes the @code{time_t} data type for representing calendar
-time as simple time, and the functions which operate on simple time objects.
-These facilities are declared in the header file @file{time.h}.
-@pindex time.h
+@node Getting the Time
+@subsection Getting the Time
 
-@cindex epoch
-@deftp {Data Type} time_t
-@standards{ISO, time.h}
-This is the data type used to represent simple time.  Sometimes, it also
-represents an elapsed time.  When interpreted as a calendar time value,
-it represents the number of seconds elapsed since 00:00:00 on January 1,
-1970, Coordinated Universal Time.  (This calendar time is sometimes
-referred to as the @dfn{epoch}.)  POSIX requires that this count not
-include leap seconds, but on some systems this count includes leap seconds
-if you set @code{TZ} to certain values (@pxref{TZ Variable}).
-
-Note that a simple time has no concept of local time zone.  Calendar
-Time @var{T} is the same instant in time regardless of where on the
-globe the computer is.
-
-In @theglibc{}, @code{time_t} is equivalent to @code{long int}.
-In other systems, @code{time_t} might be either an integer or
-floating-point type.
-@end deftp
-
-The function @code{difftime} tells you the elapsed time between two
-simple calendar times, which is not always as easy to compute as just
-subtracting.  @xref{Elapsed Time}.
+@Theglibc{} provides several functions for getting the current
+calendar time, with different levels of resolution.
 
 @deftypefun time_t time (time_t *@var{result})
 @standards{ISO, time.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-The @code{time} function returns the current calendar time as a value of
-type @code{time_t}.  If the argument @var{result} is not a null pointer,
-the calendar time value is also stored in @code{*@var{result}}.  If the
-current calendar time is not available, the value
-@w{@code{(time_t)(-1)}} is returned.
+This is the simplest function for getting the current calendar time.
+It returns the calendar time as a value of type @code{time_t}; on
+POSIX systems, that means it has a resolution of one second.  It
+uses the same clock as @w{@samp{clock_gettime (CLOCK_REALTIME_COARSE)}},
+when the clock is available or @w{@samp{clock_gettime (CLOCK_REALTIME)}}
+otherwise.
+
+If the argument @var{result} is not a null pointer, the calendar time
+value is also stored in @code{*@var{result}}.
+
+This function cannot fail.
 @end deftypefun
 
-@c The GNU C library implements stime() with a call to settimeofday() on
-@c Linux.
-@deftypefun int stime (const time_t *@var{newtime})
-@standards{SVID, time.h}
-@standards{XPG, time.h}
-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-@c On unix, this is implemented in terms of settimeofday.
-@code{stime} sets the system clock, i.e., it tells the system that the
-current calendar time is @var{newtime}, where @code{newtime} is
-interpreted as described in the above definition of @code{time_t}.
+Some applications need more precise timekeeping than is possible with
+a @code{time_t} alone.  Some applications also need more control over
+what is meant by ``the current time.''  For these applications, POSIX
+provides a function @code{clock_gettime} that can retrieve the time
+with up to nanosecond precision, from a variety of different clocks.
+Clocks can be system-wide, measuring time the same for all processes;
+or they can be per-process or per-thread, measuring CPU time consumed
+by a particular process, or some other similar resource.  Each clock
+has its own resolution and epoch.  You can find the resolution of a
+clock with the function @code{clock_getres}.  There is no function to
+get the epoch for a clock; either it is fixed and documented, or the
+clock is not meant to be used to measure absolute times.
+
+@deftp {Data Type} clockid_t
+@standards{POSIX.1, time.h}
+The type @code{clockid_t} is used for constants that indicate which of
+several system clocks one wishes to use.
+@end deftp
+
+All systems that support this family of functions will define at least
+this clock constant:
+
+@deftypevr Macro clockid_t CLOCK_REALTIME
+@standards{POSIX.1, time.h}
+This clock uses the POSIX epoch, 00:00:00 on January 1, 1970, Coordinated
+Universal Time. It is close to, but not necessarily in lock-step with, the
+clocks of @code{time} (above) and of @code{gettimeofday} (below).
+@end deftypevr
+
+@cindex monotonic time
+A second clock constant which is not universal, but still very common,
+is for a clock measuring @dfn{monotonic time}.  Monotonic time is
+useful for measuring elapsed times, because it guarantees that those
+measurements are not affected by changes to the system clock.
+
+@deftypevr Macro clockid_t CLOCK_MONOTONIC
+@standards{POSIX.1, time.h}
+System-wide clock that continuously measures the advancement of
+calendar time, ignoring discontinuous changes to the system's
+setting for absolute calendar time.
+
+The epoch for this clock is an unspecified point in the past.
+The epoch may change if the system is rebooted or suspended.
+Therefore, @code{CLOCK_MONOTONIC} cannot be used to measure
+absolute time, only elapsed time.
+@end deftypevr
 
-@code{settimeofday} is a newer function which sets the system clock to
-better than one second precision.  @code{settimeofday} is generally a
-better choice than @code{stime}.  @xref{High-Resolution Calendar}.
+Systems may support more than just these two clocks.
 
-Only the superuser can set the system clock.
+@deftypefun int clock_gettime (clockid_t @var{clock}, struct timespec *@var{ts})
+@standards{POSIX.1, time.h}
+Get the current time accoding to the clock identified by @var{clock},
+storing it as seconds and nanoseconds in @code{*@var{ts}}.
+@xref{Time Types}, for a description of @code{struct timespec}.
 
-If the function succeeds, the return value is zero.  Otherwise, it is
-@code{-1} and @code{errno} is set accordingly:
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error condition is defined for this function:
 
 @table @code
-@item EPERM
-The process is not superuser.
+@item EINVAL
+The clock identified by @var{clock} is not supported.
 @end table
 @end deftypefun
 
+@code{clock_gettime} reports the time scaled to seconds and
+nanoseconds, but the actual resolution of each clock may not be as
+fine as one nanosecond, and may not be the same for all clocks.  POSIX
+also provides a function for finding out the actual resolution of a
+clock:
 
+@deftypefun int clock_getres (clockid_t @var{clock}, struct timespec *@var{res})
+@standards{POSIX.1, time.h}
+Get the actual resolution of the clock identified by @var{clock},
+storing it in @code{*@var{ts}}.
 
-@node High-Resolution Calendar
-@subsection High-Resolution Calendar
+For instance, if the clock hardware for @code{CLOCK_REALTIME}
+uses a quartz crystal that oscillates at 32.768 kHz,
+then its resolution would be 30.518 microseconds,
+and @w{@samp{clock_getres (CLOCK_REALTIME, &r)}} would set
+@code{r.tv_sec} to 0 and @code{r.tv_nsec} to 30518.
 
-The @code{time_t} data type used to represent simple times has a
-resolution of only one second.  Some applications need more precision.
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error condition is defined for this function:
 
-So, @theglibc{} also contains functions which are capable of
-representing calendar times to a higher resolution than one second.  The
-functions and the associated data types described in this section are
-declared in