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