1.\" $NetBSD: ntp_adjtime.2,v 1.3 2002/02/08 01:28:20 ross Exp $ 2.\" 3.\" Copyright (c) 2001 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Thomas Klausner. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd September 4, 2001 38.Dt NTP_ADJTIME 2 39.Os 40.Sh NAME 41.Nm ntp_adjtime , 42.Nm ntp_gettime 43.Nd Network Time Protocol (NTP) daemon interface system calls 44.Sh LIBRARY 45.Lb libc 46.Sh SYNOPSIS 47.Fd #include \*[Lt]sys/timex.h\*[Gt] 48.Ft int 49.Fn ntp_adjtime "struct timex *" 50.Ft int 51.Fn ntp_gettime "struct ntptimeval *" 52.Sh DESCRIPTION 53The two system calls 54.Fn ntp_adjtime 55and 56.Fn ntp_gettime 57are the kernel interface to the Network Time Protocol (NTP) daemon 58.Xr ntpd 8 . 59.Pp 60The 61.Fn ntp_adjtime 62function is used by the NTP daemon to adjust the system clock to an 63externally derived time. The time offset and related variables which 64are set by 65.Fn ntp_adjtime 66are used by 67.Xr hardclock 9 68to adjust the phase and frequency of the phase- or frequency-lock loop 69(PLL resp. FLL) which controls the system clock. 70.Pp 71The 72.Fn ntp_gettime 73function provides the time, maximum error (sync distance) and 74estimated error (dispersion) to client user application programs. 75.Pp 76In the following, all variables that refer PPS are only relevant if 77the 78.Em PPS_SYNC 79option (see 80.Xr options 4 ) 81is enabled in the kernel. 82.Pp 83.Fn ntp_adjtime 84has as argument a 85.Va struct timex * 86of the following form: 87.Bd -literal 88struct timex { 89 unsigned int modes; /* clock mode bits (wo) */ 90 long offset; /* time offset (us) (rw) */ 91 long freq; /* frequency offset (scaled ppm) (rw) */ 92 long maxerror; /* maximum error (us) (rw) */ 93 long esterror; /* estimated error (us) (rw) */ 94 int status; /* clock status bits (rw) */ 95 long constant; /* pll time constant (rw) */ 96 long precision; /* clock precision (us) (ro) */ 97 long tolerance; /* clock frequency tolerance (scaled 98 * ppm) (ro) */ 99 /* 100 * The following read-only structure members are implemented 101 * only if the PPS signal discipline is configured in the 102 * kernel. 103 */ 104 long ppsfreq; /* pps frequency (scaled ppm) (ro) */ 105 long jitter; /* pps jitter (us) (ro) */ 106 int shift; /* interval duration (s) (shift) (ro) */ 107 long stabil; /* pps stability (scaled ppm) (ro) */ 108 long jitcnt; /* jitter limit exceeded (ro) */ 109 long calcnt; /* calibration intervals (ro) */ 110 long errcnt; /* calibration errors (ro) */ 111 long stbcnt; /* stability limit exceeded (ro) */ 112}; 113.Ed 114.Pp 115The members of this struct have the following meanings when used as 116argument for 117.Fn ntp_adjtime : 118.Bl -tag -width tolerance -compact 119.It Fa modes 120Defines what settings should be changed with the current 121.Fn ntp_adjtime 122call (write-only). Bitwise OR of the following: 123.Bl -tag -width MOD_TIMECONST -compact -offset indent 124.It MOD_OFFSET 125set time offset 126.It MOD_FREQUENCY 127set frequency offset 128.It MOD_MAXERROR 129set maximum time error 130.It MOD_ESTERROR 131set estimated time error 132.It MOD_STATUS 133set clock status bits 134.It MOD_TIMECONST 135set PLL time constant 136.It MOD_CLKA 137set clock A 138.It MOD_CLKB 139set clock B 140.El 141.It Fa offset 142Time offset (in microseconds), used by the PLL/FLL to adjust the 143system time in small increments (read-write). 144.It Fa freq 145Frequency offset (scaled ppm) (read-write). 146.It Fa maxerror 147Maximum error (in microseconds). Initialized by an 148.Fn ntp_adjtime 149call, and increased by the kernel once each second to reflect the maximum 150error bound growth (read-write). 151.It Fa esterror 152Estimated error (in microseconds). Set and read by 153.Fn ntp_adjtime , 154but unused by the kernel (read-write). 155.It Fa status 156System clock status bits (read-write). Bitwise OR of the following: 157.Bl -tag -width STA_PPSJITTER -compact -offset indent 158.It STA_PLL 159Enable PLL updates (read-write). 160.It STA_PPSFREQ 161Enable PPS freq discipline (read-write). 162.It STA_PPSTIME 163Enable PPS time discipline (read-write). 164.It STA_FLL 165Select frequency-lock mode (read-write). 166.It STA_INS 167Insert leap (read-write). 168.It STA_DEL 169Delete leap (read-write). 170.It STA_UNSYNC 171Clock unsynchronized (read-write). 172.It STA_FREQHOLD 173Hold frequency (read-write). 174.It STA_PPSSIGNAL 175PPS signal present (read-only). 176.It STA_PPSJITTER 177PPS signal jitter exceeded (read-only). 178.It STA_PPSWANDER 179PPS signal wander exceeded (read-only). 180.It STA_PPSERROR 181PPS signal calibration error (read-only). 182.It STA_CLOCKERR 183Clock hardware fault (read-only). 184.El 185.It Fa constant 186PLL time constant, determines the bandwidth, or 187.Dq stiffness , 188of the PLL (read-write). 189.It Fa precision 190Clock precision (in microseconds). In most cases the same 191as the kernel tick variable (see 192.Xr hz 9 ) . 193If a precision clock counter or external time-keeping signal is available, 194it could be much lower (and depend on the state of the signal) 195(read-only). 196.It Fa tolerance 197Maximum frequency error, or tolerance of the CPU clock oscillator (scaled 198ppm). Ordinarily a property of the architecture, but could change under 199the influence of external time-keeping signals (read-only). 200.It Fa ppsfreq 201PPS frequency offset produced by the frequency median filter (scaled 202ppm) (read-only). 203.It Fa jitter 204PPS jitter measured by the time median filter in microseconds 205(read-only). 206.It Fa shift 207Logarithm to base 2 of the interval duration in seconds (PPS, 208read-only). 209.It Fa stabil 210PPS stability (scaled ppm); dispersion (wander) measured by the 211frequency median filter (read-only). 212.It Fa jitcnt 213Number of seconds that have been discarded because the jitter measured 214by the time median filter exceeded the limit 215.Em MAXTIME 216(PPS, read-only). 217.It Fa calcnt 218Count of calibration intervals (PPS, read-only). 219.It Fa errcnt 220Number of calibration intervals that have been discarded because the 221wander exceeded the limit 222.Em MAXFREQ 223or where the calibration interval jitter exceeded two ticks (PPS, 224read-only). 225.It Fa stbcnt 226Number of calibration intervals that have been discarded because the 227frequency wander exceeded the limit 228.Em MAXFREQ Ns /4 229(PPS, read-only). 230.El 231After the 232.Fn ntp_adjtime 233call, the 234.Va struct timex * 235structure contains the current values of the corresponding variables. 236.Pp 237.Fn ntp_gettime 238has as argument a 239.Va struct ntptimeval * 240with the following members: 241.Bd -literal 242struct ntptimeval { 243 struct timeval time; /* current time (ro) */ 244 long maxerror; /* maximum error (us) (ro) */ 245 long esterror; /* estimated error (us) (ro) */ 246}; 247.Ed 248.Pp 249These have the following meaning: 250.Bl -tag -width tolerance -compact 251.It Fa time 252Current time (read-only). 253.It Fa maxerror 254Maximum error in microseconds (read-only). 255.It Fa esterror 256Estimated error in microseconds (read-only). 257.El 258.Sh RETURN VALUES 259.Fn ntp_adjtime 260and 261.Fn ntp_gettime 262return the current state of the clock on success, or any of the errors 263of 264.Xr copyin 9 265and 266.Xr copyout 9 . 267.Fn ntp_adjtime 268may additionally return 269.Er EPERM 270if the user calling 271.Fn ntp_adjtime 272does not have sufficient permissions. 273.Pp 274Possible states of the clock are: 275.Bl -tag -width TIME_ERROR -compact -offset indent 276.It TIME_OK 277Everything okay, no leap second warning. 278.It TIME_INS 279.Dq insert leap second 280warning. 281.It TIME_DEL 282.Dq delete leap second 283warning. 284.It TIME_OOP 285Leap second in progress. 286.It TIME_WAIT 287Leap second has occurred. 288.It TIME_ERROR 289Clock not synchronized. 290.El 291.Sh SEE ALSO 292.Xr options 4 , 293.Xr ntpd 8 , 294.Xr hardclock 9 , 295.Xr hz 9 296