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