ntp_gettime (2)

Leading comments

	$NetBSD: ntp_adjtime.2,v 1.6 2003/04/16 13:34:55 wiz Exp $

 Copyright (c) 2001 The NetBSD Foundation, Inc.
 All rights reserved.

 This code is derived from software contributed to The NetBSD Foundation
 by Thomas Klausner.

 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions
 are met:
 1. Redistributions of source code must retain the above copyright
    notice, this list of conditions and the following dis...

(The comments found at the beginning of the groff file "man2/ntp_gettime.2freebsd".)

NAME

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

LIBRARY

Lb libc

SYNOPSIS

In sys/timex.h Ft int Fn ntp_adjtime struct timex * Ft int Fn ntp_gettime struct ntptimeval *

DESCRIPTION

The two system calls Fn ntp_adjtime and Fn ntp_gettime are the kernel interface to the Network Time Protocol (NTP) daemon ntpd(8).

The Fn 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 Fn ntp_adjtime are used by Fn hardclock to adjust the phase and frequency of the phase- or frequency-lock loop (PLL resp. FLL) which controls the system clock.

The Fn 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 is enabled in the kernel.

Fn 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 Fn ntp_adjtime :

Fa modes

Defines what settings should be changed with the current Fn 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

Fa offset

Time offset (in microseconds), used by the PLL/FLL to adjust the system time in small increments (read-write).

Fa freq

Frequency offset (scaled ppm) (read-write).

Fa maxerror

Maximum error (in microseconds). Initialized by an Fn ntp_adjtime call, and increased by the kernel once each second to reflect the maximum error bound growth (read-write).

Fa esterror

Estimated error (in microseconds). Set and read by Fn ntp_adjtime , but unused by the kernel (read-write).

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

Fa constant

PLL time constant, determines the bandwidth, or ``stiffness'' of the PLL (read-write).

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

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

Fa ppsfreq

PPS frequency offset produced by the frequency median filter (scaled ppm) (read-only).

Fa jitter

PPS jitter measured by the time median filter in microseconds (read-only).

Fa shift

Logarithm to base 2 of the interval duration in seconds (PPS, read-only).

Fa stabil

PPS stability (scaled ppm); dispersion (wander) measured by the frequency median filter (read-only).

Fa jitcnt

Number of seconds that have been discarded because the jitter measured by the time median filter exceeded the limit MAXTIME (PPS, read-only).

Fa calcnt

Count of calibration intervals (PPS, read-only).

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

Fa stbcnt

Number of calibration intervals that have been discarded because the frequency wander exceeded the limit MAXFREQ /4 (PPS, read-only).

After the Fn ntp_adjtime call, the struct timex structure contains the current values of the corresponding variables.

Fn 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:

Fa time

Current time (read-only).

Fa maxerror

Maximum error in microseconds (read-only).

Fa esterror

Estimated error in microseconds (read-only).

RETURN VALUES

Fn ntp_adjtime and Fn ntp_gettime return the current state of the clock on success, or any of the errors of copyin(9) and copyout(9). Fn ntp_adjtime may additionally return Er EPERM if the user calling Fn 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 Fn ntp_adjtime system call may return Er EPERM if the caller does not have sufficient permissions.

SEE ALSO

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

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

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.