@@ -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]
@@ -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
@@ -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
@@ -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
@@ -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}