Debian Codegraph @

upstream/debian-unstable/man2/adjtimex.2

raw
1 '\" t
2 .\" Copyright 1995, Michael Chastain <[email protected]>
3 .\" Copyright 2014-2016, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: GPL-2.0-or-later
7 .\"
8 .TH adjtimex 2 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 adjtimex, clock_adjtime, ntp_adjtime \- tune kernel clock
11 .SH LIBRARY
12 Standard C library
13 .RI ( libc ,\~ \-lc )
14 .SH SYNOPSIS
15 .nf
16 .B #include <sys/timex.h>
17 .P
18 .BI "int adjtimex(struct timex *" "buf" );
19 .P
20 .BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" );
21 .P
22 .BI "int ntp_adjtime(struct timex *" buf );
23 .fi
24 .SH DESCRIPTION
25 Linux uses David L.\& Mills' clock adjustment algorithm (see RFC\ 5905).
26 The system call
27 .BR adjtimex ()
28 reads and optionally sets adjustment parameters for this algorithm.
29 It takes a pointer to a
30 .I timex
31 structure, updates kernel parameters from (selected) field values,
32 and returns the same structure updated with the current kernel values.
33 This structure is declared as follows:
34 .P
35 .in +4n
36 .EX
37 struct timex {
38 int modes; /* Mode selector */
39 long offset; /* Time offset; nanoseconds, if STA_NANO
40 status flag is set, otherwise
41 microseconds */
42 long freq; /* Frequency offset; see NOTES for units */
43 long maxerror; /* Maximum error (microseconds) */
44 long esterror; /* Estimated error (microseconds) */
45 int status; /* Clock command/status */
46 long constant; /* PLL (phase\-locked loop) time constant */
47 long precision; /* Clock precision
48 (microseconds, read\-only) */
49 long tolerance; /* Clock frequency tolerance (read\-only);
50 see NOTES for units */
51 struct timeval time;
52 /* Current time (read\-only, except for
53 ADJ_SETOFFSET); upon return, time.tv_usec
54 contains nanoseconds, if STA_NANO status
55 flag is set, otherwise microseconds */
56 long tick; /* Microseconds between clock ticks */
57 long ppsfreq; /* PPS (pulse per second) frequency
58 (read\-only); see NOTES for units */
59 long jitter; /* PPS jitter (read\-only); nanoseconds, if
60 STA_NANO status flag is set, otherwise
61 microseconds */
62 int shift; /* PPS interval duration
63 (seconds, read\-only) */
64 long stabil; /* PPS stability (read\-only);
65 see NOTES for units */
66 long jitcnt; /* PPS count of jitter limit exceeded
67 events (read\-only) */
68 long calcnt; /* PPS count of calibration intervals
69 (read\-only) */
70 long errcnt; /* PPS count of calibration errors
71 (read\-only) */
72 long stbcnt; /* PPS count of stability limit exceeded
73 events (read\-only) */
74 int tai; /* TAI offset, as set by previous ADJ_TAI
75 operation (seconds, read\-only,
76 since Linux 2.6.26) */
77 /* Further padding bytes to allow for future expansion */
78 };
79 .EE
80 .in
81 .P
82 The
83 .I modes
84 field determines which parameters, if any, to set.
85 (As described later in this page,
86 the constants used for
87 .BR ntp_adjtime ()
88 are equivalent but differently named.)
89 It is a bit mask containing a
90 bitwise OR
91 combination of zero or more of the following bits:
92 .TP
93 .B ADJ_OFFSET
94 Set time offset from
95 .IR buf.offset .
96 Since Linux 2.6.26,
97 .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23
98 the supplied value is clamped to the range (\-0.5s, +0.5s).
99 In older kernels, an
100 .B EINVAL
101 error occurs if the supplied value is out of range.
102 .TP
103 .B ADJ_FREQUENCY
104 Set frequency offset from
105 .IR buf.freq .
106 Since Linux 2.6.26,
107 .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23
108 the supplied value is clamped to the range (\-32768000, +32768000).
109 In older kernels, an
110 .B EINVAL
111 error occurs if the supplied value is out of range.
112 .TP
113 .B ADJ_MAXERROR
114 Set maximum time error from
115 .IR buf.maxerror .
116 .TP
117 .B ADJ_ESTERROR
118 Set estimated time error from
119 .IR buf.esterror .
120 .TP
121 .B ADJ_STATUS
122 Set clock status bits from
123 .IR buf.status .
124 A description of these bits is provided below.
125 .TP
126 .B ADJ_TIMECONST
127 Set PLL time constant from
128 .IR buf.constant .
129 If the
130 .B STA_NANO
131 status flag (see below) is clear, the kernel adds 4 to this value.
132 .TP
133 .BR ADJ_SETOFFSET " (since Linux 2.6.39)"
134 .\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762
135 .\" Author: Richard Cochran <[email protected]>
136 Add
137 .I buf.time
138 to the current time.
139 If
140 .I buf.status
141 includes the
142 .B ADJ_NANO
143 flag, then
144 .I buf.time.tv_usec
145 is interpreted as a nanosecond value;
146 otherwise it is interpreted as microseconds.
147 .IP
148 The value of
149 .I buf.time
150 is the sum of its two fields, but the
151 field
152 .I buf.time.tv_usec
153 must always be nonnegative.
154 The following example shows how to
155 normalize a
156 .I timeval
157 with nanosecond resolution.
158 .IP
159 .in +4n
160 .EX
161 while (buf.time.tv_usec < 0) {
162 buf.time.tv_sec \-= 1;
163 buf.time.tv_usec += 1000000000;
164 }
165 .EE
166 .in
167 .TP
168 .BR ADJ_MICRO " (since Linux 2.6.26)"
169 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
170 .\" Author: Roman Zippel <[email protected]>
171 Select microsecond resolution.
172 .TP
173 .BR ADJ_NANO " (since Linux 2.6.26)"
174 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
175 .\" Author: Roman Zippel <[email protected]>
176 Select nanosecond resolution.
177 Only one of
178 .B ADJ_MICRO
179 and
180 .B ADJ_NANO
181 should be specified.
182 .TP
183 .BR ADJ_TAI " (since Linux 2.6.26)"
184 .\" commit 153b5d054ac2d98ea0d86504884326b6777f683d
185 Set TAI (Atomic International Time) offset from
186 .IR buf.constant .
187 .IP
188 .B ADJ_TAI
189 should not be used in conjunction with
190 .BR ADJ_TIMECONST ,
191 since the latter mode also employs the
192 .I buf.constant
193 field.
194 .IP
195 For a complete explanation of TAI
196 and the difference between TAI and UTC, see
197 .UR http:\://www.bipm.org/en/bipm/tai/tai.html
198 .I BIPM
199 .UE
200 .TP
201 .B ADJ_TICK
202 Set tick value from
203 .IR buf.tick .
204 .P
205 Alternatively,
206 .I modes
207 can be specified as either of the following (multibit mask) values,
208 in which case other bits should not be specified in
209 .IR modes :
210 .\" In general, the other bits are ignored, but ADJ_OFFSET_SINGLESHOT 0x8001
211 .\" ORed with ADJ_NANO (0x2000) gives 0xa0001 == ADJ_OFFSET_SS_READ!!
212 .TP
213 .B ADJ_OFFSET_SINGLESHOT
214 .\" In user space, ADJ_OFFSET_SINGLESHOT is 0x8001
215 .\" In kernel space it is 0x0001, and must be ANDed with ADJ_ADJTIME (0x8000)
216 Old-fashioned
217 .BR adjtime (3):
218 (gradually) adjust time by value specified in
219 .IR buf.offset ,
220 which specifies an adjustment in microseconds.
221 .TP
222 .BR ADJ_OFFSET_SS_READ " (functional since Linux 2.6.28)"
223 .\" In user space, ADJ_OFFSET_SS_READ is 0xa001
224 .\" In kernel space there is ADJ_OFFSET_READONLY (0x2000) anded with
225 .\" ADJ_ADJTIME (0x8000) and ADJ_OFFSET_SINGLESHOT (0x0001) to give 0xa001)
226 Return (in
227 .IR buf.offset )
228 the remaining amount of time to be adjusted after an earlier
229 .B ADJ_OFFSET_SINGLESHOT
230 operation.
231 This feature was added in Linux 2.6.24,
232 .\" commit 52bfb36050c8529d9031d2c2513b281a360922ec
233 but did not work correctly
234 .\" commit 916c7a855174e3b53d182b97a26b2e27a29726a1
235 until Linux 2.6.28.
236 .P
237 Ordinary users are restricted to a value of either 0 or
238 .B ADJ_OFFSET_SS_READ
239 for
240 .IR modes .
241 Only the superuser may set any parameters.
242 .P
243 The
244 .I buf.status
245 field is a bit mask that is used to set and/or retrieve status
246 bits associated with the NTP implementation.
247 Some bits in the mask are both readable and settable,
248 while others are read-only.
249 .TP
250 .BR STA_PLL " (read-write)"
251 Enable phase-locked loop (PLL) updates via
252 .BR ADJ_OFFSET .
253 .TP
254 .BR STA_PPSFREQ " (read-write)"
255 Enable PPS (pulse-per-second) frequency discipline.
256 .TP
257 .BR STA_PPSTIME " (read-write)"
258 Enable PPS time discipline.
259 .TP
260 .BR STA_FLL " (read-write)"
261 Select frequency-locked loop (FLL) mode.
262 .TP
263 .BR STA_INS " (read-write)"
264 Insert a leap second after the last second of the UTC day,
265 thus extending the last minute of the day by one second.
266 Leap-second insertion will occur each day, so long as this flag remains set.
267 .\" John Stultz;
268 .\" Usually this is written as extending the day by one second,
269 .\" which is represented as:
270 .\" 23:59:59
271 .\" 23:59:60
272 .\" 00:00:00
273 .\"
274 .\" But since posix cannot represent 23:59:60, we repeat the last second:
275 .\" 23:59:59 + TIME_INS
276 .\" 23:59:59 + TIME_OOP
277 .\" 00:00:00 + TIME_WAIT
278 .\"
279 .TP
280 .BR STA_DEL " (read-write)"
281 Delete a leap second at the last second of the UTC day.
282 .\" John Stultz:
283 .\" Similarly the progression here is:
284 .\" 23:59:57 + TIME_DEL
285 .\" 23:59:58 + TIME_DEL
286 .\" 00:00:00 + TIME_WAIT
287 Leap second deletion will occur each day, so long as this flag
288 remains set.
289 .\" FIXME Does there need to be a statement that it is nonsensical to set
290 .\" to set both STA_INS and STA_DEL?
291 .TP
292 .BR STA_UNSYNC " (read-write)"
293 Clock unsynchronized.
294 .TP
295 .BR STA_FREQHOLD " (read-write)"
296 Hold frequency.
297 .\" Following text from John Stultz:
298 Normally adjustments made via
299 .B ADJ_OFFSET
300 result in dampened frequency adjustments also being made.
301 So a single call corrects the current offset,
302 but as offsets in the same direction are made repeatedly,
303 the small frequency adjustments will accumulate to fix the long-term skew.
304 .IP
305 This flag prevents the small frequency adjustment from being made
306 when correcting for an
307 .B ADJ_OFFSET
308 value.
309 .\" According to the Kernel Application Program Interface document,
310 .\" STA_FREQHOLD is not used by the NTP version 4 daemon
311 .TP
312 .BR STA_PPSSIGNAL " (read-only)"
313 A valid PPS (pulse-per-second) signal is present.
314 .TP
315 .BR STA_PPSJITTER " (read-only)"
316 PPS signal jitter exceeded.
317 .TP
318 .BR STA_PPSWANDER " (read-only)"
319 PPS signal wander exceeded.
320 .TP
321 .BR STA_PPSERROR " (read-only)"
322 PPS signal calibration error.
323 .TP
324 .BR STA_CLOCKERR " (read-only)"
325 Clock hardware fault.
326 .\" Not set in current kernel (4.5), but checked in a few places
327 .TP
328 .BR STA_NANO " (read-only; since Linux 2.6.26)"
329 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
330 .\" Author: Roman Zippel <[email protected]>
331 Resolution (0 = microsecond, 1 = nanoseconds).
332 Set via
333 .BR ADJ_NANO ,
334 cleared via
335 .BR ADJ_MICRO .
336 .TP
337 .BR STA_MODE " (since Linux 2.6.26)"
338 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
339 .\" Author: Roman Zippel <[email protected]>
340 Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop).
341 .TP
342 .BR STA_CLK " (read-only; since Linux 2.6.26)"
343 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
344 .\" Author: Roman Zippel <[email protected]>
345 Clock source (0 = A, 1 = B);
346 currently unused.
347 .P
348 Attempts to set read-only
349 .I status
350 bits are silently ignored.
351 .\"
352 .SS clock_adjtime ()
353 The
354 .BR clock_adjtime ()
355 system call (added in Linux 2.6.39) behaves like
356 .BR adjtimex ()
357 but takes an additional
358 .I clk_id
359 argument to specify the particular clock on which to act.
360 .SS ntp_adjtime ()
361 The
362 .BR ntp_adjtime ()
363 library function
364 (described in the NTP "Kernel Application Program API", KAPI)
365 is a more portable interface for performing the same task as
366 .BR adjtimex ().
367 Other than the following points, it is identical to
368 .BR adjtimex ():
369 .IP \[bu] 3
370 The constants used in
371 .I modes
372 are prefixed with "MOD_" rather than "ADJ_", and have the same suffixes (thus,
373 .BR MOD_OFFSET ,
374 .BR MOD_FREQUENCY ,
375 and so on), other than the exceptions noted in the following points.
376 .IP \[bu]
377 .B MOD_CLKA
378 is the synonym for
379 .BR ADJ_OFFSET_SINGLESHOT .
380 .IP \[bu]
381 .B MOD_CLKB
382 is the synonym for
383 .BR ADJ_TICK .
384 .IP \[bu]
385 The is no synonym for
386 .BR ADJ_OFFSET_SS_READ ,
387 which is not described in the KAPI.
388 .SH RETURN VALUE
389 On success,
390 .BR adjtimex ()
391 and
392 .BR ntp_adjtime ()
393 return the clock state;
394 that is,
395 one of the following values:
396 .TP 12
397 .B TIME_OK
398 Clock synchronized, no leap second adjustment pending.
399 .TP
400 .B TIME_INS
401 Indicates that a leap second will be added at the end of the UTC day.
402 .TP
403 .B TIME_DEL
404 Indicates that a leap second will be deleted at the end of the UTC day.
405 .TP
406 .B TIME_OOP
407 Insertion of a leap second is in progress.
408 .TP
409 .B TIME_WAIT
410 A leap-second insertion or deletion has been completed.
411 This value will be returned until the next
412 .B ADJ_STATUS
413 operation clears the
414 .B STA_INS
415 and
416 .B STA_DEL
417 flags.
418 .TP
419 .B TIME_ERROR
420 The system clock is not synchronized to a reliable server.
421 This value is returned when any of the following holds true:
422 .RS
423 .IP \[bu] 3
424 Either
425 .B STA_UNSYNC
426 or
427 .B STA_CLOCKERR
428 is set.
429 .IP \[bu]
430 .B STA_PPSSIGNAL
431 is clear and either
432 .B STA_PPSFREQ
433 or
434 .B STA_PPSTIME
435 is set.
436 .IP \[bu]
437 .B STA_PPSTIME
438 and
439 .B STA_PPSJITTER
440 are both set.
441 .IP \[bu]
442 .B STA_PPSFREQ
443 is set and either
444 .B STA_PPSWANDER
445 or
446 .B STA_PPSJITTER
447 is set.
448 .RE
449 .IP
450 The symbolic name
451 .B TIME_BAD
452 is a synonym for
453 .BR TIME_ERROR ,
454 provided for backward compatibility.
455 .P
456 Note that starting with Linux 3.4,
457 .\" commit 6b43ae8a619d17c4935c3320d2ef9e92bdeed05d changed to asynchronous
458 .\" operation, so we can no longer rely on the return code.
459 the call operates asynchronously and the return value usually will
460 not reflect a state change caused by the call itself.
461 .P
462 On failure, these calls return \-1 and set
463 .I errno
464 to indicate the error.
465 .SH ERRORS
466 .TP
467 .B EFAULT
468 .I buf
469 does not point to writable memory.
470 .TP
471 .BR EINVAL " (before Linux 2.6.26)"
472 An attempt was made to set
473 .I buf.freq
474 to a value outside the range (\-33554432, +33554432).
475 .\" From a quick glance, it appears there was no clamping or range check
476 .\" for buf.freq before Linux 2.0
477 .TP
478 .BR EINVAL " (before Linux 2.6.26)"
479 An attempt was made to set
480 .I buf.offset
481 to a value outside the permitted range.
482 Before Linux 2.0, the permitted range was (\-131072, +131072).
483 From Linux 2.0 onwards, the permitted range was (\-512000, +512000).
484 .TP
485 .B EINVAL
486 An attempt was made to set
487 .I buf.status
488 to a value other than those listed above.
489 .TP
490 .B EINVAL
491 The
492 .I clk_id
493 given to
494 .BR clock_adjtime ()
495 is invalid for one of two reasons.
496 Either the System-V style hard-coded
497 positive clock ID value is out of range, or the dynamic
498 .I clk_id
499 does not refer to a valid instance of a clock object.
500 See
501 .BR clock_gettime (2)
502 for a discussion of dynamic clocks.
503 .TP
504 .B EINVAL
505 An attempt was made to set
506 .I buf.tick
507 to a value outside the range
508 .RB 900000/ HZ
509 to
510 .RB 1100000/ HZ ,
511 where
512 .B HZ
513 is the system timer interrupt frequency.
514 .TP
515 .B ENODEV
516 The hot-pluggable device (like USB for example) represented by a
517 dynamic
518 .I clk_id
519 has disappeared after its character device was opened.
520 See
521 .BR clock_gettime (2)
522 for a discussion of dynamic clocks.
523 .TP
524 .B EOPNOTSUPP
525 The given
526 .I clk_id
527 does not support adjustment.
528 .TP
529 .B EPERM
530 .I buf.modes
531 is neither 0 nor
532 .BR ADJ_OFFSET_SS_READ ,
533 and the caller does not have sufficient privilege.
534 Under Linux, the
535 .B CAP_SYS_TIME
536 capability is required.
537 .SH ATTRIBUTES
538 For an explanation of the terms used in this section, see
539 .BR attributes (7).
540 .TS
541 allbox;
542 lbx lb lb
543 l l l.
544 Interface Attribute Value
545 T{
546 .na
547 .nh
548 .BR \%ntp_adjtime ()
549 T} Thread safety MT-Safe
550 .TE
551 .SH STANDARDS
552 .TP
553 .BR adjtimex ()
554 .TQ
555 .BR clock_adjtime ()
556 Linux.
557 .P
558 The preferred API for the NTP daemon is
559 .BR ntp_adjtime ().
560 .SH NOTES
561 In struct
562 .IR timex ,
563 .IR freq ,
564 .IR ppsfreq ,
565 and
566 .I stabil
567 are ppm (parts per million) with a 16-bit fractional part,
568 which means that a value of 1 in one of those fields
569 actually means 2\[ha]-16 ppm, and 2\[ha]16=65536 is 1 ppm.
570 This is the case for both input values (in the case of
571 .IR freq )
572 and output values.
573 .P
574 The leap-second processing triggered by
575 .B STA_INS
576 and
577 .B STA_DEL
578 is done by the kernel in timer context.
579 Thus, it will take one tick into the second
580 for the leap second to be inserted or deleted.
581 .SH SEE ALSO
582 .BR clock_gettime (2),
583 .BR clock_settime (2),
584 .BR settimeofday (2),
585 .BR adjtime (3),
586 .BR ntp_gettime (3),
587 .BR capabilities (7),
588 .BR time (7),
589 .BR adjtimex (8),
590 .BR hwclock (8)
591 .P
592 .ad l
593 .UR http:\://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm
594 NTP "Kernel Application Program Interface"
595 .UE