Unix/Linux Go Back    


NetBSD 6.1.5 - man page for ntp_gettime (netbsd section 2)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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/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 exter-
     nally derived time.  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 sig-
		nal 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.

BSD					 October 22, 2007				      BSD
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 07:52 AM.