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>
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
6 .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com>
7 .\" Modified 1997-07-30 by Paul Slootman <paul@wurtel.demon.nl>
8 .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com>
10 .TH ADJTIMEX 2 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
12 adjtimex, clock_adjtime, ntp_adjtime \- tune kernel clock
15 .RI ( libc ", " \-lc )
18 .B #include <sys/timex.h>
20 .BI "int adjtimex(struct timex *" "buf" );
22 .BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" );
24 .BI "int ntp_adjtime(struct timex *" buf );
27 Linux uses David L.\& Mills' clock adjustment algorithm (see RFC\ 5905).
30 reads and optionally sets adjustment parameters for this algorithm.
31 It takes a pointer to a
33 structure, updates kernel parameters from (selected) field values,
34 and returns the same structure updated with the current kernel values.
35 This structure is declared as follows:
40 int modes; /* Mode selector */
41 long offset; /* Time offset; nanoseconds, if STA_NANO
42 status flag is set, otherwise
44 long freq; /* Frequency offset; see NOTES for units */
45 long maxerror; /* Maximum error (microseconds) */
46 long esterror; /* Estimated error (microseconds) */
47 int status; /* Clock command/status */
48 long constant; /* PLL (phase\-locked loop) time constant */
49 long precision; /* Clock precision
50 (microseconds, read\-only) */
51 long tolerance; /* Clock frequency tolerance (read\-only);
52 see NOTES for units */
54 /* Current time (read\-only, except for
55 ADJ_SETOFFSET); upon return, time.tv_usec
56 contains nanoseconds, if STA_NANO status
57 flag is set, otherwise microseconds */
58 long tick; /* Microseconds between clock ticks */
59 long ppsfreq; /* PPS (pulse per second) frequency
60 (read\-only); see NOTES for units */
61 long jitter; /* PPS jitter (read\-only); nanoseconds, if
62 STA_NANO status flag is set, otherwise
64 int shift; /* PPS interval duration
65 (seconds, read\-only) */
66 long stabil; /* PPS stability (read\-only);
67 see NOTES for units */
68 long jitcnt; /* PPS count of jitter limit exceeded
69 events (read\-only) */
70 long calcnt; /* PPS count of calibration intervals
72 long errcnt; /* PPS count of calibration errors
74 long stbcnt; /* PPS count of stability limit exceeded
75 events (read\-only) */
76 int tai; /* TAI offset, as set by previous ADJ_TAI
77 operation (seconds, read\-only,
78 since Linux 2.6.26) */
79 /* Further padding bytes to allow for future expansion */
86 field determines which parameters, if any, to set.
87 (As described later in this page,
88 the constants used for
90 are equivalent but differently named.)
91 It is a bit mask containing a
93 combination of zero or more of the following bits:
99 .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23
100 the supplied value is clamped to the range (\-0.5s, +0.5s).
103 error occurs if the supplied value is out of range.
106 Set frequency offset from
109 .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23
110 the supplied value is clamped to the range (\-32768000, +32768000).
113 error occurs if the supplied value is out of range.
116 Set maximum time error from
120 Set estimated time error from
124 Set clock status bits from
126 A description of these bits is provided below.
129 Set PLL time constant from
133 status flag (see below) is clear, the kernel adds 4 to this value.
135 .BR ADJ_SETOFFSET " (since Linux 2.6.39)"
136 .\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762
137 .\" Author: Richard Cochran <richardcochran@gmail.com>
147 is interpreted as a nanosecond value;
148 otherwise it is interpreted as microseconds.
152 is the sum of its two fields, but the
155 must always be nonnegative.
156 The following example shows how to
159 with nanosecond resolution.
163 while (buf.time.tv_usec < 0) {
164 buf.time.tv_sec \-= 1;
165 buf.time.tv_usec += 1000000000;
170 .BR ADJ_MICRO " (since Linux 2.6.26)"
171 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
172 .\" Author: Roman Zippel <zippel@linux-m68k.org>
173 Select microsecond resolution.
175 .BR ADJ_NANO " (since Linux 2.6.26)"
176 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
177 .\" Author: Roman Zippel <zippel@linux-m68k.org>
178 Select nanosecond resolution.
185 .BR ADJ_TAI " (since Linux 2.6.26)"
186 .\" commit 153b5d054ac2d98ea0d86504884326b6777f683d
187 Set TAI (Atomic International Time) offset from
191 should not be used in conjunction with
193 since the latter mode also employs the
197 For a complete explanation of TAI
198 and the difference between TAI and UTC, see
199 .UR http://www.bipm.org/en/bipm/tai/tai.html
209 can be specified as either of the following (multibit mask) values,
210 in which case other bits should not be specified in
212 .\" In general, the other bits are ignored, but ADJ_OFFSET_SINGLESHOT 0x8001
213 .\" ORed with ADJ_NANO (0x2000) gives 0xa0001 == ADJ_OFFSET_SS_READ!!
215 .B ADJ_OFFSET_SINGLESHOT
216 .\" In user space, ADJ_OFFSET_SINGLESHOT is 0x8001
217 .\" In kernel space it is 0x0001, and must be ANDed with ADJ_ADJTIME (0x8000)
220 (gradually) adjust time by value specified in
222 which specifies an adjustment in microseconds.
224 .BR ADJ_OFFSET_SS_READ " (functional since Linux 2.6.28)"
225 .\" In user space, ADJ_OFFSET_SS_READ is 0xa001
226 .\" In kernel space there is ADJ_OFFSET_READONLY (0x2000) anded with
227 .\" ADJ_ADJTIME (0x8000) and ADJ_OFFSET_SINGLESHOT (0x0001) to give 0xa001)
230 the remaining amount of time to be adjusted after an earlier
231 .B ADJ_OFFSET_SINGLESHOT
233 This feature was added in Linux 2.6.24,
234 .\" commit 52bfb36050c8529d9031d2c2513b281a360922ec
235 but did not work correctly
236 .\" commit 916c7a855174e3b53d182b97a26b2e27a29726a1
239 Ordinary users are restricted to a value of either 0 or
240 .B ADJ_OFFSET_SS_READ
243 Only the superuser may set any parameters.
247 field is a bit mask that is used to set and/or retrieve status
248 bits associated with the NTP implementation.
249 Some bits in the mask are both readable and settable,
250 while others are read-only.
252 .BR STA_PLL " (read-write)"
253 Enable phase-locked loop (PLL) updates via
256 .BR STA_PPSFREQ " (read-write)"
257 Enable PPS (pulse-per-second) frequency discipline.
259 .BR STA_PPSTIME " (read-write)"
260 Enable PPS time discipline.
262 .BR STA_FLL " (read-write)"
263 Select frequency-locked loop (FLL) mode.
265 .BR STA_INS " (read-write)"
266 Insert a leap second after the last second of the UTC day,
267 thus extending the last minute of the day by one second.
268 Leap-second insertion will occur each day, so long as this flag remains set.
270 .\" Usually this is written as extending the day by one second,
271 .\" which is represented as:
276 .\" But since posix cannot represent 23:59:60, we repeat the last second:
277 .\" 23:59:59 + TIME_INS
278 .\" 23:59:59 + TIME_OOP
279 .\" 00:00:00 + TIME_WAIT
282 .BR STA_DEL " (read-write)"
283 Delete a leap second at the last second of the UTC day.
285 .\" Similarly the progression here is:
286 .\" 23:59:57 + TIME_DEL
287 .\" 23:59:58 + TIME_DEL
288 .\" 00:00:00 + TIME_WAIT
289 Leap second deletion will occur each day, so long as this flag
291 .\" FIXME Does there need to be a statement that it is nonsensical to set
292 .\" to set both STA_INS and STA_DEL?
294 .BR STA_UNSYNC " (read-write)"
295 Clock unsynchronized.
297 .BR STA_FREQHOLD " (read-write)"
299 .\" Following text from John Stultz:
300 Normally adjustments made via
302 result in dampened frequency adjustments also being made.
303 So a single call corrects the current offset,
304 but as offsets in the same direction are made repeatedly,
305 the small frequency adjustments will accumulate to fix the long-term skew.
307 This flag prevents the small frequency adjustment from being made
308 when correcting for an
311 .\" According to the Kernel Application Program Interface document,
312 .\" STA_FREQHOLD is not used by the NTP version 4 daemon
314 .BR STA_PPSSIGNAL " (read-only)"
315 A valid PPS (pulse-per-second) signal is present.
317 .BR STA_PPSJITTER " (read-only)"
318 PPS signal jitter exceeded.
320 .BR STA_PPSWANDER " (read-only)"
321 PPS signal wander exceeded.
323 .BR STA_PPSERROR " (read-only)"
324 PPS signal calibration error.
326 .BR STA_CLOCKERR " (read-only)"
327 Clock hardware fault.
328 .\" Not set in current kernel (4.5), but checked in a few places
330 .BR STA_NANO " (read-only; since Linux 2.6.26)"
331 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
332 .\" Author: Roman Zippel <zippel@linux-m68k.org>
333 Resolution (0 = microsecond, 1 = nanoseconds).
339 .BR STA_MODE " (since Linux 2.6.26)"
340 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
341 .\" Author: Roman Zippel <zippel@linux-m68k.org>
342 Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop).
344 .BR STA_CLK " (read-only; since Linux 2.6.26)"
345 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
346 .\" Author: Roman Zippel <zippel@linux-m68k.org>
347 Clock source (0 = A, 1 = B); currently unused.
349 Attempts to set read-only
351 bits are silently ignored.
356 system call (added in Linux 2.6.39) behaves like
358 but takes an additional
360 argument to specify the particular clock on which to act.
365 (described in the NTP "Kernel Application Program API", KAPI)
366 is a more portable interface for performing the same task as
368 Other than the following points, it is identical to
371 The constants used in
373 are prefixed with "MOD_" rather than "ADJ_", and have the same suffixes (thus,
376 and so on), other than the exceptions noted in the following points.
380 .BR ADJ_OFFSET_SINGLESHOT .
386 The is no synonym for
387 .BR ADJ_OFFSET_SS_READ ,
388 which is not described in the KAPI.
394 return the clock state; that is, one of the following values:
397 Clock synchronized, no leap second adjustment pending.
400 Indicates that a leap second will be added at the end of the UTC day.
403 Indicates that a leap second will be deleted at the end of the UTC day.
406 Insertion of a leap second is in progress.
409 A leap-second insertion or deletion has been completed.
410 This value will be returned until the next
419 The system clock is not synchronized to a reliable server.
420 This value is returned when any of the following holds true:
453 provided for backward compatibility.
455 Note that starting with Linux 3.4,
456 .\" commit 6b43ae8a619d17c4935c3320d2ef9e92bdeed05d changed to asynchronous
457 .\" operation, so we can no longer rely on the return code.
458 the call operates asynchronously and the return value usually will
459 not reflect a state change caused by the call itself.
461 On failure, these calls return \-1 and set
463 to indicate the error.
468 does not point to writable memory.
470 .BR EINVAL " (kernels before Linux 2.6.26)"
471 An attempt was made to set
473 to a value outside the range (\-33554432, +33554432).
474 .\" From a quick glance, it appears there was no clamping or range check
475 .\" for buf.freq in kernels before 2.0
477 .BR EINVAL " (kernels before Linux 2.6.26)"
478 An attempt was made to set
480 to a value outside the permitted range.
481 In kernels before Linux 2.0, the permitted range was (\-131072, +131072).
482 From Linux 2.0 onwards, the permitted range was (\-512000, +512000).
485 An attempt was made to set
487 to a value other than those listed above.
494 is invalid for one of two reasons.
495 Either the System-V style hard-coded
496 positive clock ID value is out of range, or the dynamic
498 does not refer to a valid instance of a clock object.
500 .BR clock_gettime (2)
501 for a discussion of dynamic clocks.
504 An attempt was made to set
506 to a value outside the range
512 is the system timer interrupt frequency.
515 The hot-pluggable device (like USB for example) represented by a
518 has disappeared after its character device was opened.
520 .BR clock_gettime (2)
521 for a discussion of dynamic clocks.
526 does not support adjustment.
531 .BR ADJ_OFFSET_SS_READ ,
532 and the caller does not have sufficient privilege.
535 capability is required.
537 For an explanation of the terms used in this section, see
545 Interface Attribute Value
548 T} Thread safety MT-Safe
554 None of these interfaces is described in POSIX.1
559 are Linux-specific and should not be used in programs
560 intended to be portable.
562 The preferred API for the NTP daemon is
571 are ppm (parts per million) with a 16-bit fractional part,
572 which means that a value of 1 in one of those fields
573 actually means 2^-16 ppm, and 2^16=65536 is 1 ppm.
574 This is the case for both input values (in the case of
578 The leap-second processing triggered by
582 is done by the kernel in timer context.
583 Thus, it will take one tick into the second
584 for the leap second to be inserted or deleted.
586 .BR clock_gettime (2),
587 .BR clock_settime (2),
588 .BR settimeofday (2),
591 .BR capabilities (7),
597 .UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm
598 NTP "Kernel Application Program Interface"