Patchwork [v2,10/10] Revise the documentation of simple calendar time.

login
register
mail settings
Submitter Zack Weinberg
Date Aug. 28, 2019, 3:32 p.m.
Message ID <20190828153236.18229-11-zackw@panix.com>
Download mbox | patch
Permalink /patch/34311/
State New
Headers show

Comments

Zack Weinberg - Aug. 28, 2019, 3:32 p.m.
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."

ChangeLog:
	* manual/time.texi: Major revision of text related to simple
	calendar time.  clock_gettime, clock_getres, and clock_settime
	are now documented.
	* manual/filesys.texi, manual/llio.texi, manual/threads.texi:
	Update cross-references to renamed sections in time.texi.
---
 NEWS                |   62 ++-
 manual/filesys.texi |    2 +-
 manual/llio.texi    |   10 +-
 manual/threads.texi |    2 +-
 manual/time.texi    | 1071 ++++++++++++++++++++++++-------------------
 5 files changed, 673 insertions(+), 474 deletions(-)
Paul Eggert - Aug. 29, 2019, 1:09 a.m.
Zack Weinberg wrote:

> +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)}}
> +and @code{gettimeofday} (see below).

As we've discussed recently (e.g., 
<https://sourceware.org/ml/libc-alpha/2019-08/msg00755.html>), the 'time' 
function does not necessarily use the same clock as clock_gettime 
(CLOCK_REALTIME). On GNU/Linux it appears to use the CLOCK_REALTIME_COARSE 
clock, though I doubt whether that's guaranteed everywhere. So I suggest 
changing that last sentence to:

This function uses a clock close to the clocks of @w{@samp{clock_gettime 
(CLOCK_REALTIME)}} and of @code{gettimeofday} (see below), but the three clocks 
are not necessarily in lock-step, and precise timestamp comparison is reliable 
only when timestamps come from the same clock.

> +@deftypevr Macro clockid_t CLOCK_REALTIME
> +@standards{POSIX.1, time.h}
> +System-wide clock measuring calendar time.  This clock reports the
> +same time as @code{time} (above) and @code{gettimeofday} (below) and
> +uses the POSIX epoch, 00:00:00 on January 1, 1970, Coordinated
> +Universal Time.

Similarly, change the last sentence to:

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).

> +@code{struct timeval}.  @code{gettimeofday} uses the same clock as
> +@code{time} and @w{@samp{clock_gettime (CLOCK_REALTIME)}}.

Similarly, change this sentence to:

The clock of @code{gettimeofday} is close to, but not necessarily in lock-step 
with, the clocks of @code{time} and of @w{@samp{clock_gettime (CLOCK_REALTIME)}} 
(see above).
Zack Weinberg - Aug. 29, 2019, 5:41 p.m.
On Wed, Aug 28, 2019 at 9:09 PM Paul Eggert <eggert@cs.ucla.edu> wrote:
> Zack Weinberg wrote:
> > +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)}}
> > +and @code{gettimeofday} (see below).
>
> As we've discussed recently (e.g.,
> <https://sourceware.org/ml/libc-alpha/2019-08/msg00755.html>), the 'time'
> function does not necessarily use the same clock as clock_gettime
> (CLOCK_REALTIME).
...
> This function uses a clock close to the clocks of @w{@samp{clock_gettime
> (CLOCK_REALTIME)}} and of @code{gettimeofday} (see below), but the three clocks
> are not necessarily in lock-step, and precise timestamp comparison is reliable
> only when timestamps come from the same clock.

I think it's good to add a cautionary note *like* this, but I'm
worried that your suggested text might confuse readers into thinking
that these clocks might use different epochs or could be set
independently.  I'll think about how to put it better.

zw
Paul Eggert - Aug. 30, 2019, 7:17 p.m.
>> This function uses a clock close to the clocks of @w{@samp{clock_gettime
>> (CLOCK_REALTIME)}} and of @code{gettimeofday} (see below), but the three clocks
>> are not necessarily in lock-step, and precise timestamp comparison is reliable
>> only when timestamps come from the same clock.

> I think it's good to add a cautionary note *like  this, but I'm
> worried that your suggested text might confuse readers into thinking
> that these clocks might use different epochs or could be set
> independently.  I'll think about how to put it better.

Yes, the wording "close to" was my attempt to prevent that conclusion. 
The wording could be expanded -- though when I tried to expand it 
myself, I found that the expansion was not clearer enough to be worth 
the extra words.

Patch

diff --git a/NEWS b/NEWS
index a64b89986a..75453bbda8 100644
--- a/NEWS
+++ b/NEWS
@@ -3,7 +3,7 @@  Copyright (C) 1992-2019 Free Software Foundation, Inc.
 See the end for copying conditions.
 
 Please send GNU C library bug reports via <https://sourceware.org/bugzilla/>
