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