NTP_ADJTIME(2)            NetBSD 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 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-
     grams.

     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-
                lowing:
                      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 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
                (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.

NetBSD 5.0_STABLE              September 4, 2001             NetBSD 5.0_STABLE
