*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->NetBSD man pages -> ntp_gettime (2)              



NAME    [Toc]    [Back]

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

LIBRARY    [Toc]    [Back]

     Standard C Library (libc, -lc)

SYNOPSIS    [Toc]    [Back]

     #include <sys/timex.h>

     ntp_adjtime(struct timex *);

     ntp_gettime(struct ntptimeval *);

DESCRIPTION    [Toc]    [Back]

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

     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 timekeeping
 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
                because the wander exceeded the limit MAXFREQ or where the
                calibration interval jitter exceeded two ticks (PPS, readonly).

     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

     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    [Toc]    [Back]

     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    [Toc]    [Back]

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

BSD                            September 4, 2001                           BSD
[ Back ]
 Similar pages
Name OS Title
ntpd FreeBSD Network Time Protocol (NTP) daemon
xntpd HP-UX Network Time Protocol daemon
xntpd Tru64 Network Time Protocol (NTP) daemon
ntpd OpenBSD Network Time Protocol daemon
ntp.conf FreeBSD Network Time Protocol (NTP) daemon configuration file
ntpd.conf OpenBSD Network Time Protocol daemon configuration file
xntpdc Tru64 Monitor and control program for the Network Time Protocol daemon
ntp Tru64 query a clock running a Network Time Protocol daemon, either ntpd or xntpd
ntpdate Tru64 set the date and time via NTP (Network Time Protocol)
peer_snmpd IRIX Simple Network Management Protocol daemon
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service