mirror of
git://sourceware.org/git/glibc.git
synced 2025-01-18 12:16:13 +08:00
Update.
* manual/sysinfo.texi: Fix typo. * manual/time.texi: Document timelocal, timegm, adjtimex, and stime. Replace "high precision time" with "high accuracy clock". Fix language. Patches by Bryan Henderson <bryanh@giraffe-data.com>.
This commit is contained in:
Ulrich Drepper
parent
54eb84d0c7
commit
3566d33c12
@ -1,5 +1,11 @@
|
||||
2000-04-21 Ulrich Drepper <drepper@redhat.com>
|
||||
|
||||
* manual/sysinfo.texi: Fix typo.
|
||||
* manual/time.texi: Document timelocal, timegm, adjtimex, and stime.
|
||||
Replace "high precision time" with "high accuracy clock".
|
||||
Fix language.
|
||||
Patches by Bryan Henderson <bryanh@giraffe-data.com>.
|
||||
|
||||
* nis/nis_findserv.c (__nis_findfastest): Improve memory handling.
|
||||
* nis/nis_print_group_entry.c (nis_print_group_entry): Use alloca
|
||||
instead of malloc.
|
||||
|
||||
@ -691,7 +691,7 @@ For a remount, @code{mount} ignores @var{fstype}.
|
||||
@c This is traditionally called "rwflag" for historical reasons.
|
||||
@c No point in confusing people today, though.
|
||||
@var{options} specifies a variety of options that apply until the
|
||||
filesystem in unmounted or remounted. The precise meaning of an option
|
||||
filesystem is unmounted or remounted. The precise meaning of an option
|
||||
depends on the filesystem and with some filesystems, an option may have
|
||||
no effect at all. Furthermore, for some filesystems, some of these
|
||||
options (but never @code{MS_RDONLY}) can be overridden for individual
|
||||
|
||||
541
manual/time.texi
541
manual/time.texi
@ -25,8 +25,6 @@ an Alarm}.
|
||||
@menu
|
||||
* Processor Time:: Measures processor time used by a program.
|
||||
* Calendar Time:: Manipulation of ``real'' dates and times.
|
||||
* Precision Time:: Manipulation and monitoring of high accuracy
|
||||
time.
|
||||
* Setting an Alarm:: Sending a signal after a specified time.
|
||||
* Sleeping:: Waiting for a period of time.
|
||||
@end menu
|
||||
@ -195,42 +193,45 @@ the @code{tms_utime} and @code{tms_stime} fields returned by
|
||||
@node Calendar Time
|
||||
@section Calendar Time
|
||||
|
||||
This section describes facilities for keeping track of dates and times
|
||||
according to the Gregorian calendar.
|
||||
@cindex Gregorian calendar
|
||||
This section describes facilities for keeping track of points in time.
|
||||
This is called calendar time and sometimes absolute time.
|
||||
@cindex time, absolute
|
||||
@cindex time, calendar
|
||||
@cindex date and time
|
||||
|
||||
There are three representations for date and time information:
|
||||
The GNU C library represents calendar time three ways:
|
||||
|
||||
@itemize @bullet
|
||||
@item
|
||||
@dfn{Calendar time} (the @code{time_t} data type) is a compact
|
||||
@dfn{Simple time} (the @code{time_t} data type) is a compact
|
||||
representation, typically giving the number of seconds elapsed since
|
||||
some implementation-specific base time.
|
||||
@cindex calendar time
|
||||
@cindex simple time
|
||||
|
||||
@item
|
||||
There is also a @dfn{high-resolution time} representation (the @code{struct
|
||||
timeval} data type) that includes fractions of a second. Use this time
|
||||
representation instead of ordinary calendar time when you need greater
|
||||
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 the date and time as a set of components
|
||||
specifying the year, month, and so on, for a specific time zone.
|
||||
This time representation is usually used in conjunction with formatting
|
||||
date and time values.
|
||||
@dfn{Local time} or @dfn{broken-down time} (the @code{struct tm} data
|
||||
type) represents the date and time as a set of components specifying the
|
||||
year, month, and so on in the Gregorian calendar, for a specific time
|
||||
zone. This 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
|
||||
|
||||
@menu
|
||||
* Simple Calendar Time:: Facilities for manipulating calendar time.
|
||||
* High-Resolution Calendar:: A time representation with greater precision.
|
||||
* Broken-down Time:: Facilities for manipulating local time.
|
||||
* High Accuracy Clock:: Maintaining a high accuracy system clock.
|
||||
* Formatting Date and Time:: Converting times to strings.
|
||||
* Parsing Date and Time:: Convert textual time and date information back
|
||||
into broken-down time values.
|
||||
@ -243,8 +244,8 @@ date and time values.
|
||||
@node Simple Calendar Time
|
||||
@subsection Simple Calendar Time
|
||||
|
||||
This section describes the @code{time_t} data type for representing
|
||||
calendar time, and the functions which operate on calendar time objects.
|
||||
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
|
||||
|
||||
@ -252,14 +253,19 @@ These facilities are declared in the header file @file{time.h}.
|
||||
@comment time.h
|
||||
@comment ISO
|
||||
@deftp {Data Type} time_t
|
||||
This is the data type used to represent calendar time.
|
||||
This is the data type used to represent simple time. Sometimes, it also
|
||||
represents an elapsed time.
|
||||
When interpreted as an absolute time
|
||||
value, it represents the number of seconds elapsed since 00:00:00 on
|
||||
January 1, 1970, Coordinated Universal Time. (This date is sometimes
|
||||
January 1, 1970, Coordinated Universal Time. (This time is sometimes
|
||||
referred to as the @dfn{epoch}.) POSIX requires that this count
|
||||
ignore leap seconds, but on some hosts this count includes leap seconds
|
||||
not include leap seconds, but on some hosts 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. Time @var{N}
|
||||
is the same instant in time regardless of where on the globe the
|
||||
computer is.
|
||||
|
||||
In the GNU C library, @code{time_t} is equivalent to @code{long int}.
|
||||
In other systems, @code{time_t} might be either an integer or
|
||||
floating-point type.
|
||||
@ -287,11 +293,36 @@ time value is also stored in @code{*@var{result}}. If the calendar
|
||||
time is not available, the value @w{@code{(time_t)(-1)}} is returned.
|
||||
@end deftypefun
|
||||
|
||||
@c The GNU C library implements stime() with a call to settimeofday() on
|
||||
@c Linux.
|
||||
@comment time.h
|
||||
@comment SVID, XPG
|
||||
@deftypefun int stime (time_t *@var{newtime})
|
||||
@code{stime} sets the system clock, i.e. it tells the system that the
|
||||
present absolute time is @var{newtime}, where @code{newtime} is
|
||||
interpreted as described in the above definition of @code{time_t}.
|
||||
|
||||
@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}.
|
||||
|
||||
Only the superuser can set the system clock.
|
||||
|
||||
If the function succeeds, the return value is zero. Otherwise, it is
|
||||
@code{-1} and @code{errno} is set accordingly:
|
||||
|
||||
@table @code
|
||||
@item EPERM
|
||||
The process is not superuser.
|
||||
@end table
|
||||
@end deftypefun
|
||||
|
||||
|
||||
|
||||
@node High-Resolution Calendar
|
||||
@subsection High-Resolution Calendar
|
||||
|
||||
The @code{time_t} data type used to represent calendar times has a
|
||||
The @code{time_t} data type used to represent simple times has a
|
||||
resolution of only one second. Some applications need more precision.
|
||||
|
||||
So, the GNU C library also contains functions which are capable of
|
||||
@ -405,6 +436,22 @@ 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 time
|
||||
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.
|
||||
|
||||
The return value is @code{0} on success and @code{-1} on failure. The
|
||||
following @code{errno} error conditions are defined for this function:
|
||||
|
||||
@ -418,6 +465,7 @@ The operating system does not support setting time zone information, and
|
||||
@end table
|
||||
@end deftypefun
|
||||
|
||||
@c On Linux, GNU libc implements adjtime() as a call to adjtimex().
|
||||
@comment sys/time.h
|
||||
@comment BSD
|
||||
@deftypefun int adjtime (const struct timeval *@var{delta}, struct timeval *@var{olddelta})
|
||||
@ -437,6 +485,10 @@ 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:
|
||||
|
||||
@ -450,19 +502,32 @@ You do not have privilege to set the time.
|
||||
and @code{adjtime} functions are derived from BSD.
|
||||
|
||||
|
||||
Symbols for the following function are declared in @file{sys/timex.h}.
|
||||
|
||||
@comment sys/timex.h
|
||||
@comment GNU
|
||||
@deftypefun int adjtimex (struct timex *@var{timex})
|
||||
|
||||
@code{adjtimex} is functionally identical to @code{ntp_adjtime}.
|
||||
@xref{High Accuracy Clock}.
|
||||
|
||||
This function is present only with a Linux kernel.
|
||||
|
||||
@end deftypefun
|
||||
|
||||
@node Broken-down Time
|
||||
@subsection Broken-down Time
|
||||
@cindex broken-down time
|
||||
@cindex calendar time and broken-down time
|
||||
|
||||
Calendar time is represented as a number of seconds. This is convenient
|
||||
for calculation, but has no relation to the way people normally
|
||||
represent dates and times. By contrast, @dfn{broken-down time} is a binary
|
||||
representation 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.
|
||||
Calendar time is represented as an amount of time since a fixed base
|
||||
time. This is convenient for calculation, but has no relation to the
|
||||
way people normally think of dates and times. By contrast,
|
||||
@dfn{broken-down time} is a binary representation 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.
|
||||
|
||||
A broken-down time value is always relative to a choice of local time
|
||||
A broken-down time value is always relative to a choice of time
|
||||
zone, and it also indicates which time zone was used.
|
||||
|
||||
The symbols in this section are declared in the header file @file{time.h}.
|
||||
@ -533,7 +598,7 @@ GNU extension, and is not visible in a strict @w{ISO C} environment.
|
||||
@comment time.h
|
||||
@comment ISO
|
||||
@deftypefun {struct tm *} localtime (const time_t *@var{time})
|
||||
The @code{localtime} function converts the calendar time pointed to by
|
||||
The @code{localtime} function converts the simple time pointed to by
|
||||
@var{time} to broken-down time representation, expressed relative to the
|
||||
user's specified time zone.
|
||||
|
||||
@ -559,7 +624,7 @@ all threads. POSIX.1c introduced a variant of this function.
|
||||
@comment POSIX.1c
|
||||
@deftypefun {struct tm *} localtime_r (const time_t *@var{time}, struct tm *@var{resultp})
|
||||
The @code{localtime_r} function works just like the @code{localtime}
|
||||
function. It takes a pointer to a variable containing the calendar time
|
||||
function. It takes a pointer to a variable containing a simple time
|
||||
and converts it to the broken-down time format.
|
||||
|
||||
But the result is not placed in a static buffer. Instead it is placed
|
||||
@ -575,11 +640,9 @@ object the result was written into, i.e., it returns @var{resultp}.
|
||||
@comment ISO
|
||||
@deftypefun {struct tm *} gmtime (const time_t *@var{time})
|
||||
This function is similar to @code{localtime}, except that the broken-down
|
||||
time is expressed as Coordinated Universal Time (UTC)---that is, as
|
||||
Greenwich Mean Time (GMT)---rather than relative to the local time zone.
|
||||
time is expressed as Coordinated Universal Time (UTC) (formerly called
|
||||
Greenwich Mean Time (GMT)) rather than relative to a local time zone.
|
||||
|
||||
Recall that calendar times are @emph{always} expressed in coordinated
|
||||
universal time.
|
||||
@end deftypefun
|
||||
|
||||
As for the @code{localtime} function we have the problem that the result
|
||||
@ -601,19 +664,19 @@ object the result was written into, i.e., it returns @var{resultp}.
|
||||
@comment ISO
|
||||
@deftypefun time_t mktime (struct tm *@var{brokentime})
|
||||
The @code{mktime} function is used to convert a broken-down time structure
|
||||
to a calendar time representation. It also ``normalizes'' the contents of
|
||||
to a simple time representation. It also ``normalizes'' the contents of
|
||||
the broken-down time structure, by filling in the day of week and day of
|
||||
year based on the other date and time components.
|
||||
|
||||
The @code{mktime} function ignores the specified contents of the
|
||||
@code{tm_wday} and @code{tm_yday} members of the broken-down time
|
||||
structure. It uses the values of the other components to compute the
|
||||
structure. It uses the values of the other components to determine the
|
||||
calendar time; it's permissible for these components to have
|
||||
unnormalized values outside their normal ranges. The last thing that
|
||||
@code{mktime} does is adjust the components of the @var{brokentime}
|
||||
structure (including the @code{tm_wday} and @code{tm_yday}).
|
||||
|
||||
If the specified broken-down time cannot be represented as a calendar time,
|
||||
If the specified broken-down time cannot be represented as a simple time,
|
||||
@code{mktime} returns a value of @code{(time_t)(-1)} and does not modify
|
||||
the contents of @var{brokentime}.
|
||||
|
||||
@ -621,6 +684,242 @@ Calling @code{mktime} also sets the variable @code{tzname} with
|
||||
information about the current time zone. @xref{Time Zone Functions}.
|
||||
@end deftypefun
|
||||
|
||||
@comment time.h
|
||||
@comment ???
|
||||
@deftypefun time_t timelocal (struct tm *@var{brokentime})
|
||||
|
||||
@code{timelocal} is functionally identical to @code{mktime}, but more
|
||||
mnemonically named. Note that it is the inverse of the @code{localtime}
|
||||
function.
|
||||
|
||||
@strong{Portability note:} @code{mktime} is essentially universally
|
||||
available. @code{timelocal} is rather rare.
|
||||
|
||||
@end deftypefun
|
||||
|
||||
@comment time.h
|
||||
@comment ???
|
||||
@deftypefun time_t timegm (struct tm *@var{brokentime})
|
||||
|
||||
@code{timegm} is functionally identical to @code{mktime} except it
|
||||
always takes the input values to be Coordinated Universal Time (UTC)
|
||||
regardless of any local time zone setting.
|
||||
|
||||
Note that @code{timegm} is the inverse of @code{gmtime}.
|
||||
|
||||
@strong{Portability note:} @code{mktime} is essentially universally
|
||||
available. @code{timegm} is rather rare. For the most portable
|
||||
conversion from a UTC broken-down time to a simple time, set
|
||||
the @code{TZ} environment variable to UTC, call @code{mktime}, then set
|
||||
@code{TZ} back.
|
||||
|
||||
@end deftypefun
|
||||
|
||||
|
||||
|
||||
@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 to monitor kernel time. It contains the
|
||||
following members:
|
||||
@table @code
|
||||
@item struct timeval time
|
||||
This is the current time. The @code{struct timeval} data type is
|
||||
described in @ref{High-Resolution Calendar}.
|
||||
|
||||
@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
|
||||
local clock against the true time.
|
||||
@end table
|
||||
@end deftp
|
||||
|
||||
@comment sys/timex.h
|
||||
@comment GNU
|
||||
@deftypefun int ntp_gettime (struct ntptimeval *@var{tptr})
|
||||
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 a @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:
|
||||
|
||||
@table @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 table
|
||||
@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 local clock from the true
|
||||
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 time
|
||||
and the local 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 time.
|
||||
|
||||
@item long int tick
|
||||
The 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 local clock. The value is expressed in scaled PPM and it denotes
|
||||
the difference in frequency between the local 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 of calibrations where the stability
|
||||
exceeded the threshold.
|
||||
@end table
|
||||
@end deftp
|
||||
|
||||
@comment sys/timex.h
|
||||
@comment GNU
|
||||
@deftypefun int ntp_adjtime (struct timex *@var{tptr})
|
||||
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 the GNU C library did not
|
||||
have this function but did have the synonymous @code{adjtimex}.
|
||||
|
||||
@end deftypefun
|
||||
|
||||
|
||||
@node Formatting Date and Time
|
||||
@subsection Formatting Date and Time
|
||||
|
||||
@ -669,7 +968,7 @@ return @code{NULL}.
|
||||
@comment ISO
|
||||
@deftypefun {char *} ctime (const time_t *@var{time})
|
||||
The @code{ctime} function is similar to @code{asctime}, except that the
|
||||
time value is specified as a @code{time_t} calendar time value rather
|
||||
time value is specified as a @code{time_t} simple time value rather
|
||||
than in broken-down local time format. It is equivalent to
|
||||
|
||||
@smallexample
|
||||
@ -1816,8 +2115,8 @@ effect.
|
||||
@node Time Functions Example
|
||||
@subsection Time Functions Example
|
||||
|
||||
Here is an example program showing the use of some of the local time and
|
||||
calendar time functions.
|
||||
Here is an example program showing the use of some of the calendar time
|
||||
functions.
|
||||
|
||||
@smallexample
|
||||
@include strftim.c.texi
|
||||
@ -1832,169 +2131,6 @@ The time is 01:02 PM.
|
||||
@end smallexample
|
||||
|
||||
|
||||
@node Precision Time
|
||||
@section Precision Time
|
||||
|
||||
@cindex time, high precision
|
||||
@pindex sys/timex.h
|
||||
The @code{ntp_gettime} and @code{ntp_adjtime} functions provide an
|
||||
interface to monitor and manipulate high precision time. These
|
||||
functions are declared in @file{sys/timex.h}.
|
||||
|
||||
@tindex struct ntptimeval
|
||||
@deftp {Data Type} {struct ntptimeval}
|
||||
This structure is used to monitor kernel time. It contains the
|
||||
following members:
|
||||
@table @code
|
||||
@item struct timeval time
|
||||
This is the current time. The @code{struct timeval} data type is
|
||||
described in @ref{High-Resolution Calendar}.
|
||||
|
||||
@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
|
||||
local clock against the true time.
|
||||
@end table
|
||||
@end deftp
|
||||
|
||||
@comment sys/timex,h
|
||||
@comment GNU
|
||||
@deftypefun int ntp_gettime (struct ntptimeval *@var{tptr})
|
||||
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 a @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:
|
||||
|
||||
@table @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 table
|
||||
@end deftypefun
|
||||
|
||||
@tindex struct timex
|
||||
@deftp {Data Type} {struct timex}
|
||||
This structure is used to control and monitor kernel time in a greater
|
||||
level of detail. 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 local clock from the true
|
||||
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 time
|
||||
and the local 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 and can't be changed.
|
||||
|
||||
@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 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 local clock. The value is expressed in scaled PPM and it denotes
|
||||
the difference in frequency between the local 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 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 of calibrations where the stability
|
||||
exceeded the threshold.
|
||||
@end table
|
||||
@end deftp
|
||||
|
||||
@comment sys/timex.h
|
||||
@comment GNU
|
||||
@deftypefun int ntp_adjtime (struct timex *@var{tptr})
|
||||
The @code{ntp_adjtime} function sets the structure specified by
|
||||
@var{tptr} to current values. In addition, values passed in @var{tptr}
|
||||
can be used to replace existing settings. To do this the @code{modes}
|
||||
element of the @code{struct timex} must be set appropriately. Setting
|
||||
it to zero selects reading the current state.
|
||||
|
||||
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 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. Another reason could be that the specified new values
|
||||
are not allowed.
|
||||
@end table
|
||||
|
||||
For more details see RFC1305 (Network Time Protocol, Version 3) and
|
||||
related documents.
|
||||
@end deftypefun
|
||||
|
||||
|
||||
@node Setting an Alarm
|
||||
@section Setting an Alarm
|
||||
|
||||
@ -2263,4 +2399,3 @@ be protected using cancellation handlers.
|
||||
|
||||
The @code{nanosleep} function is declared in @file{time.h}.
|
||||
@end deftypefun
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user