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
36 .Nd Network Time Protocol (NTP) daemon interface system calls
42 .Fn ntp_adjtime "struct timex *"
44 .Fn ntp_gettime "struct ntptimeval *"
50 are the kernel interface to the Network Time Protocol (NTP) daemon
55 function is used by the NTP daemon to adjust the system clock to an
56 externally derived time.
57 The time offset and related variables which are set by
61 to adjust the phase and frequency of the phase- or frequency-lock loop
62 (PLL resp. FLL) which controls the system clock.
66 function provides the time, maximum error (sync distance) and
67 estimated error (dispersion) to client user application programs.
69 In the following, all variables that refer PPS are only relevant if
72 option is enabled in the kernel.
77 of the following form:
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
91 * The following read-only structure members are implemented
92 * only if the PPS signal discipline is configured in the
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) */
106 The members of this struct have the following meanings when used as
109 .Bl -tag -width tolerance -compact
111 Defines what settings should be changed with the current
114 Bitwise OR of the following:
115 .Bl -tag -width MOD_TIMECONST -compact -offset indent
121 set maximum time error
123 set estimated time error
125 set clock status bits
127 set PLL time constant
134 Time offset (in microseconds), used by the PLL/FLL to adjust the
135 system time in small increments (read-write).
137 Frequency offset (scaled ppm) (read-write).
139 Maximum error (in microseconds).
142 call, and increased by the kernel once each second to reflect the maximum
143 error bound growth (read-write).
145 Estimated error (in microseconds).
148 but unused by the kernel (read-write).
150 System clock status bits (read-write).
151 Bitwise OR of the following:
152 .Bl -tag -width STA_PPSJITTER -compact -offset indent
154 Enable PLL updates (read-write).
156 Enable PPS freq discipline (read-write).
158 Enable PPS time discipline (read-write).
160 Select frequency-lock mode (read-write).
162 Insert leap (read-write).
164 Delete leap (read-write).
166 Clock unsynchronized (read-write).
168 Hold frequency (read-write).
170 PPS signal present (read-only).
172 PPS signal jitter exceeded (read-only).
174 PPS signal wander exceeded (read-only).
176 PPS signal calibration error (read-only).
178 Clock hardware fault (read-only).
181 PLL time constant, determines the bandwidth, or
183 of the PLL (read-write).
185 Clock precision (in microseconds).
186 In most cases the same as the kernel tick variable (see
188 If a precision clock counter or external time-keeping signal is available,
189 it could be much lower (and depend on the state of the signal)
192 Maximum frequency error, or tolerance of the CPU clock oscillator (scaled
194 Ordinarily a property of the architecture, but could change under
195 the influence of external time-keeping signals (read-only).
197 PPS frequency offset produced by the frequency median filter (scaled
200 PPS jitter measured by the time median filter in microseconds
203 Logarithm to base 2 of the interval duration in seconds (PPS,
206 PPS stability (scaled ppm); dispersion (wander) measured by the
207 frequency median filter (read-only).
209 Number of seconds that have been discarded because the jitter measured
210 by the time median filter exceeded the limit
214 Count of calibration intervals (PPS, read-only).
216 Number of calibration intervals that have been discarded because the
217 wander exceeded the limit
219 or where the calibration interval jitter exceeded two ticks (PPS,
222 Number of calibration intervals that have been discarded because the
223 frequency wander exceeded the limit
231 structure contains the current values of the corresponding variables.
235 .Va struct ntptimeval *
236 with the following members:
239 struct timeval time; /* current time (ro) */
240 long maxerror; /* maximum error (us) (ro) */
241 long esterror; /* estimated error (us) (ro) */
245 These have the following meaning:
246 .Bl -tag -width tolerance -compact
248 Current time (read-only).
250 Maximum error in microseconds (read-only).
252 Estimated error in microseconds (read-only).
258 return the current state of the clock on success, or any of the errors
264 may additionally return
268 does not have sufficient permissions.
270 Possible states of the clock are:
271 .Bl -tag -width TIME_ERROR -compact -offset indent
273 Everything okay, no leap second warning.
275 .Dq insert leap second
277 At the end of the day, a leap second will be inserted after 23:59:59.
279 .Dq delete leap second
281 At the end of the day, second 23:59:59 will be skipped.
283 Leap second in progress.
285 Leap second has occurred within the last few seconds.
287 Clock not synchronized.
292 system call may return
295 does not have sufficient permissions.
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
309 is extremely complex and stateful.
310 Users should not attempt modification without first