NTP_ADJTIME(2)						      BSD 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/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 pro-
     grams.

     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():
     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 timeval time;    /* current time (ro) */
	     long maxerror;	     /* maximum error (us) (ro) */
	     long esterror;	     /* estimated error (us) (ro) */
     };

     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.	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 EPERM if the caller does not have sufficient permissions.

SEE ALSO

     options(4), ntpd(8), hardclock(9), hz(9)

     http://www.bipm.fr/enus/5_Scientific/c_time/time_1.html

     http://www.boulder.nist.gov/timefreq/general/faq.htm

     ftp://time.nist.gov/pub/leap-seconds.list

BUGS

     Take note that this API is extremely complex and stateful.  Users should not attempt modification without first reviewing the ntpd(8) sources
     in depth.

BSD
								   July 13, 2005							       BSD