[PATCH 12/12] Revise the documentation of ‘simple calendar time’.

[Zack Weinberg <zackw at panix dot com>]

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.

---
Large blocks of text are moved around, so the diff is not terribly
informative; reviewers may find it easier to apply the diff and then
read the changed sections of the rendered manual.

This patch also includes a NEWS update covering all of the
user-visible changes in this patch series.
---
 NEWS                |   53 ++-
 manual/filesys.texi |    2 +-
 manual/llio.texi    |   10 +-
 manual/threads.texi |    2 +-
 manual/time.texi    | 1062 ++++++++++++++++++++++++-------------------
 5 files changed, 655 insertions(+), 474 deletions(-)

diff --git a/NEWS b/NEWS
index 045720b3fb..721c3e4385 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
 
@@ -25,6 +25,57 @@ 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.
 
+* 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, 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 ftime and gettimeofday functions 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 ftime will always receive a ‘struct timeb’
+  whose timezone and dstflag fields are zero (as if the system were
+  operating on UTC).  Similarly, callers of gettimeofday with a non-null
+  ‘tzp’ argument will always receive a ‘struct timezone’ whose
+  tz_minuteswest and tz_dsttime fields are zero.
+
+* 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 ntp_adjtime
+  instead.
+
 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 bfa46dd45b..b61d13c9ad 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,180 @@ 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.
+@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.  Its values
+are counts of @dfn{clock ticks} since some arbitrary event.  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 negative values can be used to represent calendar times
+before the epoch.
+
+POSIX says that @code{time_t} values do not include leap seconds, but
+some systems interpret them as including leap seconds when the
+@code{TZ} environment variable is set a certain way
+(@pxref{TZ Variable}).  This only affects conversions to broken-down
+time.
+@cindex epoch
+@cindex leap seconds
+@cindex seconds, leap
+@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}.  The calculation is unaware of whether
+or not @var{begin} and @var{end} are meant to include leap seconds.
+
+On POSIX-conformant systems, @samp{difftime (end, begin)} produces the
+same result as the expression @samp{(double)(end - begin)}.  But on
+other systems, @code{time_t} values might be encoded in a way that
+prevents subtraction from working directly.
+@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 +314,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 +406,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 +424,419 @@ 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
 
-@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}.
+@node Setting and Adjusting the Time
+@subsection Setting and Adjusting the Time
 
-Only the superuser can set the system clock.
+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.
 
-If the function succeeds, the return value is zero.  Otherwise, it is
-@code{-1} and @code{errno} is set accordingly:
+The functions in this section require special privileges to use.
+@xref{Users and Groups}.
+
+@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} (but see below
+for an exception).
+
+@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.
+
+@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).
 
-The @code{struct timezone} type is obsolete and should never be used.
-Instead, use the facilities described in @ref{Time Zone Functions}.
+@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 +844,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 +859,82 @@ 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 setting the 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 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 +942,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 +1274,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
 
@@ -2694,7 +2824,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})
@@ -2879,7 +3009,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}
-- 
2.23.0.rc1