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.
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
38 .Nd Network Time Protocol (NTP) daemon interface system calls
44 .Fn ntp_adjtime "struct timex *"
46 .Fn ntp_gettime "struct ntptimeval *"
52 are the kernel interface to the Network Time Protocol (NTP) daemon
57 function is used by the NTP daemon to adjust the system clock to an
58 externally derived time.
59 The time offset and related variables which are set by
63 to adjust the phase and frequency of the phase- or frequency-lock loop
64 (PLL resp. FLL) which controls the system clock.
68 function provides the time, maximum error (sync distance) and
69 estimated error (dispersion) to client user application programs.
71 In the following, all variables that refer PPS are only relevant if
74 option is enabled in the kernel.
79 of the following form:
82 unsigned int modes; /* clock mode bits (wo) */
83 long offset; /* time offset (us) (rw) */
84 long freq; /* frequency offset (scaled ppm) (rw) */
85 long maxerror; /* maximum error (us) (rw) */
86 long esterror; /* estimated error (us) (rw) */
87 int status; /* clock status bits (rw) */
88 long constant; /* pll time constant (rw) */
89 long precision; /* clock precision (us) (ro) */
90 long tolerance; /* clock frequency tolerance (scaled
93 * The following read-only structure members are implemented
94 * only if the PPS signal discipline is configured in the
97 long ppsfreq; /* pps frequency (scaled ppm) (ro) */
98 long jitter; /* pps jitter (us) (ro) */
99 int shift; /* interval duration (s) (shift) (ro) */
100 long stabil; /* pps stability (scaled ppm) (ro) */
101 long jitcnt; /* jitter limit exceeded (ro) */
102 long calcnt; /* calibration intervals (ro) */
103 long errcnt; /* calibration errors (ro) */
104 long stbcnt; /* stability limit exceeded (ro) */
108 The members of this struct have the following meanings when used as
111 .Bl -tag -width tolerance -compact
113 Defines what settings should be changed with the current
116 Bitwise OR of the following:
117 .Bl -tag -width MOD_TIMECONST -compact -offset indent
123 set maximum time error
125 set estimated time error
127 set clock status bits
129 set PLL time constant
136 Time offset (in microseconds), used by the PLL/FLL to adjust the
137 system time in small increments (read-write).
139 Frequency offset (scaled ppm) (read-write).
141 Maximum error (in microseconds).
144 call, and increased by the kernel once each second to reflect the maximum
145 error bound growth (read-write).
147 Estimated error (in microseconds).
150 but unused by the kernel (read-write).
152 System clock status bits (read-write).
153 Bitwise OR of the following:
154 .Bl -tag -width STA_PPSJITTER -compact -offset indent
156 Enable PLL updates (read-write).
158 Enable PPS freq discipline (read-write).
160 Enable PPS time discipline (read-write).
162 Select frequency-lock mode (read-write).
164 Insert leap (read-write).
166 Delete leap (read-write).
168 Clock unsynchronized (read-write).
170 Hold frequency (read-write).
172 PPS signal present (read-only).
174 PPS signal jitter exceeded (read-only).
176 PPS signal wander exceeded (read-only).
178 PPS signal calibration error (read-only).
180 Clock hardware fault (read-only).
183 PLL time constant, determines the bandwidth, or
185 of the PLL (read-write).
187 Clock precision (in microseconds).
188 In most cases the same as the kernel tick variable (see
190 If a precision clock counter or external time-keeping signal is available,
191 it could be much lower (and depend on the state of the signal)
194 Maximum frequency error, or tolerance of the CPU clock oscillator (scaled
196 Ordinarily a property of the architecture, but could change under
197 the influence of external time-keeping signals (read-only).
199 PPS frequency offset produced by the frequency median filter (scaled
202 PPS jitter measured by the time median filter in microseconds
205 Logarithm to base 2 of the interval duration in seconds (PPS,
208 PPS stability (scaled ppm); dispersion (wander) measured by the
209 frequency median filter (read-only).
211 Number of seconds that have been discarded because the jitter measured
212 by the time median filter exceeded the limit
216 Count of calibration intervals (PPS, read-only).
218 Number of calibration intervals that have been discarded because the
219 wander exceeded the limit
221 or where the calibration interval jitter exceeded two ticks (PPS,
224 Number of calibration intervals that have been discarded because the
225 frequency wander exceeded the limit
233 structure contains the current values of the corresponding variables.
237 .Va struct ntptimeval *
238 with the following members:
241 struct timeval time; /* current time (ro) */
242 long maxerror; /* maximum error (us) (ro) */
243 long esterror; /* estimated error (us) (ro) */
247 These have the following meaning:
248 .Bl -tag -width tolerance -compact
250 Current time (read-only).
252 Maximum error in microseconds (read-only).
254 Estimated error in microseconds (read-only).
260 return the current state of the clock on success, or any of the errors
266 may additionally return
270 does not have sufficient permissions.
272 Possible states of the clock are:
273 .Bl -tag -width TIME_ERROR -compact -offset indent
275 Everything okay, no leap second warning.
277 .Dq insert leap second
279 At the end of the day, a leap second will be inserted after 23:59:59.
281 .Dq delete leap second
283 At the end of the day, second 23:59:59 will be skipped.
285 Leap second in progress.
287 Leap second has occurred within the last few seconds.
289 Clock not synchronized.
294 system call may return
297 does not have sufficient permissions.
303 .Bl -tag -width indent
304 .It Pa http://www.bipm.fr/enus/5_Scientific/c_time/time_1.html
305 .It Pa http://www.boulder.nist.gov/timefreq/general/faq.htm
306 .It Pa ftp://time.nist.gov/pub/leap-seconds.list
311 is extremely complex and stateful.
312 Users should not attempt modification without first