Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
NTP_ADJTIME(2)		    BSD	System Calls Manual		NTP_ADJTIME(2)

     ntp_adjtime, ntp_gettime -- Network Time Protocol (NTP) daemon interface
     system calls

     Standard C	Library	(libc, -lc)

     #include <sys/time.h>
     #include <sys/timex.h>

     ntp_adjtime(struct	timex *);

     ntp_gettime(struct	ntptimeval *);

     The two system calls ntp_adjtime()	and ntp_gettime() are the kernel in-
     terface 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 vari-
     ables 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 dis-
     tance) and	estimated error	(dispersion) to	client user application	pro-

     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 argu-
     ment 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 sec-
		ond 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 fol-
		      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-
     tolerance	Maximum	frequency error, or tolerance of the CPU clock oscil-
		lator (scaled ppm).  Ordinarily	a property of the architec-
		ture, 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
     shift	Logarithm to base 2 of the interval duration in	seconds	(PPS,
     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 be-
		cause the wander exceeded the limit MAXFREQ or where the cali-
		bration	interval jitter	exceeded two ticks (PPS, read-only).
     stbcnt	Number of calibration intervals	that have been discarded be-
		cause the frequency wander exceeded the	limit MAXFREQ/4	(PPS,
     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

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

     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.

     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.

BSD			       October 22, 2007				   BSD


Want to link to this manual page? Use this URL:

home | help