1 .\" $NetBSD: ntp_adjtime.2,v 1.6 2003/04/16 13:34:55 wiz Exp $
3 .\" Copyright (c) 2001 The NetBSD Foundation, Inc.
4 .\" All rights reserved.
6 .\" This code is derived from software contributed to The NetBSD Foundation
7 .\" by Thomas Klausner.
9 .\" Redistribution and use in source and binary forms, with or without
10 .\" modification, are permitted provided that the following conditions
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.
25 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
26 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
27 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
28 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
29 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
30 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
31 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
32 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
33 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
34 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
45 .Nd Network Time Protocol (NTP) daemon interface system calls
51 .Fn ntp_adjtime "struct timex *"
53 .Fn ntp_gettime "struct ntptimeval *"
59 are the kernel interface to the Network Time Protocol (NTP) daemon
64 function is used by the NTP daemon to adjust the system clock to an
65 externally derived time.
66 The time offset and related variables which are set by
70 to adjust the phase and frequency of the phase- or frequency-lock loop
71 (PLL resp. FLL) which controls the system clock.
75 function provides the time, maximum error (sync distance) and
76 estimated error (dispersion) to client user application programs.
78 In the following, all variables that refer PPS are only relevant if
81 option is enabled in the kernel.
86 of the following form:
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
100 * The following read-only structure members are implemented
101 * only if the PPS signal discipline is configured in the
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) */
115 The members of this struct have the following meanings when used as
118 .Bl -tag -width tolerance -compact
120 Defines what settings should be changed with the current
123 Bitwise OR of the following:
124 .Bl -tag -width MOD_TIMECONST -compact -offset indent
130 set maximum time error
132 set estimated time error
134 set clock status bits
136 set PLL time constant
143 Time offset (in microseconds), used by the PLL/FLL to adjust the
144 system time in small increments (read-write).
146 Frequency offset (scaled ppm) (read-write).
148 Maximum error (in microseconds).
151 call, and increased by the kernel once each second to reflect the maximum
152 error bound growth (read-write).
154 Estimated error (in microseconds).
157 but unused by the kernel (read-write).
159 System clock status bits (read-write).
160 Bitwise OR of the following:
161 .Bl -tag -width STA_PPSJITTER -compact -offset indent
163 Enable PLL updates (read-write).
165 Enable PPS freq discipline (read-write).
167 Enable PPS time discipline (read-write).
169 Select frequency-lock mode (read-write).
171 Insert leap (read-write).
173 Delete leap (read-write).
175 Clock unsynchronized (read-write).
177 Hold frequency (read-write).
179 PPS signal present (read-only).
181 PPS signal jitter exceeded (read-only).
183 PPS signal wander exceeded (read-only).
185 PPS signal calibration error (read-only).
187 Clock hardware fault (read-only).
190 PLL time constant, determines the bandwidth, or
192 of the PLL (read-write).
194 Clock precision (in microseconds).
195 In most cases the same as the kernel tick variable (see
197 If a precision clock counter or external time-keeping signal is available,
198 it could be much lower (and depend on the state of the signal)
201 Maximum frequency error, or tolerance of the CPU clock oscillator (scaled
203 Ordinarily a property of the architecture, but could change under
204 the influence of external time-keeping signals (read-only).
206 PPS frequency offset produced by the frequency median filter (scaled
209 PPS jitter measured by the time median filter in microseconds
212 Logarithm to base 2 of the interval duration in seconds (PPS,
215 PPS stability (scaled ppm); dispersion (wander) measured by the
216 frequency median filter (read-only).
218 Number of seconds that have been discarded because the jitter measured
219 by the time median filter exceeded the limit
223 Count of calibration intervals (PPS, read-only).
225 Number of calibration intervals that have been discarded because the
226 wander exceeded the limit
228 or where the calibration interval jitter exceeded two ticks (PPS,
231 Number of calibration intervals that have been discarded because the
232 frequency wander exceeded the limit
240 structure contains the current values of the corresponding variables.
244 .Va struct ntptimeval *
245 with the following members:
248 struct timeval time; /* current time (ro) */
249 long maxerror; /* maximum error (us) (ro) */
250 long esterror; /* estimated error (us) (ro) */
254 These have the following meaning:
255 .Bl -tag -width tolerance -compact
257 Current time (read-only).
259 Maximum error in microseconds (read-only).
261 Estimated error in microseconds (read-only).
267 return the current state of the clock on success, or any of the errors
273 may additionally return
277 does not have sufficient permissions.
279 Possible states of the clock are:
280 .Bl -tag -width TIME_ERROR -compact -offset indent
282 Everything okay, no leap second warning.
284 .Dq insert leap second
286 At the end of the day, a leap second will be inserted after 23:59:59.
288 .Dq delete leap second
290 At the end of the day, second 23:59:59 will be skipped.
292 Leap second in progress.
294 Leap second has occurred within the last few seconds..
296 Clock not synchronized.
301 system call may return
304 does not have sufficient permissions.
310 .Bl -tag -width indent
311 .It Pa http://www.bipm.fr/enus/5_Scientific/c_time/time_1.html
312 .It Pa http://www.boulder.nist.gov/timefreq/general/faq.htm
313 .It Pa ftp://time.nist.gov/pub/leap-seconds.list
318 is extremely complex and stateful.
319 Users should not attempt modification without first