1.\" $NetBSD: ntp_adjtime.2,v 1.4 2002/10/01 18:10:45 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.\" 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. 64The time offset and related variables which are 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). 123Bitwise OR of the following: 124.Bl -tag -width MOD_TIMECONST -compact -offset indent 125.It MOD_OFFSET 126set time offset 127.It MOD_FREQUENCY 128set frequency offset 129.It MOD_MAXERROR 130set maximum time error 131.It MOD_ESTERROR 132set estimated time error 133.It MOD_STATUS 134set clock status bits 135.It MOD_TIMECONST 136set PLL time constant 137.It MOD_CLKA 138set clock A 139.It MOD_CLKB 140set clock B 141.El 142.It Fa offset 143Time offset (in microseconds), used by the PLL/FLL to adjust the 144system time in small increments (read-write). 145.It Fa freq 146Frequency offset (scaled ppm) (read-write). 147.It Fa maxerror 148Maximum error (in microseconds). 149Initialized by an 150.Fn ntp_adjtime 151call, and increased by the kernel once each second to reflect the maximum 152error bound growth (read-write). 153.It Fa esterror 154Estimated error (in microseconds). 155Set and read by 156.Fn ntp_adjtime , 157but unused by the kernel (read-write). 158.It Fa status 159System clock status bits (read-write). 160Bitwise OR of the following: 161.Bl -tag -width STA_PPSJITTER -compact -offset indent 162.It STA_PLL 163Enable PLL updates (read-write). 164.It STA_PPSFREQ 165Enable PPS freq discipline (read-write). 166.It STA_PPSTIME 167Enable PPS time discipline (read-write). 168.It STA_FLL 169Select frequency-lock mode (read-write). 170.It STA_INS 171Insert leap (read-write). 172.It STA_DEL 173Delete leap (read-write). 174.It STA_UNSYNC 175Clock unsynchronized (read-write). 176.It STA_FREQHOLD 177Hold frequency (read-write). 178.It STA_PPSSIGNAL 179PPS signal present (read-only). 180.It STA_PPSJITTER 181PPS signal jitter exceeded (read-only). 182.It STA_PPSWANDER 183PPS signal wander exceeded (read-only). 184.It STA_PPSERROR 185PPS signal calibration error (read-only). 186.It STA_CLOCKERR 187Clock hardware fault (read-only). 188.El 189.It Fa constant 190PLL time constant, determines the bandwidth, or 191.Dq stiffness , 192of the PLL (read-write). 193.It Fa precision 194Clock precision (in microseconds). 195In most cases the same as the kernel tick variable (see 196.Xr hz 9 ) . 197If a precision clock counter or external time-keeping signal is available, 198it could be much lower (and depend on the state of the signal) 199(read-only). 200.It Fa tolerance 201Maximum frequency error, or tolerance of the CPU clock oscillator (scaled 202ppm). 203Ordinarily a property of the architecture, but could change under 204the influence of external time-keeping signals (read-only). 205.It Fa ppsfreq 206PPS frequency offset produced by the frequency median filter (scaled 207ppm) (read-only). 208.It Fa jitter 209PPS jitter measured by the time median filter in microseconds 210(read-only). 211.It Fa shift 212Logarithm to base 2 of the interval duration in seconds (PPS, 213read-only). 214.It Fa stabil 215PPS stability (scaled ppm); dispersion (wander) measured by the 216frequency median filter (read-only). 217.It Fa jitcnt 218Number of seconds that have been discarded because the jitter measured 219by the time median filter exceeded the limit 220.Em MAXTIME 221(PPS, read-only). 222.It Fa calcnt 223Count of calibration intervals (PPS, read-only). 224.It Fa errcnt 225Number of calibration intervals that have been discarded because the 226wander exceeded the limit 227.Em MAXFREQ 228or where the calibration interval jitter exceeded two ticks (PPS, 229read-only). 230.It Fa stbcnt 231Number of calibration intervals that have been discarded because the 232frequency wander exceeded the limit 233.Em MAXFREQ Ns /4 234(PPS, read-only). 235.El 236After the 237.Fn ntp_adjtime 238call, the 239.Va struct timex * 240structure contains the current values of the corresponding variables. 241.Pp 242.Fn ntp_gettime 243has as argument a 244.Va struct ntptimeval * 245with the following members: 246.Bd -literal 247struct ntptimeval { 248 struct timeval time; /* current time (ro) */ 249 long maxerror; /* maximum error (us) (ro) */ 250 long esterror; /* estimated error (us) (ro) */ 251}; 252.Ed 253.Pp 254These have the following meaning: 255.Bl -tag -width tolerance -compact 256.It Fa time 257Current time (read-only). 258.It Fa maxerror 259Maximum error in microseconds (read-only). 260.It Fa esterror 261Estimated error in microseconds (read-only). 262.El 263.Sh RETURN VALUES 264.Fn ntp_adjtime 265and 266.Fn ntp_gettime 267return the current state of the clock on success, or any of the errors 268of 269.Xr copyin 9 270and 271.Xr copyout 9 . 272.Fn ntp_adjtime 273may additionally return 274.Er EPERM 275if the user calling 276.Fn ntp_adjtime 277does not have sufficient permissions. 278.Pp 279Possible states of the clock are: 280.Bl -tag -width TIME_ERROR -compact -offset indent 281.It TIME_OK 282Everything okay, no leap second warning. 283.It TIME_INS 284.Dq insert leap second 285warning. 286.It TIME_DEL 287.Dq delete leap second 288warning. 289.It TIME_OOP 290Leap second in progress. 291.It TIME_WAIT 292Leap second has occurred. 293.It TIME_ERROR 294Clock not synchronized. 295.El 296.Sh SEE ALSO 297.Xr options 4 , 298.Xr ntpd 8 , 299.Xr hardclock 9 , 300.Xr hz 9 301