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 .\" %%%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.
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.
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.
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/>.
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>
29 .TH ADJTIMEX 2 2016-10-08 "Linux" "Linux Programmer's Manual"
31 adjtimex, ntp_adjtime \- tune kernel clock
34 .B #include <sys/timex.h>
36 .BI "int adjtimex(struct timex *" "buf" );
38 .BI "int ntp_adjtime(struct timex *" buf );
41 Linux uses David L. Mills' clock adjustment algorithm (see RFC\ 5905).
44 reads and optionally sets adjustment parameters for this algorithm.
45 It takes a pointer to a
47 structure, updates kernel parameters from (selected) field values,
48 and returns the same structure updated with the current kernel values.
49 This structure is declared as follows:
54 int modes; /* Mode selector */
55 long offset; /* Time offset; nanoseconds, if STA_NANO
56 status flag is set, otherwise
58 long freq; /* Frequency offset; see NOTES for units */
59 long maxerror; /* Maximum error (microseconds) */
60 long esterror; /* Estimated error (microseconds) */
61 int status; /* Clock command/status */
62 long constant; /* PLL (phase-locked loop) time constant */
63 long precision; /* Clock precision
64 (microseconds, read-only) */
65 long tolerance; /* Clock frequency tolerance (read-only);
66 see NOTES for units */
68 /* Current time (read-only, except for
69 ADJ_SETOFFSET); upon return, time.tv_usec
70 contains nanoseconds, if STA_NANO status
71 flag is set, otherwise microseconds */
72 long tick; /* Microseconds between clock ticks */
73 long ppsfreq; /* PPS (pulse per second) frequency
74 (read-only); see NOTES for units */
75 long jitter; /* PPS jitter (read-only); nanoseconds, if
76 STA_NANO status flag is set, otherwise
78 int shift; /* PPS interval duration
79 (seconds, read-only) */
80 long stabil; /* PPS stability (read-only);
81 see NOTES for units */
82 long jitcnt; /* PPS count of jitter limit exceeded
84 long calcnt; /* PPS count of calibration intervals
86 long errcnt; /* PPS count of calibration errors
88 long stbcnt; /* PPS count of stability limit exceeded
90 int tai; /* TAI offset, as set by previous ADJ_TAI
91 operation (seconds, read-only,
92 since Linux 2.6.26) */
93 /* Further padding bytes to allow for future expansion */
100 field determines which parameters, if any, to set.
101 (As described later in this page,
102 the constants used for
104 are equivalent but differently named.)
105 It is a bit mask containing a
107 combination of zero or more of the following bits:
113 .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23
114 the supplied value is clamped to the range (\-0.5s, +0.5s).
117 error occurs if the supplied value is out of range.
120 Set frequency offset from
123 .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23
124 the supplied value is clamped to the range (\-32768000, +32768000).
127 error occurs if the supplied value is out of range.
130 Set maximum time error from
134 Set estimated time error from
138 Set clock status bits from
140 A description of these bits is provided below.
143 Set PLL time constant from
147 status flag (see below) is clear, the kernel adds 4 to this value.
149 .BR ADJ_SETOFFSET " (since Linux 2.6.39)"
150 .\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762
151 .\" Author: Richard Cochran <richardcochran@gmail.com>
161 is interpreted as a nanosecond value;
162 otherwise it is interpreted as microseconds.
164 .BR ADJ_MICRO " (since Linux 2.6.26)"
165 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
166 .\" Author: Roman Zippel <zippel@linux-m68k.org>
167 Select microsecond resolution.
169 .BR ADJ_NANO " (since Linux 2.6.26)"
170 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
171 .\" Author: Roman Zippel <zippel@linux-m68k.org>
172 Select nanosecond resolution.
179 .BR ADJ_TAI " (since Linux 2.6.26)"
180 .\" commit 153b5d054ac2d98ea0d86504884326b6777f683d
181 Set TAI (Atomic International Time) offset from
185 should not be used in conjunction with
187 since the latter mode also employs the
191 For a complete explanation of TAI
192 and the difference between TAI and UTC, see
193 .UR http://www.bipm.org/en/bipm/tai/tai.html
203 can be specified as either of the following (multibit mask) values,
204 in which case other bits should not be specified in
206 .\" In general, the other bits are ignored, but ADJ_OFFSET_SINGLESHOT 0x8001
207 .\" ORed with ADJ_NANO (0x2000) gives 0xa0001 == ADJ_OFFSET_SS_READ!!
209 .BR ADJ_OFFSET_SINGLESHOT
210 .\" In user space, ADJ_OFFSET_SINGLESHOT is 0x8001
211 .\" In kernel space it is 0x0001, and must be ANDed with ADJ_ADJTIME (0x8000)
214 (gradually) adjust time by value specified in
216 which specifies an adjustment in microseconds.
218 .BR ADJ_OFFSET_SS_READ " (functional since Linux 2.6.28)"
219 .\" In user space, ADJ_OFFSET_SS_READ is 0xa001
220 .\" In kernel space there is ADJ_OFFSET_READONLY (0x2000) anded with
221 .\" ADJ_ADJTIME (0x8000) and ADJ_OFFSET_SINGLESHOT (0x0001) to give 0xa001)
224 the remaining amount of time to be adjusted after an earlier
225 .BR ADJ_OFFSET_SINGLESHOT
227 This feature was added in Linux 2.6.24,
228 .\" commit 52bfb36050c8529d9031d2c2513b281a360922ec
229 but did not work correctly
230 .\" commit 916c7a855174e3b53d182b97a26b2e27a29726a1
233 Ordinary users are restricted to a value of either 0 or
234 .B ADJ_OFFSET_SS_READ
237 Only the superuser may set any parameters.
241 field is a bit mask that is used to set and/or retrieve status
242 bits associated with the NTP implementation.
243 Some bits in the mask are both readable and settable,
244 while others are read-only.
246 .BR STA_PLL " (read-write)"
247 Enable phase-locked loop (PLL) updates via
250 .BR STA_PPSFREQ " (read-write)"
251 Enable PPS (pulse-per-second) frequency discipline.
253 .BR STA_PPSTIME " (read-write)"
254 Enable PPS time discipline.
256 .BR STA_FLL " (read-write)"
257 Select frequency-locked loop (FLL) mode.
259 .BR STA_INS " (read-write)"
260 Insert a leap second after the last second of the UTC day,
261 thus extending the last minute of the day by one second.
262 Leap-second insertion will occur each day, so long as this flag remains set.
264 .\" Usually this is written as extending the day by one second,
265 .\" which is represented as:
270 .\" But since posix cannot represent 23:59:60, we repeat the last second:
271 .\" 23:59:59 + TIME_INS
272 .\" 23:59:59 + TIME_OOP
273 .\" 00:00:00 + TIME_WAIT
276 .BR STA_DEL " (read-write)"
277 Delete a leap second at the last second of the UTC day.
279 .\" Similarly the progression here is:
280 .\" 23:59:57 + TIME_DEL
281 .\" 23:59:58 + TIME_DEL
282 .\" 00:00:00 + TIME_WAIT
283 Leap second deletion will occur each day, so long as this flag
285 .\" FIXME Does there need to be a statement that it is nonsensical to set
286 .\" to set both STA_INS and STA_DEL?
288 .BR STA_UNSYNC " (read-write)"
289 Clock unsynchronized.
291 .BR STA_FREQHOLD " (read-write)"
293 .\" Following text from John Stultz:
294 Normally adjustments made via
296 result in dampened frequency adjustments also being made.
297 So a single call corrects the current offset,
298 but as offsets in the same direction are made repeatedly,
299 the small frequency adjustments will accumulate to fix the long-term skew.
301 This flag prevents the small frequency adjustment from being made
302 when correcting for an
305 .\" According to the Kernel Application Program Interface document,
306 .\" STA_FREQHOLD is not used by the NTP version 4 daemon
308 .BR STA_PPSSIGNAL " (read-only)"
309 A valid PPS (pulse-per-second) signal is present.
311 .BR STA_PPSJITTER " (read-only)"
312 PPS signal jitter exceeded.
314 .BR STA_PPSWANDER " (read-only)"
315 PPS signal wander exceeded.
317 .BR STA_PPSERROR " (read-only)"
318 PPS signal calibration error.
320 .BR STA_CLOCKERR " (read-only)"
321 Clock hardware fault.
322 .\" Not set in current kernel (4.5), but checked in a few places
324 .BR STA_NANO " (read-only; since Linux 2.6.26)"
325 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
326 .\" Author: Roman Zippel <zippel@linux-m68k.org>
327 Resolution (0 = microsecond, 1 = nanoseconds).
333 .BR STA_MODE " (since Linux 2.6.26)"
334 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
335 .\" Author: Roman Zippel <zippel@linux-m68k.org>
336 Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop).
338 .BR STA_CLK " (read-only; since Linux 2.6.26)"
339 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
340 .\" Author: Roman Zippel <zippel@linux-m68k.org>
341 Clock source (0 = A, 1 = B); currently unused.
343 Attempts to set read-only
345 bits are silently ignored.
351 (described in the NTP "Kernel Application Program API", KAPI)
352 is a more portable interface for performing the same task as
354 Other than the following points, it is identical to
357 The constants used in
359 are prefixed with "MOD_" rather than "ADJ_", and have the same suffixes (thus,
362 and so on), other than the exceptions noted in the following points.
366 .BR ADJ_OFFSET_SINGLESHOT .
372 The is no synonym for
373 .BR ADJ_OFFSET_SS_READ ,
374 which is not described in the KAPI.
380 return the clock state; that is, one of the following values:
383 Clock synchronized, no leap second adjustment pending.
386 Indicates that a leap second will be added at the end of the UTC day.
389 Indicates that a leap second will be deleted at the end of the UTC day.
392 Insertion of a leap second is in progress.
395 A leap-second insertion or deletion has been completed.
396 This value will be returned until the next
405 The system clock is not synchronized to a reliable server.
406 This value is returned when any of the following holds true:
439 provided for backward compatibility.
441 Note that starting with Linux 3.4,
442 .\" commit 6b43ae8a619d17c4935c3320d2ef9e92bdeed05d changed to asynchronous
443 .\" operation, so we can no longer rely on the return code.
444 the call operates asynchronously and the return value usually will
445 not reflect a state change caused by the call itself.
447 On failure, these calls return \-1 and set
453 does not point to writable memory.
455 .BR EINVAL " (kernels before Linux 2.6.26)"
456 An attempt was made to set
458 to a value outside the range (\-33554432, +33554432).
459 .\" From a quick glance, it appears there was no clamping or range check
460 .\" for buf.freq in kernels before 2.0
462 .BR EINVAL " (kernels before Linux 2.6.26)"
463 An attempt was made to set
465 to a value outside the permitted range.
466 In kernels before Linux 2.0, the permitted range was (\-131072, +131072).
467 From Linux 2.0 onwards, the permitted range was (\-512000, +512000).
470 An attempt was made to set
472 to a value other than those listed above.
475 An attempt was made to set
477 to a value outside the range
483 is the system timer interrupt frequency.
488 .BR ADJ_OFFSET_SS_READ ,
489 and the caller does not have sufficient privilege.
492 capability is required.
494 For an explanation of the terms used in this section, see
500 Interface Attribute Value
503 T} Thread safety MT-Safe
506 Neither of these interfaces is described in POSIX.1
509 is Linux-specific and should not be used in programs
510 intended to be portable.
512 The preferred API for the NTP daemon is
521 are ppm (parts per million) with a 16-bit fractional part,
522 which means that a value of 1 in one of those fields
523 actually means 2^-16 ppm, and 2^16=65536 is 1 ppm.
524 This is the case for both input values (in the case of
528 The leap-second processing triggered by
532 is done by the kernel in timer context
533 Thus, it will take one tick into the second
534 for the leap second to be inserted or deleted.
536 .BR settimeofday (2),
539 .BR capabilities (7),
545 .UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm
546 NTP "Kernel Application Program Interface"