Debian Codegraph @

upstream/debian-trixie/man2/adjtimex.2

raw
1 '\" t
2 .\" Copyright (c) 1995 Michael Chastain ([email protected]), 15 April 1995.
3 .\" and Copyright (C) 2014, 2016 Michael Kerrisk <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\"
7 .\" Modified 1997-01-31 by Eric S. Raymond <[email protected]>
8 .\" Modified 1997-07-30 by Paul Slootman <[email protected]>
9 .\" Modified 2004-05-27 by Michael Kerrisk <[email protected]>
10 .\"
11 .TH adjtimex 2 2024-05-02 "Linux man-pages 6.9.1"
12 .SH NAME
13 adjtimex, clock_adjtime, ntp_adjtime \- tune kernel clock
14 .SH LIBRARY
15 Standard C library
16 .RI ( libc ", " \-lc )
17 .SH SYNOPSIS
18 .nf
19 .B #include <sys/timex.h>
20 .P
21 .BI "int adjtimex(struct timex *" "buf" );
22 .P
23 .BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" );
24 .P
25 .BI "int ntp_adjtime(struct timex *" buf );
26 .fi
27 .SH DESCRIPTION
28 Linux uses David L.\& Mills' clock adjustment algorithm (see RFC\ 5905).
29 The system call
30 .BR adjtimex ()
31 reads and optionally sets adjustment parameters for this algorithm.
32 It takes a pointer to a
33 .I timex
34 structure, updates kernel parameters from (selected) field values,
35 and returns the same structure updated with the current kernel values.
36 This structure is declared as follows:
37 .P
38 .in +4n
39 .EX
40 struct timex {
41 int modes; /* Mode selector */
42 long offset; /* Time offset; nanoseconds, if STA_NANO
43 status flag is set, otherwise
44 microseconds */
45 long freq; /* Frequency offset; see NOTES for units */
46 long maxerror; /* Maximum error (microseconds) */
47 long esterror; /* Estimated error (microseconds) */
48 int status; /* Clock command/status */
49 long constant; /* PLL (phase\-locked loop) time constant */
50 long precision; /* Clock precision
51 (microseconds, read\-only) */
52 long tolerance; /* Clock frequency tolerance (read\-only);
53 see NOTES for units */
54 struct timeval time;
55 /* Current time (read\-only, except for
56 ADJ_SETOFFSET); upon return, time.tv_usec
57 contains nanoseconds, if STA_NANO status
58 flag is set, otherwise microseconds */
59 long tick; /* Microseconds between clock ticks */
60 long ppsfreq; /* PPS (pulse per second) frequency
61 (read\-only); see NOTES for units */
62 long jitter; /* PPS jitter (read\-only); nanoseconds, if
63 STA_NANO status flag is set, otherwise
64 microseconds */
65 int shift; /* PPS interval duration
66 (seconds, read\-only) */
67 long stabil; /* PPS stability (read\-only);
68 see NOTES for units */
69 long jitcnt; /* PPS count of jitter limit exceeded
70 events (read\-only) */
71 long calcnt; /* PPS count of calibration intervals
72 (read\-only) */
73 long errcnt; /* PPS count of calibration errors
74 (read\-only) */
75 long stbcnt; /* PPS count of stability limit exceeded
76 events (read\-only) */
77 int tai; /* TAI offset, as set by previous ADJ_TAI
78 operation (seconds, read\-only,
79 since Linux 2.6.26) */
80 /* Further padding bytes to allow for future expansion */
81 };
82 .EE
83 .in
84 .P
85 The
86 .I modes
87 field determines which parameters, if any, to set.
88 (As described later in this page,
89 the constants used for
90 .BR ntp_adjtime ()
91 are equivalent but differently named.)
92 It is a bit mask containing a
93 bitwise OR
94 combination of zero or more of the following bits:
95 .TP
96 .B ADJ_OFFSET
97 Set time offset from
98 .IR buf.offset .
99 Since Linux 2.6.26,
100 .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23
101 the supplied value is clamped to the range (\-0.5s, +0.5s).
102 In older kernels, an
103 .B EINVAL
104 error occurs if the supplied value is out of range.
105 .TP
106 .B ADJ_FREQUENCY
107 Set frequency offset from
108 .IR buf.freq .
109 Since Linux 2.6.26,
110 .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23
111 the supplied value is clamped to the range (\-32768000, +32768000).
112 In older kernels, an
113 .B EINVAL
114 error occurs if the supplied value is out of range.
115 .TP
116 .B ADJ_MAXERROR
117 Set maximum time error from
118 .IR buf.maxerror .
119 .TP
120 .B ADJ_ESTERROR
121 Set estimated time error from
122 .IR buf.esterror .
123 .TP
124 .B ADJ_STATUS
125 Set clock status bits from
126 .IR buf.status .
127 A description of these bits is provided below.
128 .TP
129 .B ADJ_TIMECONST
130 Set PLL time constant from
131 .IR buf.constant .
132 If the
133 .B STA_NANO
134 status flag (see below) is clear, the kernel adds 4 to this value.
135 .TP
136 .BR ADJ_SETOFFSET " (since Linux 2.6.39)"
137 .\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762
138 .\" Author: Richard Cochran <[email protected]>
139 Add
140 .I buf.time
141 to the current time.
142 If
143 .I buf.status
144 includes the
145 .B ADJ_NANO
146 flag, then
147 .I buf.time.tv_usec
148 is interpreted as a nanosecond value;
149 otherwise it is interpreted as microseconds.
150 .IP
151 The value of
152 .I buf.time
153 is the sum of its two fields, but the
154 field
155 .I buf.time.tv_usec
156 must always be nonnegative.
157 The following example shows how to
158 normalize a
159 .I timeval
160 with nanosecond resolution.
161 .IP
162 .in +4n
163 .EX
164 while (buf.time.tv_usec < 0) {
165 buf.time.tv_sec \-= 1;
166 buf.time.tv_usec += 1000000000;
167 }
168 .EE
169 .in
170 .TP
171 .BR ADJ_MICRO " (since Linux 2.6.26)"
172 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
173 .\" Author: Roman Zippel <[email protected]>
174 Select microsecond resolution.
175 .TP
176 .BR ADJ_NANO " (since Linux 2.6.26)"
177 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
178 .\" Author: Roman Zippel <[email protected]>
179 Select nanosecond resolution.
180 Only one of
181 .B ADJ_MICRO
182 and
183 .B ADJ_NANO
184 should be specified.
185 .TP
186 .BR ADJ_TAI " (since Linux 2.6.26)"
187 .\" commit 153b5d054ac2d98ea0d86504884326b6777f683d
188 Set TAI (Atomic International Time) offset from
189 .IR buf.constant .
190 .IP
191 .B ADJ_TAI
192 should not be used in conjunction with
193 .BR ADJ_TIMECONST ,
194 since the latter mode also employs the
195 .I buf.constant
196 field.
197 .IP
198 For a complete explanation of TAI
199 and the difference between TAI and UTC, see
200 .UR http://www.bipm.org/en/bipm/tai/tai.html
201 .I BIPM
202 .UE
203 .TP
204 .B ADJ_TICK
205 Set tick value from
206 .IR buf.tick .
207 .P
208 Alternatively,
209 .I modes
210 can be specified as either of the following (multibit mask) values,
211 in which case other bits should not be specified in
212 .IR modes :
213 .\" In general, the other bits are ignored, but ADJ_OFFSET_SINGLESHOT 0x8001
214 .\" ORed with ADJ_NANO (0x2000) gives 0xa0001 == ADJ_OFFSET_SS_READ!!
215 .TP
216 .B ADJ_OFFSET_SINGLESHOT
217 .\" In user space, ADJ_OFFSET_SINGLESHOT is 0x8001
218 .\" In kernel space it is 0x0001, and must be ANDed with ADJ_ADJTIME (0x8000)
219 Old-fashioned
220 .BR adjtime (3):
221 (gradually) adjust time by value specified in
222 .IR buf.offset ,
223 which specifies an adjustment in microseconds.
224 .TP
225 .BR ADJ_OFFSET_SS_READ " (functional since Linux 2.6.28)"
226 .\" In user space, ADJ_OFFSET_SS_READ is 0xa001
227 .\" In kernel space there is ADJ_OFFSET_READONLY (0x2000) anded with
228 .\" ADJ_ADJTIME (0x8000) and ADJ_OFFSET_SINGLESHOT (0x0001) to give 0xa001)
229 Return (in
230 .IR buf.offset )
231 the remaining amount of time to be adjusted after an earlier
232 .B ADJ_OFFSET_SINGLESHOT
233 operation.
234 This feature was added in Linux 2.6.24,
235 .\" commit 52bfb36050c8529d9031d2c2513b281a360922ec
236 but did not work correctly
237 .\" commit 916c7a855174e3b53d182b97a26b2e27a29726a1
238 until Linux 2.6.28.
239 .P
240 Ordinary users are restricted to a value of either 0 or
241 .B ADJ_OFFSET_SS_READ
242 for
243 .IR modes .
244 Only the superuser may set any parameters.
245 .P
246 The
247 .I buf.status
248 field is a bit mask that is used to set and/or retrieve status
249 bits associated with the NTP implementation.
250 Some bits in the mask are both readable and settable,
251 while others are read-only.
252 .TP
253 .BR STA_PLL " (read-write)"
254 Enable phase-locked loop (PLL) updates via
255 .BR ADJ_OFFSET .
256 .TP
257 .BR STA_PPSFREQ " (read-write)"
258 Enable PPS (pulse-per-second) frequency discipline.
259 .TP
260 .BR STA_PPSTIME " (read-write)"
261 Enable PPS time discipline.
262 .TP
263 .BR STA_FLL " (read-write)"
264 Select frequency-locked loop (FLL) mode.
265 .TP
266 .BR STA_INS " (read-write)"
267 Insert a leap second after the last second of the UTC day,
268 thus extending the last minute of the day by one second.
269 Leap-second insertion will occur each day, so long as this flag remains set.
270 .\" John Stultz;
271 .\" Usually this is written as extending the day by one second,
272 .\" which is represented as:
273 .\" 23:59:59
274 .\" 23:59:60
275 .\" 00:00:00
276 .\"
277 .\" But since posix cannot represent 23:59:60, we repeat the last second:
278 .\" 23:59:59 + TIME_INS
279 .\" 23:59:59 + TIME_OOP
280 .\" 00:00:00 + TIME_WAIT
281 .\"
282 .TP
283 .BR STA_DEL " (read-write)"
284 Delete a leap second at the last second of the UTC day.
285 .\" John Stultz:
286 .\" Similarly the progression here is:
287 .\" 23:59:57 + TIME_DEL
288 .\" 23:59:58 + TIME_DEL
289 .\" 00:00:00 + TIME_WAIT
290 Leap second deletion will occur each day, so long as this flag
291 remains set.
292 .\" FIXME Does there need to be a statement that it is nonsensical to set
293 .\" to set both STA_INS and STA_DEL?
294 .TP
295 .BR STA_UNSYNC " (read-write)"
296 Clock unsynchronized.
297 .TP
298 .BR STA_FREQHOLD " (read-write)"
299 Hold frequency.
300 .\" Following text from John Stultz:
301 Normally adjustments made via
302 .B ADJ_OFFSET
303 result in dampened frequency adjustments also being made.
304 So a single call corrects the current offset,
305 but as offsets in the same direction are made repeatedly,
306 the small frequency adjustments will accumulate to fix the long-term skew.
307 .IP
308 This flag prevents the small frequency adjustment from being made
309 when correcting for an
310 .B ADJ_OFFSET
311 value.
312 .\" According to the Kernel Application Program Interface document,
313 .\" STA_FREQHOLD is not used by the NTP version 4 daemon
314 .TP
315 .BR STA_PPSSIGNAL " (read-only)"
316 A valid PPS (pulse-per-second) signal is present.
317 .TP
318 .BR STA_PPSJITTER " (read-only)"
319 PPS signal jitter exceeded.
320 .TP
321 .BR STA_PPSWANDER " (read-only)"
322 PPS signal wander exceeded.
323 .TP
324 .BR STA_PPSERROR " (read-only)"
325 PPS signal calibration error.
326 .TP
327 .BR STA_CLOCKERR " (read-only)"
328 Clock hardware fault.
329 .\" Not set in current kernel (4.5), but checked in a few places
330 .TP
331 .BR STA_NANO " (read-only; since Linux 2.6.26)"
332 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
333 .\" Author: Roman Zippel <[email protected]>
334 Resolution (0 = microsecond, 1 = nanoseconds).
335 Set via
336 .BR ADJ_NANO ,
337 cleared via
338 .BR ADJ_MICRO .
339 .TP
340 .BR STA_MODE " (since Linux 2.6.26)"
341 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
342 .\" Author: Roman Zippel <[email protected]>
343 Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop).
344 .TP
345 .BR STA_CLK " (read-only; since Linux 2.6.26)"
346 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
347 .\" Author: Roman Zippel <[email protected]>
348 Clock source (0 = A, 1 = B); currently unused.
349 .P
350 Attempts to set read-only
351 .I status
352 bits are silently ignored.
353 .\"
354 .SS clock_adjtime ()
355 The
356 .BR clock_adjtime ()
357 system call (added in Linux 2.6.39) behaves like
358 .BR adjtimex ()
359 but takes an additional
360 .I clk_id
361 argument to specify the particular clock on which to act.
362 .SS ntp_adjtime ()
363 The
364 .BR ntp_adjtime ()
365 library function
366 (described in the NTP "Kernel Application Program API", KAPI)
367 is a more portable interface for performing the same task as
368 .BR adjtimex ().
369 Other than the following points, it is identical to
370 .BR adjtimex ():
371 .IP \[bu] 3
372 The constants used in
373 .I modes
374 are prefixed with "MOD_" rather than "ADJ_", and have the same suffixes (thus,
375 .BR MOD_OFFSET ,
376 .BR MOD_FREQUENCY ,
377 and so on), other than the exceptions noted in the following points.
378 .IP \[bu]
379 .B MOD_CLKA
380 is the synonym for
381 .BR ADJ_OFFSET_SINGLESHOT .
382 .IP \[bu]
383 .B MOD_CLKB
384 is the synonym for
385 .BR ADJ_TICK .
386 .IP \[bu]
387 The is no synonym for
388 .BR ADJ_OFFSET_SS_READ ,
389 which is not described in the KAPI.
390 .SH RETURN VALUE
391 On success,
392 .BR adjtimex ()
393 and
394 .BR ntp_adjtime ()
395 return the clock state; that is, 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