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