-using `glibc' in the "product" field.
+using ‘glibc’ in the "product" field.
 
 Version 2.31
 
@@ -30,6 +30,66 @@  Deprecated and removed features, and other changes affecting compatibility:
   Request 25 to TS 18661-1, as applied for C2X.  Existing binaries that pass
   floating-point arguments directly will continue to work.
 
+* The obsolete functions ftime and stime are no longer available to newly
+  linked binaries, and the header <sys/timeb.h> has been removed.  Programs
+  that used these functions should be updated to use clock_gettime and
+  clock_settime, respectively.
+
+* On Linux-based systems, glibc now uses the clock_gettime and clock_settime
+  system calls to implement all of the other functions that get or set
+  the time: time, ftime, gettimeofday, timespec_get, stime, and settimeofday.
+
+  System calls and/or vDSO functions, if any, that directly implement these
+  functions will no longer be used, with one exception: ‘settimeofday’ may
+  still invoke the system call of the same name when its ‘tzp’ argument is
+  not a null pointer (see below).
+
+  This change was made because the Linux kernel maintainers intend to
+  provide only clock_gettime and clock_settime system calls on future new
+  architectures, and to deprecate the other system calls on existing
+  architectures.  It potentially breaks programs that use seccomp filters to
+  limit the set of system calls a process can use.
+
+* The gettimeofday function will no longer report information about a
+  system-wide time zone.
+
+  This 4.2-BSD-era feature has been deprecated for many years, as it cannot
+  handle the full complexity of the world’s timezones, but hitherto we have
+  supported it on a best-effort basis.  Changes required to support 64-bit
+  time_t on 32-bit architectures have made this no longer practical.
+
+  As of this release, callers of gettimeofday with a non-null ‘tzp’ argument
+  will always receive a ‘struct timezone’ whose tz_minuteswest and
+  tz_dsttime fields are zero.  We have also arranged for call sites that
+  pass a non-null ‘tzp’ argument to gettimeofday to receive compile-time
+  warnings, if the compiler makes this possible.
+
+  A similar change has been made to the obsolete function ftime.
+
+* The settimeofday function _can_ still be used to set a system-wide time
+  zone when the operating system supports it.  This is because the Linux
+  kernel reused the API, on some architectures, to describe a system-wide
+  time-zone-like offset between the software clock maintained by the kernel,
+  and the “RTC” clock that keeps time when the system is shut down.
+
+  However, to reduce the odds of this offset being set by accident,
+  settimeofday can no longer be used to set the time and the offset
+  simultaneously.  If both of its two arguments are non-null, the call
+  will fail (setting errno to EINVAL).
+
+  Callers attempting to set this offset should also be prepared for the call
+  to fail and set errno to ENOSYS; this already happens on the Hurd and on
+  some Linux architectures.  The Linux kernel maintainers are discussing a
+  more principled replacement for the reused API.  After a replacement
+  becomes available, we will change settimeofday to fail with ENOSYS on all
+  platforms when its ‘tzp’ argument is not a null pointer.
+
+  Note that settimeofday itself is obsolescent according to POSIX.
+  Programs that set the system time should use clock_settime and/or
+  the adjtime family of functions instead.  We may also cease to make
+  settimeofday available to newly linked binaries after there is a
+  replacement for Linux’s time-zone-like offset API.
+
 Changes to build and runtime requirements:
 
   [Add changes to build and runtime requirements here]
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..b3f02254f4 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
 
-@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.
+@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:
+
+@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,418 @@  communicate with people.
 				 the time functions.
 @end menu
 
-@node Simple Calendar Time
-@subsection Simple Calendar Time
+@node Getting the Time
+@subsection Getting the 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
+@Theglibc{} provides several functions for getting the current
+calendar time, with different levels of resolution.
 
-@cindex epoch
-@deftp {Data Type} time_t
+@deftypefun time_t time (time_t *@var{result})
 @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.
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+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)}}
+and @code{gettimeofday} (see below).
+
+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
+
+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
 
-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}.
+All systems that support this family of functions will define at least
+this clock constant:
 
-@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.
+@deftypevr Macro clockid_t CLOCK_REALTIME
+@standards{POSIX.1, time.h}
+System-wide clock measuring calendar time.  This clock reports the
+same time as @code{time} (above) and @code{gettimeofday} (below) and
+uses the POSIX epoch, 00:00:00 on January 1, 1970, Coordinated
+Universal Time.
+@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
+
+Systems may support more than just these two clocks.
+
+@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}.
+
+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 EINVAL
+The clock identified by @var{clock} is not supported.
+@end table
 @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}
+@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}}.
+
+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 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 EINVAL
+The clock identified by @var{clock} is not supported.
+@end table
+@end deftypefun
+
+These functions, and the constants that identify particular clocks,
+are declared in @file{time.h}.
+
+@strong{Portability Note:} On some systems, including systems that use
+older versions of @theglibc{}, programs that use @code{clock_gettime}
+or @code{clock_setres} must be linked with the @code{-lrt} library.
+This has not been necessary with @theglibc{} since version 2.17.
+
+@Theglibc{} also provides an older, but still widely used, function
+for getting the current time with a resolution of microseconds.  This
+function is declared in @file{sys/time.h}.
+
+@deftypefun int gettimeofday (struct timeval *@var{tp}, void *@var{tzp})
+@standards{BSD, sys/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}.
+Get the current calendar time, storing it as seconds and microseconds
+in @code{*@var{tp}}.  @xref{Time Types}, for a description of
+@code{struct timeval}.  @code{gettimeofday} uses the same clock as
+@code{time} and @w{@samp{clock_gettime (CLOCK_REALTIME)}}.
+
+On some historic systems, if @var{tzp} was not a null pointer,
+information about a system-wide time zone would be written to
+@code{*@var{tzp}}.  This feature is obsolete and not supported on
+@gnusystems{}.  You should always supply a null pointer for this
+argument.  Instead, use the facilities described in @ref{Time Zone
+Functions} and in @ref{Broken-down Time} for working with time zones.
+
+This function cannot fail, and its return value is always @code{0}.
+
+@strong{Portability Note:} As of the 2008 revision of POSIX, this
+function is considered obsolete.  @Theglibc{} will continue to provide
+this function indefinitely, but new programs should use
+@code{clock_gettime} instead.
+@end deftypefun
+
+@node Setting and Adjusting the Time
+@subsection Setting and Adjusting the Time
 
-@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}.
+The clock hardware inside a modern computer is quite reliable, but it
+can still be wrong.  The functions in this section allow one to set
+the system's idea of the current calendar time, and to adjust the rate
+at which the system counts seconds, so that the calendar time will
+both be accurate, and remain accurate.
 
-Only the superuser can set the system clock.
+The functions in this section require special privileges to use.
+@xref{Users and Groups}.
 
-If the function succeeds, the return value is zero.  Otherwise, it is
-@code{-1} and @code{errno} is set accordingly:
+@deftypefun int clock_settime (clockid_t @var{clock}, const struct timespec *@var{ts})
+@standards{POSIX, time.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Change the current calendar time, according to the clock identified by
+@var{clock}, to be the simple calendar time in @code{*@var{ts}}.
+
+Not all of the system's clocks can be changed.  For instance, the
+@code{CLOCK_REALTIME} clock can be changed (with the appropriate
+privileges), but the @code{CLOCK_MONOTONIC} clock cannot.
+
+Because simple calendar times are independent of time zone, this
+function should not be used when the time zone changes (e.g.@: if the
+computer is physically moved from one zone to another).  Instead, use
+the facilities described in @ref{Time Zone Functions}.
+
+@code{clock_settime} causes the clock to jump forwards or backwards,
+which can cause a variety of problems.  Changing the
+@code{CLOCK_REALTIME} clock with @code{clock_settime} does not affect
+when timers expire (@pxref{Setting an Alarm}) or when sleeping
+processes wake up (@pxref{Sleeping}), which avoids some of the
+problems.  Still, for small changes made while the system is running,
+it is better to use @code{ntp_adjtime} (below) to make a smooth
+transition from one time to another.
+
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error conditions are defined for this function:
 
 @table @code
+@item EINVAL
+The clock identified by @var{clock} is not supported or cannot be set
+at all, or the simple calendar time in @code{*@var{ts}} is invalid
+(for instance, @code{ts->tv_nsec} is negative or greater than 999,999,999).
+
 @item EPERM
-The process is not superuser.
+This process does not have the privileges required to set the clock
+identified by @var{clock}.
 @end table
+
+@strong{Portability Note}: On some systems, including systems that use
+older versions of @theglibc{}, programs that use @code{clock_settime}
+must be linked with the @code{-lrt} library.  This has not been
+necessary with @theglibc{} since version 2.17.
 @end deftypefun
 
+@cindex time, high precision
+@cindex clock, high accuracy
+@cindex clock, disciplining
+@pindex sys/timex.h
+For systems that remain up and running for long periods, it is not
+enough to set the time once; one should also @dfn{discipline} the
+clock so that it does not drift away from the true calendar time.
 
+The @code{ntp_gettime} and @code{ntp_adjtime} functions provide an
+interface to monitor and discipline the system clock.  For example,
+you can fine-tune the rate at which the clock ``ticks,'' and make
+small adjustments to the current reported calendar time smoothly, by
+temporarily speeding up or slowing down the clock.
 
-@node High-Resolution Calendar
-@subsection High-Resolution Calendar
+These functions' names begin with @samp{ntp_} because they were
+designed for use by programs implementing the Network Time Protocol to
+synchronize a system's clock with other systems' clocks and/or with
+external high-precision clock hardware.
 
-The @code{time_t} data type used to represent simple times has a
-resolution of only one second.  Some applications need more precision.
+These functions, and the constants and structures they use, are
+declared in @file{sys/timex.h}.
 
-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 @file{sys/time.h}.
-@pindex sys/time.h
+@tindex struct ntptimeval
+@deftp {Data Type} {struct ntptimeval}
+This structure is used to report information about the system clock.
+It contains the following members:
+@table @code
+@item struct timeval time
+The current calendar time, as if retrieved by @code{gettimeofday}.
+The @code{struct timeval} data type is described in
+@ref{Time Types}.
 
-@deftp {Data Type} {struct timezone}
-@standards{BSD, sys/time.h}
-The @code{struct timezone} structure is used to hold minimal information
-about the local time zone.  It has the following members:
+@item long int maxerror
+This is the maximum error, measured in microseconds.  Unless updated
+via @code{ntp_adjtime} periodically, this value will reach some
+platform-specific maximum value.
+
+@item long int esterror
+This is the estimated error, measured in microseconds.  This value can
+be set by @code{ntp_adjtime} to indicate the estimated offset of the
+system clock from the true calendar time.
+@end table
+@end deftp
+
+@deftypefun int ntp_gettime (struct ntptimeval *@var{tptr})
+@standards{GNU, sys/timex.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+@c Wrapper for adjtimex.
+The @code{ntp_gettime} function sets the structure pointed to by
+@var{tptr} to current values.  The elements of the structure afterwards
+contain the values the timer implementation in the kernel assumes.  They
+might or might not be correct.  If they are not, an @code{ntp_adjtime}
+call is necessary.
 
+The return value is @code{0} on success and other values on failure.  The
+following @code{errno} error conditions are defined for this function:
+
+@vtable @code
+@item TIME_ERROR
+The precision clock model is not properly set up at the moment, thus the
+clock must be considered unsynchronized, and the values should be
+treated with care.
+@end vtable
+@end deftypefun
+
+@tindex struct timex
+@deftp {Data Type} {struct timex}
+This structure is used to control and monitor the system clock.  It
+contains the following members:
 @table @code
-@item int tz_minuteswest
-This is the number of minutes west of UTC.
+@item unsigned int modes
+This variable controls whether and which values are set.  Several
+symbolic constants have to be combined with @emph{binary or} to specify
+the effective mode.  These constants start with @code{MOD_}.
 
-@item int tz_dsttime
-If nonzero, Daylight Saving Time applies during some part of the year.
-@end table
+@item long int offset
+This value indicates the current offset of the system clock from the true
+calendar time.  The value is given in microseconds.  If bit
+@code{MOD_OFFSET} is set in @code{modes}, the offset (and possibly other
+dependent values) can be set.  The offset's absolute value must not
+exceed @code{MAXPHASE}.
+
+
+@item long int frequency
+This value indicates the difference in frequency between the true
+calendar time and the system clock.  The value is expressed as scaled
+PPM (parts per million, 0.0001%).  The scaling is @code{1 <<
+SHIFT_USEC}.  The value can be set with bit @code{MOD_FREQUENCY}, but
+the absolute value must not exceed @code{MAXFREQ}.
+
+@item long int maxerror
+This is the maximum error, measured in microseconds.  A new value can be
+set using bit @code{MOD_MAXERROR}.  Unless updated via
+@code{ntp_adjtime} periodically, this value will increase steadily
+and reach some platform-specific maximum value.
+
+@item long int esterror
+This is the estimated error, measured in microseconds.  This value can
+be set using bit @code{MOD_ESTERROR}.
+
+@item int status
+This variable reflects the various states of the clock machinery.  There
+are symbolic constants for the significant bits, starting with
+@code{STA_}.  Some of these flags can be updated using the
+@code{MOD_STATUS} bit.
+
+@item long int constant
+This value represents the bandwidth or stiffness of the PLL (phase
+locked loop) implemented in the kernel.  The value can be changed using
+bit @code{MOD_TIMECONST}.
+
+@item long int precision
+This value represents the accuracy or the maximum error when reading the
+system clock.  The value is expressed in microseconds.
+
+@item long int tolerance
+This value represents the maximum frequency error of the system clock in
+scaled PPM.  This value is used to increase the @code{maxerror} every
+second.
+
+@item struct timeval time
+The current calendar time.
+
+@item long int tick
+The elapsed time between clock ticks in microseconds.  A clock tick is a
+periodic timer interrupt on which the system clock is based.
+
+@item long int ppsfreq
+This is the first of a few optional variables that are present only if
+the system clock can use a PPS (pulse per second) signal to discipline
+the system clock.  The value is expressed in scaled PPM and it denotes
+the difference in frequency between the system clock and the PPS signal.
+
+@item long int jitter
+This value expresses a median filtered average of the PPS signal's
+dispersion in microseconds.
 
-The @code{struct timezone} type is obsolete and should never be used.
-Instead, use the facilities described in @ref{Time Zone Functions}.
+@item int shift
+This value is a binary exponent for the duration of the PPS calibration
+interval, ranging from @code{PPS_SHIFT} to @code{PPS_SHIFTMAX}.
+
+@item long int stabil
+This value represents the median filtered dispersion of the PPS
+frequency in scaled PPM.
+
+@item long int jitcnt
+This counter represents the number of pulses where the jitter exceeded
+the allowed maximum @code{MAXTIME}.
+
+@item long int calcnt
+This counter reflects the number of successful calibration intervals.
+
+@item long int errcnt
+This counter represents the number of calibration errors (caused by
+large offsets or jitter).
+
+@item long int stbcnt
+This counter denotes the number of calibrations where the stability
+exceeded the threshold.
+@end table
 @end deftp
 
-@deftypefun int gettimeofday (struct timeval *@var{tp}, struct timezone *@var{tzp})
-@standards{BSD, sys/time.h}
+@deftypefun int ntp_adjtime (struct timex *@var{tptr})
+@standards{GNU, sys/timex.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-@c On most GNU/Linux systems this is a direct syscall, but the posix/
-@c implementation (not used on GNU/Linux or GNU/Hurd) relies on time and
-@c localtime_r, saving and restoring tzname in an unsafe manner.
-@c On some GNU/Linux variants, ifunc resolvers are used in shared libc
-@c for vdso resolution.  ifunc-vdso-revisit.
-The @code{gettimeofday} function returns the current calendar time as
-the elapsed time since the epoch in the @code{struct timeval} structure
-indicated by @var{tp}.  (@pxref{Elapsed Time} for a description of
-@code{struct timeval}).  Information about the time zone is returned in
-the structure pointed to by @var{tzp}.  If the @var{tzp} argument is a null
-pointer, time zone information is ignored.
+@c Alias to adjtimex syscall.
+The @code{ntp_adjtime} function sets the structure specified by
+@var{tptr} to current values.
+
+In addition, @code{ntp_adjtime} updates some settings to match what you
+pass to it in *@var{tptr}.  Use the @code{modes} element of *@var{tptr}
+to select what settings to update.  You can set @code{offset},
+@code{freq}, @code{maxerror}, @code{esterror}, @code{status},
+@code{constant}, and @code{tick}.
 
-The return value is @code{0} on success and @code{-1} on failure.  The
-following @code{errno} error condition is defined for this function:
+@code{modes} = zero means set nothing.
 
-@table @code
-@item ENOSYS
-The operating system does not support getting time zone information, and
-@var{tzp} is not a null pointer.  @gnusystems{} do not
-support using @w{@code{struct timezone}} to represent time zone
-information; that is an obsolete feature of 4.3 BSD.
-Instead, use the facilities described in @ref{Time Zone Functions}.
-@end table
-@end deftypefun
+Only the superuser can update settings.
 
-@deftypefun int settimeofday (const struct timeval *@var{tp}, const struct timezone *@var{tzp})
-@standards{BSD, sys/time.h}
-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-@c On HURD, it calls host_set_time with a privileged port.  On other
-@c unix systems, it's a syscall.
-The @code{settimeofday} function sets the current calendar time in the
-system clock according to the arguments.  As for @code{gettimeofday},
-the calendar time is represented as the elapsed time since the epoch.
-As for @code{gettimeofday}, time zone information is ignored if
-@var{tzp} is a null pointer.
-
-You must be a privileged user in order to use @code{settimeofday}.
-
-Some kernels automatically set the system clock from some source such as
-a hardware clock when they start up.  Others, including Linux, place the
-system clock in an ``invalid'' state (in which attempts to read the clock
-fail).  A call of @code{stime} removes the system clock from an invalid
-state, and system startup scripts typically run a program that calls
-@code{stime}.
-
-@code{settimeofday} causes a sudden jump forwards or backwards, which
-can cause a variety of problems in a system.  Use @code{adjtime} (below)
-to make a smooth transition from one time to another by temporarily
-speeding up or slowing down the clock.
-
-With a Linux kernel, @code{adjtimex} does the same thing and can also
-make permanent changes to the speed of the system clock so it doesn't
-need to be corrected as often.
+@c On Linux, ntp_adjtime() also does the adjtime() function if you set
+@c modes = ADJ_OFFSET_SINGLESHOT (in fact, that is how GNU libc implements
+@c adjtime()).  But this should be considered an internal function because
+@c it's so inconsistent with the rest of what ntp_adjtime() does and is
+@c forced in an ugly way into the struct timex.  So we don't document it
+@c and instead document adjtime() as the way to achieve the function.
 
-The return value is @code{0} on success and @code{-1} on failure.  The
+The return value is @code{0} on success and other values on failure.  The
 following @code{errno} error conditions are defined for this function:
 
 @table @code
+@item TIME_ERROR
+The high accuracy clock model is not properly set up at the moment, thus the
+clock must be considered unsynchronized, and the values should be
+treated with care.  Another reason could be that the specified new values
+are not allowed.
+
 @item EPERM
-This process cannot set the clock because it is not privileged.
+The process specified a settings update, but is not superuser.
 
-@item ENOSYS
-The operating system does not support setting time zone information, and
-@var{tzp} is not a null pointer.
 @end table
+
+For more details see RFC1305 (Network Time Protocol, Version 3) and
+related documents.
+
+@strong{Portability note:} Early versions of @theglibc{} did not
+have this function, but did have the synonymous @code{adjtimex}.
 @end deftypefun
 
+
 @c On Linux, GNU libc implements adjtime() as a call to adjtimex().
 @deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta})
 @standards{BSD, sys/time.h}
@@ -553,10 +849,11 @@  The operating system does not support setting time zone information, and
 @c On hurd and mach, call host_adjust_time with a privileged port.  On
 @c Linux, it's implemented in terms of adjtimex.  On other unixen, it's
 @c a syscall.
-This function speeds up or slows down the system clock in order to make
-a gradual adjustment.  This ensures that the calendar time reported by
-the system clock is always monotonically increasing, which might not
-happen if you simply set the clock.
+This simpler version of @code{ntp_adjtime} speeds up or slows down the
+system clock for a short time, in order to correct it by a small
+amount.  This avoids a discontinuous change in the calendar time
+reported by the @code{CLOCK_REALTIME} clock, at the price of having to
+wait longer for the time to become correct.
 
 The @var{delta} argument specifies a relative adjustment to be made to
 the clock time.  If negative, the system clock is slowed down for a
@@ -567,37 +864,86 @@  If the @var{olddelta} argument is not a null pointer, the @code{adjtime}
 function returns information about any previous time adjustment that
 has not yet completed.
 
-This function is typically used to synchronize the clocks of computers
-in a local network.  You must be a privileged user to use it.
-
-With a Linux kernel, you can use the @code{adjtimex} function to
-permanently change the clock speed.
-
 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
-You do not have privilege to set the time.
+This process does not have the privileges required to adjust the
+@code{CLOCK_REALTIME} clock.
 @end table
 @end deftypefun
 
-@strong{Portability Note:}  The @code{gettimeofday}, @code{settimeofday},
-and @code{adjtime} functions are derived from BSD.
+For compatibility, @theglibc{} also provides several older functions
+for controlling the system time.  New programs should prefer to use
+the functions above.
+
+@deftypefun int stime (const time_t *@var{newtime})
+@standards{SVID, time.h}
+@standards{XPG, time.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Change the @code{CLOCK_REALTIME} calendar time to be the simple
+calendar time in @code{*@var{newtime}}.  Calling this function is
+exactly the same as calling @w{@samp{clock_settime (CLOCK_REALTIME)}},
+except that the new time can only be set to a precision of one second.
+
+This function is no longer available on @gnusystems{}, but it may be
+the @emph{only} way to set the time on very old Unix systems, so we
+continue to document it.  If it is available, it is declared in
+@file{time.h}.
 
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error condition is defined for this function:
 
-Symbols for the following function are declared in @file{sys/timex.h}.
+@table @code
+@item EPERM
+This process does not have the privileges required to adjust the
+@code{CLOCK_REALTIME} clock.
+@end table
+@end deftypefun
 
 @deftypefun int adjtimex (struct timex *@var{timex})
 @standards{GNU, sys/timex.h}
 @safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-@c It's a syscall, only available on linux.
+@code{adjtimex} is an older name for @code{ntp_adjtime}.
+This function is only available on @gnulinuxsystems{}.
+It is declared in @file{sys/timex.h}.
+@end deftypefun
+
+@deftypefun int settimeofday (const struct timeval *@var{tp}, const void *@var{tzp})
+@standards{BSD, sys/time.h}
+@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
+Change the @code{CLOCK_REALTIME} calendar time to be the simple
+calendar time in @code{*@var{newtime}}.  This function is declared in
+@file{sys/time.h}.
+
+When @var{tzp} is a null pointer, calling this function is exactly the
+same as calling @w{@samp{clock_settime (CLOCK_REALTIME)}}, except that
+the new time can only be set to a precision of one microsecond.
+
+When @var{tzp} is not a null pointer, the data it points to @emph{may}
+be used to set a system-wide idea of the current timezone.  This
+feature is obsolete and not supported on @gnusystems{}.  Instead, use
+the facilities described in @ref{Time Zone Functions} and in
+@ref{Broken-down Time} for working with time zones.
+
+The return value is @code{0} on success and @code{-1} on failure.  The
+following @code{errno} error conditions are defined for this function:
 
-@code{adjtimex} is functionally identical to @code{ntp_adjtime}.
-@xref{High Accuracy Clock}.
+@table @code
+@item EPERM
+This process does not have the privileges required to set the
+@code{CLOCK_REALTIME} clock.
 
-This function is present only with a Linux kernel.
+@item EINVAL
+Neither @var{tp} nor @var{tzp} is a null pointer.  (For historical
+reasons, it is not possible to set the current time and the current
+time zone in the same call.)
 
+@item ENOSYS
+The operating system does not support setting time zone information, and
+@var{tzp} is not a null pointer.
+@end table
 @end deftypefun
 
 @node Broken-down Time
@@ -605,13 +951,13 @@  This function is present only with a Linux kernel.
 @cindex broken-down time
 @cindex calendar time and broken-down time
 
-Calendar time is represented by the usual @glibcadj{} functions as an
-elapsed time since a fixed base calendar time.  This is convenient for
-computation, but has no relation to the way people normally think of
-calendar time.  By contrast, @dfn{broken-down time} is a binary
-representation of calendar time separated into year, month, day, and so
-on.  Broken-down time values are not useful for calculations, but they
-are useful for printing human readable time information.
+Simple calendar times represent absolute times as elapsed times since
+an epoch.  This is convenient for computation, but has no relation to
+the way people normally think of calendar time.  By contrast,
+@dfn{broken-down time} is a binary representation of calendar time
+separated into year, month, day, and so on.  Broken-down time values
+are not useful for calculations, but they are useful for printing
+human readable time information.
 
 A broken-down time value is always relative to a choice of time
 zone, and it also indicates which time zone that is.
@@ -937,213 +1283,6 @@  the @code{TZ} environment variable to UTC, call @code{mktime}, then set
 
 
 
-@node High Accuracy Clock
-@subsection High Accuracy Clock
-
-@cindex time, high precision
-@cindex clock, high accuracy
-@pindex sys/timex.h
-@c On Linux, GNU libc implements ntp_gettime() and npt_adjtime() as calls
-@c to adjtimex().
-The @code{ntp_gettime} and @code{ntp_adjtime} functions provide an
-interface to monitor and manipulate the system clock to maintain high
-accuracy time.  For example, you can fine tune the speed of the clock
-or synchronize it with another time source.
-
-A typical use of these functions is by a server implementing the Network
-Time Protocol to synchronize the clocks of multiple systems and high
-precision clocks.
-
-These functions are declared in @file{sys/timex.h}.
-
-@tindex struct ntptimeval
-@deftp {Data Type} {struct ntptimeval}
-This structure is used for information about the system clock.  It
-contains the following members:
-@table @code
-@item struct timeval time
-This is the current calendar time, expressed as the elapsed time since
-the epoch.  The @code{struct timeval} data type is described in
-@ref{Elapsed Time}.
-
-@item long int maxerror
-This is the maximum error, measured in microseconds.  Unless updated
-via @code{ntp_adjtime} periodically, this value will reach some
-platform-specific maximum value.
-
-@item long int esterror
-This is the estimated error, measured in microseconds.  This value can
-be set by @code{ntp_adjtime} to indicate the estimated offset of the
-system clock from the true calendar time.
-@end table
-@end deftp
-
-@deftypefun int ntp_gettime (struct ntptimeval *@var{tptr})
-@standards{GNU, sys/timex.h}
-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-@c Wrapper for adjtimex.
-The @code{ntp_gettime} function sets the structure pointed to by
-@var{tptr} to current values.  The elements of the structure afterwards
-contain the values the timer implementation in the kernel assumes.  They
-might or might not be correct.  If they are not, an @code{ntp_adjtime}
-call is necessary.
-
-The return value is @code{0} on success and other values on failure.  The
-following @code{errno} error conditions are defined for this function:
-
-@vtable @code
-@item TIME_ERROR
-The precision clock model is not properly set up at the moment, thus the
-clock must be considered unsynchronized, and the values should be
-treated with care.
-@end vtable
-@end deftypefun
-
-@tindex struct timex
-@deftp {Data Type} {struct timex}
-This structure is used to control and monitor the system clock.  It
-contains the following members:
-@table @code
-@item unsigned int modes
-This variable controls whether and which values are set.  Several
-symbolic constants have to be combined with @emph{binary or} to specify
-the effective mode.  These constants start with @code{MOD_}.
-
-@item long int offset
-This value indicates the current offset of the system clock from the true
-calendar time.  The value is given in microseconds.  If bit
-@code{MOD_OFFSET} is set in @code{modes}, the offset (and possibly other
-dependent values) can be set.  The offset's absolute value must not
-exceed @code{MAXPHASE}.
-
-
-@item long int frequency
-This value indicates the difference in frequency between the true
-calendar time and the system clock.  The value is expressed as scaled
-PPM (parts per million, 0.0001%).  The scaling is @code{1 <<
-SHIFT_USEC}.  The value can be set with bit @code{MOD_FREQUENCY}, but
-the absolute value must not exceed @code{MAXFREQ}.
-
-@item long int maxerror
-This is the maximum error, measured in microseconds.  A new value can be
-set using bit @code{MOD_MAXERROR}.  Unless updated via
-@code{ntp_adjtime} periodically, this value will increase steadily
-and reach some platform-specific maximum value.
-
-@item long int esterror
-This is the estimated error, measured in microseconds.  This value can
-be set using bit @code{MOD_ESTERROR}.
-
-@item int status
-This variable reflects the various states of the clock machinery.  There
-are symbolic constants for the significant bits, starting with
-@code{STA_}.  Some of these flags can be updated using the
-@code{MOD_STATUS} bit.
-
-@item long int constant
-This value represents the bandwidth or stiffness of the PLL (phase
-locked loop) implemented in the kernel.  The value can be changed using
-bit @code{MOD_TIMECONST}.
-
-@item long int precision
-This value represents the accuracy or the maximum error when reading the
-system clock.  The value is expressed in microseconds.
-
-@item long int tolerance
-This value represents the maximum frequency error of the system clock in
-scaled PPM.  This value is used to increase the @code{maxerror} every
-second.
-
-@item struct timeval time
-The current calendar time.
-
-@item long int tick
-The elapsed time between clock ticks in microseconds.  A clock tick is a
-periodic timer interrupt on which the system clock is based.
-
-@item long int ppsfreq
-This is the first of a few optional variables that are present only if
-the system clock can use a PPS (pulse per second) signal to discipline
-the system clock.  The value is expressed in scaled PPM and it denotes
-the difference in frequency between the system clock and the PPS signal.
-
-@item long int jitter
-This value expresses a median filtered average of the PPS signal's
-dispersion in microseconds.
-
-@item int shift
-This value is a binary exponent for the duration of the PPS calibration
-interval, ranging from @code{PPS_SHIFT} to @code{PPS_SHIFTMAX}.
-
-@item long int stabil
-This value represents the median filtered dispersion of the PPS
-frequency in scaled PPM.
-
-@item long int jitcnt
-This counter represents the number of pulses where the jitter exceeded
-the allowed maximum @code{MAXTIME}.
-
-@item long int calcnt
-This counter reflects the number of successful calibration intervals.
-
-@item long int errcnt
-This counter represents the number of calibration errors (caused by
-large offsets or jitter).
-
-@item long int stbcnt
-This counter denotes the number of calibrations where the stability
-exceeded the threshold.
-@end table
-@end deftp
-
-@deftypefun int ntp_adjtime (struct timex *@var{tptr})
-@standards{GNU, sys/timex.h}
-@safety{@prelim{}@mtsafe{}@assafe{}@acsafe{}}
-@c Alias to adjtimex syscall.
-The @code{ntp_adjtime} function sets the structure specified by
-@var{tptr} to current values.
-
-In addition, @code{ntp_adjtime} updates some settings to match what you
-pass to it in *@var{tptr}.  Use the @code{modes} element of *@var{tptr}
-to select what settings to update.  You can set @code{offset},
-@code{freq}, @code{maxerror}, @code{esterror}, @code{status},
-@code{constant}, and @code{tick}.
-
-@code{modes} = zero means set nothing.
-
-Only the superuser can update settings.
-
-@c On Linux, ntp_adjtime() also does the adjtime() function if you set
-@c modes = ADJ_OFFSET_SINGLESHOT (in fact, that is how GNU libc implements
-@c adjtime()).  But this should be considered an internal function because
-@c it's so inconsistent with the rest of what ntp_adjtime() does and is
-@c forced in an ugly way into the struct timex.  So we don't document it
-@c and instead document adjtime() as the way to achieve the function.
-
-The return value is @code{0} on success and other values on failure.  The
-following @code{errno} error conditions are defined for this function:
-
-@table @code
-@item TIME_ERROR
-The high accuracy clock model is not properly set up at the moment, thus the
-clock must be considered unsynchronized, and the values should be
-treated with care.  Another reason could be that the specified new values
-are not allowed.
-
-@item EPERM
-The process specified a settings update, but is not superuser.
-
-@end table
-
-For more details see RFC1305 (Network Time Protocol, Version 3) and
-related documents.
-
-@strong{Portability note:} Early versions of @theglibc{} did not
-have this function but did have the synonymous @code{adjtimex}.
-
-@end deftypefun
-
-
 @node Formatting Calendar Time
 @subsection Formatting Calendar Time
 
@@ -2700,7 +2839,7 @@  This is the period between now and the first timer interrupt.  If zero,
 the alarm is disabled.
 @end table
 
-The @code{struct timeval} data type is described in @ref{Elapsed Time}.
+The @code{struct timeval} data type is described in @ref{Time Types}.
 @end deftp
 
 @deftypefun int setitimer (int @var{which}, const struct itimerval *@var{new}, struct itimerval *@var{old})
@@ -2885,7 +3024,7 @@  The function returns as *@code{remaining} the elapsed time left in the
 interval for which you requested to sleep.  If the interval completed
 without getting interrupted by a signal, this is zero.
 
-@code{struct timespec} is described in @xref{Elapsed Time}.
+@code{struct timespec} is described in @ref{Time Types}.
 
 If the function returns because the interval is over the return value is
 zero.  If the function returns @math{-1} the global variable @code{errno}