1 .\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995.
2 .\" and Copyright (C) 2014 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 2014-12-31 "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 microseconds */
57 long freq; /* Frequency offset, in units of 2^-16 ppm
58 (parts per million, see NOTES below) */
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 (microseconds, read-only) */
64 long tolerance; /* Clock frequency tolerance (ppm, read-only) */
66 /* Current time (read-only, except for
67 ADJ_SETOFFSET); upon return, time.tv_usec
68 contains nanoseconds, if STA_NANO status
69 flag is set, otherwise microseconds */
70 long tick; /* Microseconds between clock ticks */
71 long ppsfreq; /* PPS (pulse per second) frequency (in units
72 of 2^-16 ppm\-\-see NOTES, read-only) */
73 long jitter; /* PPS jitter (read-only); nanoseconds, if
74 STA_NANO status flag is set, otherwise
76 int shift; /* PPS interval duration (seconds, read-only) */
77 long stabil; /* PPS stability (2^-16 ppm\-\-see NOTES,
79 long jitcnt; /* PPS count of jitter limit exceeded
81 long calcnt; /* PPS count of calibration intervals
83 long errcnt; /* PPS count of calibration errors
85 long stbcnt; /* PPS count of stability limit exceeded
87 int tai; /* TAI offset, as set by previous ADJ_TAI
88 operation (seconds, read-only,
89 since Linux 2.6.26) */
90 /* Further padding bytes to allow for future expansion */
97 field determines which parameters, if any, to set.
98 (As described later in this page,
99 the constants used for
101 are equivalent but differently named.)
102 It is a bit mask containing a
104 combination of zero or more of the following bits:
110 .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23
111 the supplied value is clamped to the range (\-0.5s, +0.5s).
114 error occurs if the supplied value is out of range.
117 Set frequency offset from
120 .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23
121 the supplied value is clamped to the range (\-32768000, +32768000).
124 error occurs if the supplied value is out of range.
127 Set maximum time error from
131 Set estimated time error from
135 Set clock status bits from
137 A description of these bits is provided below.
140 Set PLL time constant from
144 status flag (see below) is clear, the kernel adds 4 to this value.
146 .BR ADJ_SETOFFSET " (since Linux 2.6.29)"
147 .\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762
148 .\" Author: Richard Cochran <richardcochran@gmail.com>
158 is interpreted as a nanosecond value;
159 otherwise it is interpreted as microseconds.
161 .BR ADJ_MICRO " (since Linux 2.6.36)"
162 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
163 .\" Author: Roman Zippel <zippel@linux-m68k.org>
164 Select microsecond resolution.
166 .BR ADJ_NANO " (since Linux 2.6.36)"
167 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
168 .\" Author: Roman Zippel <zippel@linux-m68k.org>
169 Select nanosecond resolution.
176 .BR ADJ_TAI " (since Linux 2.6.26)"
177 .\" commit 153b5d054ac2d98ea0d86504884326b6777f683d
178 Set TAI (Atomic International Time) offset from
182 should not be used in conjunction with
184 since the latter mode also employs the
188 For a complete explanation of TAI
189 and the difference between TAI and UTC, see
190 .UR http://www.bipm.org/en/bipm/tai/tai.html
200 can be specified as either of the following (multibit mask) values,
201 in which case other bits should not be specified in
203 .\" In general, the other bits are ignored, but ADJ_OFFSET_SINGLESHOT 0x8001
204 .\" ORed with ADJ_NANO (0x2000) gives 0xa0001 == ADJ_OFFSET_SS_READ!!
206 .BR ADJ_OFFSET_SINGLESHOT
207 .\" In user space, ADJ_OFFSET_SINGLESHOT is 0x8001
208 .\" In kernel space it is 0x0001, and must be ANDed with ADJ_ADJTIME (0x8000)
211 (gradually) adjust time by value specified in
213 which specifies an adjustment in microseconds.
215 .BR ADJ_OFFSET_SS_READ " (functional since Linux 2.6.28)"
216 .\" In user space, ADJ_OFFSET_SS_READ is 0xa001
217 .\" In kernel space there is ADJ_OFFSET_READONLY (0x2000) anded with
218 .\" ADJ_ADJTIME (0x8000) and ADJ_OFFSET_SINGLESHOT (0x0001) to give 0xa001)
221 the remaining amount of time to be adjusted after an earlier
222 .BR ADJ_OFFSET_SINGLESHOT
224 This feature was added in Linux 2.6.24,
225 .\" commit 52bfb36050c8529d9031d2c2513b281a360922ec
226 but did not work correctly
227 .\" commit 916c7a855174e3b53d182b97a26b2e27a29726a1
230 Ordinary users are restricted to a value of either 0 or
231 .B ADJ_OFFSET_SS_READ
234 Only the superuser may set any parameters.
238 field is a bit mask that is used to set and/or retrieve status
239 bits associated with the NTP implementation.
240 Some bits in the mask are both readable and settable,
241 while others are read-only.
243 .BR STA_PLL " (read-write)"
244 Enable phase-locked loop (PLL) updates via
247 .BR STA_PPSFREQ " (read-write)"
248 Enable PPS (pulse-per-second) frequency discipline.
250 .BR STA_PPSTIME " (read-write)"
251 Enable PPS time discipline.
253 .BR STA_FLL " (read-write)"
254 Select frequency-locked loop (FLL) mode.
256 .BR STA_INS " (read-write)"
257 Insert a leap second after the last second of the UTC day,
258 thus extending the last minute of the day by one second.
259 Leap-second insertion will occur each day, so long as this flag remains set.
261 .\" Usually this is written as extending the day by one second,
262 .\" which is represented as:
267 .\" But since posix cannot represent 23:59:60, we repeat the last second:
268 .\" 23:59:59 + TIME_INS
269 .\" 23:59:59 + TIME_OOP
270 .\" 00:00:00 + TIME_WAIT
273 .BR STA_DEL " (read-write)"
274 Delete a leap second at the last second of the UTC day.
276 .\" Similarly the progression here is:
277 .\" 23:59:57 + TIME_DEL
278 .\" 23:59:58 + TIME_DEL
279 .\" 00:00:00 + TIME_WAIT
280 Leap second deletion will occur each day, so long as this flag
282 .\" FIXME Does there need to be a statement that it is nonsensical to set
283 .\" to set both STA_INS and STA_DEL?
285 .BR STA_UNSYNC " (read-write)"
286 Clock unsynchronized.
288 .BR STA_FREQHOLD " (read-write)"
290 .\" Following text from John Stultz:
291 Normally adjustments made via
293 result in dampened frequency adjustments also being made.
294 So a single call corrects the current offset,
295 but as offsets in the same direction are made repeatedly,
296 the small frequency adjustments will accumulate to fix the long-term skew.
298 This flag prevents the small frequency adjustment from being made
299 when correcting for an
302 .\" According to the Kernel Application Program Interface document,
303 .\" STA_FREQHOLD is not used by the NTP version 4 daemon
305 .BR STA_PPSSIGNAL " (read-only)"
306 A valid PPS (pulse-per-second) signal is present.
308 .BR STA_PPSJITTER " (read-only)"
309 PPS signal jitter exceeded.
311 .BR STA_PPSWANDER " (read-only)"
312 PPS signal wander exceeded.
314 .BR STA_PPSERROR " (read-only)"
315 PPS signal calibration error.
317 .BR STA_CLOCKERR " (read-only)"
318 Clock hardware fault.
319 .\" Not set in current kernel (4.5), but checked in a few places
321 .BR STA_NANO " (read-only; since Linux 2.6.26)"
322 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
323 .\" Author: Roman Zippel <zippel@linux-m68k.org>
324 Resolution (0 = microsecond, 1 = nanoseconds).
330 .BR STA_MODE " (since Linux 2.6.26)"
331 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
332 .\" Author: Roman Zippel <zippel@linux-m68k.org>
333 Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop).
335 .BR STA_CLK " (read-only; since Linux 2.6.26)"
336 .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db
337 .\" Author: Roman Zippel <zippel@linux-m68k.org>
338 Clock source (0 = A, 1 = B); currently unused.
340 Attempts to set read-only
342 bits are silently ignored.
348 (described in the NTP "Kernel Application Program API", KAPI)
349 is a more portable interface for performing the same task as
351 Other than the following points, it is identical to
354 The constants used in
356 are prefixed with "MOD_" rather than "ADJ_", and have the same suffixes (thus,
359 and so on), other than the exceptions noted in the following points.
363 .BR ADJ_OFFSET_SINGLESHOT .
369 The is no synonym for
370 .BR ADJ_OFFSET_SS_READ ,
371 which is not described in the KAPI.
377 return the clock state; that is, one of the following values:
380 Clock synchronized, no leap second adjustment pending.
383 Indicates that a leap second will be added at the end of the UTC day.
386 Indicates that a leap second will be deleted at the end of the UTC day.
389 Insertion of a leap second is in progress.
392 A leap-second insertion or deletion has been completed.
393 This value will be returned until the next
402 The system clock is not synchronized to a reliable server.
403 This value is returned when any of the following holds true:
436 provided for backward compatibility.
438 Note that starting with Linux 3.4,
439 .\" commit 6b43ae8a619d17c4935c3320d2ef9e92bdeed05d changed to asynchronous
440 .\" operation, so we can no longer rely on the return code.
441 the call operates asynchronously and the return value usually will
442 not reflect a state change caused by the call itself.
444 On failure, these calls return \-1 and set
450 does not point to writable memory.
452 .BR EINVAL " (kernels before Linux 2.6.26)"
453 An attempt was made to set
455 to a value outside the range (\-33554432, +33554432).
456 .\" From a quck glance, it appears there was no clamping or range check
457 .\" for buf.freq in kernels before 2.0
459 .BR EINVAL " (kernels before Linux 2.6.26)"
460 An attempt was made to set
462 to a value outside the permitted range.
463 In kernels before Linux 2.0, the permitted range was (\-131072, +131072).
464 From Linux 2.0 onwards, the permitted range was (\-512000, +512000).
467 An attempt was made to set
469 to a value other than those listed above.
472 An attempt was made to set
474 to a value outside the range
480 is the system timer interrupt frequency.
485 .BR ADJ_OFFSET_SS_READ ,
486 and the caller does not have sufficient privilege.
489 capability is required.
497 are ppm (parts per million) with a 16-bit fractional part,
498 which means that a value of 1 in one of those fields
499 actually means 2^-16 ppm, and 2^16=65536 is 1 ppm.
500 This is the case for both input values (in the case of
504 The leap-second processing triggered vy
508 is done by the kernel in timer context
509 Thus, it will take one tick into the second
510 for the leap second to be inserted or deleted.
512 Neither of these interfaces is described in POSIX.1
515 is Linux-specific and should not be used in programs
516 intended to be portable.
518 The preferred API for NTP daemon is
520 which is described in the NTP KAPI documentation.
522 .BR settimeofday (2),
524 .\" .BR ntp_gettime (3),
525 .BR capabilities (7),
530 .UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm
531 NTP "Kernel Application Program Interface"