ntp_adjtimentp_gettime
- Network Time Protocol (NTP) daemon interface system calls
LIBRARY
Lb libc
SYNOPSIS
#include <sys/timex.h> int
ntp_adjtime (struct timex *); int
ntp_gettime (struct ntptimeval *);
DESCRIPTION
The two system calls
ntp_adjtime ();
and
ntp_gettime ();
are the kernel interface to the Network Time Protocol (NTP) daemon
ntpd(8).
The
ntp_adjtime ();
function is used by the NTP daemon to adjust the system clock to an
externally derived time.
The time offset and related variables which are set by
ntp_adjtime ();
are used by
hardclock ();
to adjust the phase and frequency of the phase- or frequency-lock loop
(PLL resp. FLL) which controls the system clock.
The
ntp_gettime ();
function provides the time, maximum error (sync distance) and
estimated error (dispersion) to client user application programs.
In the following, all variables that refer PPS are only relevant if
the
PPS_SYNC
option is enabled in the kernel.
ntp_adjtime ();
has as argument a
struct timex
of the following form:
struct timex {
unsigned int modes; /* clock mode bits (wo) */
long offset; /* time offset (us) (rw) */
long freq; /* frequency offset (scaled ppm) (rw) */
long maxerror; /* maximum error (us) (rw) */
long esterror; /* estimated error (us) (rw) */
int status; /* clock status bits (rw) */
long constant; /* pll time constant (rw) */
long precision; /* clock precision (us) (ro) */
long tolerance; /* clock frequency tolerance (scaled
* ppm) (ro) */
/*
* The following read-only structure members are implemented
* only if the PPS signal discipline is configured in the
* kernel.
*/
long ppsfreq; /* pps frequency (scaled ppm) (ro) */
long jitter; /* pps jitter (us) (ro) */
int shift; /* interval duration (s) (shift) (ro) */
long stabil; /* pps stability (scaled ppm) (ro) */
long jitcnt; /* jitter limit exceeded (ro) */
long calcnt; /* calibration intervals (ro) */
long errcnt; /* calibration errors (ro) */
long stbcnt; /* stability limit exceeded (ro) */
};
The members of this struct have the following meanings when used as
argument for
ntp_adjtime (:);
Fa modes
Defines what settings should be changed with the current
ntp_adjtime ();
call (write-only).
Bitwise OR of the following:
MOD_OFFSET
set time offset
MOD_FREQUENCY
set frequency offset
MOD_MAXERROR
set maximum time error
MOD_ESTERROR
set estimated time error
MOD_STATUS
set clock status bits
MOD_TIMECONST
set PLL time constant
MOD_CLKA
set clock A
MOD_CLKB
set clock B
Fa offset
Time offset (in microseconds), used by the PLL/FLL to adjust the
system time in small increments (read-write).
Fa freq
Frequency offset (scaled ppm) (read-write).
Fa maxerror
Maximum error (in microseconds).
Initialized by an
ntp_adjtime ();
call, and increased by the kernel once each second to reflect the maximum
error bound growth (read-write).
Fa esterror
Estimated error (in microseconds).
Set and read by
ntp_adjtime (,);
but unused by the kernel (read-write).
Fa status
System clock status bits (read-write).
Bitwise OR of the following:
STA_PLL
Enable PLL updates (read-write).
STA_PPSFREQ
Enable PPS freq discipline (read-write).
STA_PPSTIME
Enable PPS time discipline (read-write).
STA_FLL
Select frequency-lock mode (read-write).
STA_INS
Insert leap (read-write).
STA_DEL
Delete leap (read-write).
STA_UNSYNC
Clock unsynchronized (read-write).
STA_FREQHOLD
Hold frequency (read-write).
STA_PPSSIGNAL
PPS signal present (read-only).
STA_PPSJITTER
PPS signal jitter exceeded (read-only).
STA_PPSWANDER
PPS signal wander exceeded (read-only).
STA_PPSERROR
PPS signal calibration error (read-only).
STA_CLOCKERR
Clock hardware fault (read-only).
Fa constant
PLL time constant, determines the bandwidth, or
``stiffness''
of the PLL (read-write).
Fa precision
Clock precision (in microseconds).
In most cases the same as the kernel tick variable (see
hz(9)).
If a precision clock counter or external time-keeping signal is available,
it could be much lower (and depend on the state of the signal)
(read-only).
Fa tolerance
Maximum frequency error, or tolerance of the CPU clock oscillator (scaled
ppm).
Ordinarily a property of the architecture, but could change under
the influence of external time-keeping signals (read-only).
Fa ppsfreq
PPS frequency offset produced by the frequency median filter (scaled
ppm) (read-only).
Fa jitter
PPS jitter measured by the time median filter in microseconds
(read-only).
Fa shift
Logarithm to base 2 of the interval duration in seconds (PPS,
read-only).
Fa stabil
PPS stability (scaled ppm); dispersion (wander) measured by the
frequency median filter (read-only).
Fa jitcnt
Number of seconds that have been discarded because the jitter measured
by the time median filter exceeded the limit
MAXTIME
(PPS, read-only).
Fa calcnt
Count of calibration intervals (PPS, read-only).
Fa errcnt
Number of calibration intervals that have been discarded because the
wander exceeded the limit
MAXFREQ
or where the calibration interval jitter exceeded two ticks (PPS,
read-only).
Fa stbcnt
Number of calibration intervals that have been discarded because the
frequency wander exceeded the limit
MAXFREQ /4
(PPS, read-only).
After the
ntp_adjtime ();
call, the
struct timex
structure contains the current values of the corresponding variables.
ntp_gettime ();
has as argument a
struct ntptimeval
with the following members:
struct ntptimeval {
struct timeval time; /* current time (ro) */
long maxerror; /* maximum error (us) (ro) */
long esterror; /* estimated error (us) (ro) */
};
These have the following meaning:
Fa time
Current time (read-only).
Fa maxerror
Maximum error in microseconds (read-only).
Fa esterror
Estimated error in microseconds (read-only).
RETURN VALUES
ntp_adjtime ();
and
ntp_gettime ();
return the current state of the clock on success, or any of the errors
of
copyin(9)
and
copyout(9).
ntp_adjtime ();
may additionally return
Er EPERM
if the user calling
ntp_adjtime ();
does not have sufficient permissions.
Possible states of the clock are:
TIME_OK
Everything okay, no leap second warning.
TIME_INS
``insert leap second''
warning.
At the end of the day, a leap second will be inserted after 23:59:59.
TIME_DEL
``delete leap second''
warning.
At the end of the day, second 23:59:59 will be skipped.
TIME_OOP
Leap second in progress.
TIME_WAIT
Leap second has occurred within the last few seconds..
TIME_ERROR
Clock not synchronized.
ERRORS
The
ntp_adjtime ();
system call may return
Er EPERM
if the caller
does not have sufficient permissions.
