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