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