NAME
ntp_adjtime,
ntp_gettime —
Network Time Protocol (NTP) daemon interface system
calls
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#include <sys/time.h>
#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
ntp_adjtime() system call is available only for the super
user. If the system call fails, the
ntp_adjtime() function
in the standard C library will try to use the
clockctl(4) device if present,
thus making it possible for the NTP daemon to run as a non-privileged user. If
clockctl(4) is not present,
ntp_adjtime() returns
EPERM
.
The time offset and related variables which are set by
ntp_adjtime() are used by
hardclock(9) 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 (see
options(4)) 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():
- 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
- offset
- Time offset (in microseconds), used by the PLL/FLL to
adjust the system time in small increments (read-write).
- freq
- Frequency offset (scaled ppm) (read-write).
- 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).
- esterror
- Estimated error (in microseconds). Set and read by
ntp_adjtime(), but unused by the kernel
(read-write).
- 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).
- constant
- PLL time constant, determines the bandwidth, or
“stiffness”, of the PLL (read-write).
- 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).
- 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).
- ppsfreq
- PPS frequency offset produced by the frequency median
filter (scaled ppm) (read-only).
- jitter
- PPS jitter measured by the time median filter in
microseconds (read-only).
- shift
- Logarithm to base 2 of the interval duration in seconds
(PPS, read-only).
- stabil
- PPS stability (scaled ppm); dispersion (wander) measured by
the frequency median filter (read-only).
- jitcnt
- Number of seconds that have been discarded because the
jitter measured by the time median filter exceeded the limit
MAXTIME (PPS, read-only).
- calcnt
- Count of calibration intervals (PPS, read-only).
- 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).
- 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 timespec time; /* current time (ro) */
long maxerror; /* maximum error (us) (ro) */
long esterror; /* estimated error (us) (ro) */
/* the following are placeholders for now */
long tai; /* TAI offset */
int time_state; /* time status */
};
These have the following meaning:
- time
- Current time (read-only).
- maxerror
- Maximum error in microseconds (read-only).
- 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
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.
- TIME_DEL
- “delete leap second” warning.
- TIME_OOP
- Leap second in progress.
- TIME_WAIT
- Leap second has occurred.
- TIME_ERROR
- Clock not synchronized.
SEE ALSO
options(4),
ntpd(8),
hardclock(9),
hz(9)
J. Mogul, D.
Mills, J. Brittenson, J.
Stone, and U. Windl,
Pulse-Per-Second API for UNIX-like Operating Systems,
RFC 2783, March
2000.