NTP_ADJTIME(2)

NTP_ADJTIME(2) | System Calls Manual | NTP_ADJTIME(2)

# 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.

December 8, 2015 | NetBSD 8.0