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