1ADJTIMEX(2) Linux Programmer's Manual ADJTIMEX(2)
2
6 adjtimex, clock_adjtime, ntp_adjtime - tune kernel clock
7
9 #include <sys/timex.h>
10 int adjtimex(struct timex *buf);
12 int clock_adjtime(clockid_t clk_id, struct timex *buf);
14 int ntp_adjtime(struct timex *buf);
16
18 Linux uses David L. Mills' clock adjustment algorithm (see RFC 5905).
19 The system call adjtimex() reads and optionally sets adjustment parame‐
20 ters for this algorithm. It takes a pointer to a timex structure, up‐
21 dates kernel parameters from (selected) field values, and returns the
22 same structure updated with the current kernel values. This structure
23 is declared as follows:
24 struct timex {
26 int modes; /* Mode selector */
27 long offset; /* Time offset; nanoseconds, if STA_NANO
28 status flag is set, otherwise
29 microseconds */
30 long freq; /* Frequency offset; see NOTES for units */
31 long maxerror; /* Maximum error (microseconds) */
32 long esterror; /* Estimated error (microseconds) */
33 int status; /* Clock command/status */
34 long constant; /* PLL (phase-locked loop) time constant */
35 long precision; /* Clock precision
36 (microseconds, read-only) */
37 long tolerance; /* Clock frequency tolerance (read-only);
38 see NOTES for units */
39 struct timeval time;
40 /* Current time (read-only, except for
41 ADJ_SETOFFSET); upon return, time.tv_usec
42 contains nanoseconds, if STA_NANO status
43 flag is set, otherwise microseconds */
44 long tick; /* Microseconds between clock ticks */
45 long ppsfreq; /* PPS (pulse per second) frequency
46 (read-only); see NOTES for units */
47 long jitter; /* PPS jitter (read-only); nanoseconds, if
48 STA_NANO status flag is set, otherwise
49 microseconds */
50 int shift; /* PPS interval duration
51 (seconds, read-only) */
52 long stabil; /* PPS stability (read-only);
53 see NOTES for units */
54 long jitcnt; /* PPS count of jitter limit exceeded
55 events (read-only) */
56 long calcnt; /* PPS count of calibration intervals
57 (read-only) */
58 long errcnt; /* PPS count of calibration errors
59 (read-only) */
60 long stbcnt; /* PPS count of stability limit exceeded
61 events (read-only) */
62 int tai; /* TAI offset, as set by previous ADJ_TAI
63 operation (seconds, read-only,
64 since Linux 2.6.26) */
65 /* Further padding bytes to allow for future expansion */
66 };
67 The modes field determines which parameters, if any, to set. (As de‐
69 scribed later in this page, the constants used for ntp_adjtime() are
70 equivalent but differently named.) It is a bit mask containing a bit‐
71 wise-or combination of zero or more of the following bits:
72 ADJ_OFFSET
74 Set time offset from buf.offset. Since Linux 2.6.26, the sup‐
75 plied value is clamped to the range (-0.5s, +0.5s). In older
76 kernels, an EINVAL error occurs if the supplied value is out of
77 range.
78 ADJ_FREQUENCY
80 Set frequency offset from buf.freq. Since Linux 2.6.26, the
81 supplied value is clamped to the range (-32768000, +32768000).
82 In older kernels, an EINVAL error occurs if the supplied value
83 is out of range.
84 ADJ_MAXERROR
86 Set maximum time error from buf.maxerror.
87 ADJ_ESTERROR
89 Set estimated time error from buf.esterror.
90 ADJ_STATUS
92 Set clock status bits from buf.status. A description of these
93 bits is provided below.
94 ADJ_TIMECONST
96 Set PLL time constant from buf.constant. If the STA_NANO status
97 flag (see below) is clear, the kernel adds 4 to this value.
98 ADJ_SETOFFSET (since Linux 2.6.39)
100 Add buf.time to the current time. If buf.status includes the
101 ADJ_NANO flag, then buf.time.tv_usec is interpreted as a
102 nanosecond value; otherwise it is interpreted as microseconds.
103 The value of buf.time is the sum of its two fields, but the
105 field buf.time.tv_usec must always be nonnegative. The follow‐
106 ing example shows how to normalize a timeval with nanosecond
107 resolution.
108 while (buf.time.tv_usec < 0) {
110 buf.time.tv_sec -= 1;
111 buf.time.tv_usec += 1000000000;
112 }
113 ADJ_MICRO (since Linux 2.6.26)
115 Select microsecond resolution.
116 ADJ_NANO (since Linux 2.6.26)
118 Select nanosecond resolution. Only one of ADJ_MICRO and
119 ADJ_NANO should be specified.
120 ADJ_TAI (since Linux 2.6.26)
122 Set TAI (Atomic International Time) offset from buf.constant.
123 ADJ_TAI should not be used in conjunction with ADJ_TIMECONST,
125 since the latter mode also employs the buf.constant field.
126 For a complete explanation of TAI and the difference between TAI
128 and UTC, see BIPM ⟨http://www.bipm.org/en/bipm/tai/tai.html⟩
129 ADJ_TICK
131 Set tick value from buf.tick.
132 Alternatively, modes can be specified as either of the following
134 (multibit mask) values, in which case other bits should not be speci‐
135 fied in modes:
136 ADJ_OFFSET_SINGLESHOT
138 Old-fashioned adjtime(3): (gradually) adjust time by value spec‐
139 ified in buf.offset, which specifies an adjustment in microsec‐
140 onds.
141 ADJ_OFFSET_SS_READ (functional since Linux 2.6.28)
143 Return (in buf.offset) the remaining amount of time to be ad‐
144 justed after an earlier ADJ_OFFSET_SINGLESHOT operation. This
145 feature was added in Linux 2.6.24, but did not work correctly
146 until Linux 2.6.28.
147 Ordinary users are restricted to a value of either 0 or ADJ_OFF‐
149 SET_SS_READ for modes. Only the superuser may set any parameters.
150 The buf.status field is a bit mask that is used to set and/or retrieve
152 status bits associated with the NTP implementation. Some bits in the
153 mask are both readable and settable, while others are read-only.
154 STA_PLL (read-write)
156 Enable phase-locked loop (PLL) updates via ADJ_OFFSET.
157 STA_PPSFREQ (read-write)
159 Enable PPS (pulse-per-second) frequency discipline.
160 STA_PPSTIME (read-write)
162 Enable PPS time discipline.
163 STA_FLL (read-write)
165 Select frequency-locked loop (FLL) mode.
166 STA_INS (read-write)
168 Insert a leap second after the last second of the UTC day, thus
169 extending the last minute of the day by one second. Leap-second
170 insertion will occur each day, so long as this flag remains set.
171 STA_DEL (read-write)
173 Delete a leap second at the last second of the UTC day. Leap
174 second deletion will occur each day, so long as this flag re‐
175 mains set.
176 STA_UNSYNC (read-write)
178 Clock unsynchronized.
179 STA_FREQHOLD (read-write)
181 Hold frequency. Normally adjustments made via ADJ_OFFSET result
182 in dampened frequency adjustments also being made. So a single
183 call corrects the current offset, but as offsets in the same di‐
184 rection are made repeatedly, the small frequency adjustments
185 will accumulate to fix the long-term skew.
186 This flag prevents the small frequency adjustment from being
188 made when correcting for an ADJ_OFFSET value.
189 STA_PPSSIGNAL (read-only)
191 A valid PPS (pulse-per-second) signal is present.
192 STA_PPSJITTER (read-only)
194 PPS signal jitter exceeded.
195 STA_PPSWANDER (read-only)
197 PPS signal wander exceeded.
198 STA_PPSERROR (read-only)
200 PPS signal calibration error.
201 STA_CLOCKERR (read-only)
203 Clock hardware fault.
204 STA_NANO (read-only; since Linux 2.6.26)
206 Resolution (0 = microsecond, 1 = nanoseconds). Set via
207 ADJ_NANO, cleared via ADJ_MICRO.
208 STA_MODE (since Linux 2.6.26)
210 Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop).
211 STA_CLK (read-only; since Linux 2.6.26)
213 Clock source (0 = A, 1 = B); currently unused.
214 Attempts to set read-only status bits are silently ignored.
216 clock_adjtime ()
218 The clock_adjtime() system call (added in Linux 2.6.39) behaves like
219 adjtimex() but takes an additional clk_id argument to specify the par‐
220 ticular clock on which to act.
221 ntp_adjtime ()
223 The ntp_adjtime() library function (described in the NTP "Kernel Appli‐
224 cation Program API", KAPI) is a more portable interface for performing
225 the same task as adjtimex(). Other than the following points, it is
226 identical to adjtimex():
227 * The constants used in modes are prefixed with "MOD_" rather than
229 "ADJ_", and have the same suffixes (thus, MOD_OFFSET, MOD_FREQUENCY,
230 and so on), other than the exceptions noted in the following points.
231 * MOD_CLKA is the synonym for ADJ_OFFSET_SINGLESHOT.
233 * MOD_CLKB is the synonym for ADJ_TICK.
235 * The is no synonym for ADJ_OFFSET_SS_READ, which is not described in
237 the KAPI.
238
240 On success, adjtimex() and ntp_adjtime() return the clock state; that
241 is, one of the following values:
242 TIME_OK Clock synchronized, no leap second adjustment pending.
244 TIME_INS Indicates that a leap second will be added at the end of
246 the UTC day.
247 TIME_DEL Indicates that a leap second will be deleted at the end of
249 the UTC day.
250 TIME_OOP Insertion of a leap second is in progress.
252 TIME_WAIT A leap-second insertion or deletion has been completed.
254 This value will be returned until the next ADJ_STATUS oper‐
255 ation clears the STA_INS and STA_DEL flags.
256 TIME_ERROR The system clock is not synchronized to a reliable server.
258 This value is returned when any of the following holds
259 true:
260 * Either STA_UNSYNC or STA_CLOCKERR is set.
262 * STA_PPSSIGNAL is clear and either STA_PPSFREQ or STA_PP‐
264 STIME is set.
265 * STA_PPSTIME and STA_PPSJITTER are both set.
267 * STA_PPSFREQ is set and either STA_PPSWANDER or STA_PP‐
269 SJITTER is set.
270 The symbolic name TIME_BAD is a synonym for TIME_ERROR,
272 provided for backward compatibility.
273 Note that starting with Linux 3.4, the call operates asynchronously and
275 the return value usually will not reflect a state change caused by the
276 call itself.
277 On failure, these calls return -1 and set errno to indicate the error.
279
281 EFAULT buf does not point to writable memory.
282 EINVAL (kernels before Linux 2.6.26)
284 An attempt was made to set buf.freq to a value outside the range
285 (-33554432, +33554432).
286 EINVAL (kernels before Linux 2.6.26)
288 An attempt was made to set buf.offset to a value outside the
289 permitted range. In kernels before Linux 2.0, the permitted
290 range was (-131072, +131072). From Linux 2.0 onwards, the per‐
291 mitted range was (-512000, +512000).
292 EINVAL An attempt was made to set buf.status to a value other than
294 those listed above.
295 EINVAL The clk_id given to clock_adjtime() is invalid for one of two
297 reasons. Either the System-V style hard-coded positive clock ID
298 value is out of range, or the dynamic clk_id does not refer to a
299 valid instance of a clock object. See clock_gettime(2) for a
300 discussion of dynamic clocks.
301 EINVAL An attempt was made to set buf.tick to a value outside the range
303 900000/HZ to 1100000/HZ, where HZ is the system timer interrupt
304 frequency.
305 ENODEV The hot-pluggable device (like USB for example) represented by a
307 dynamic clk_id has disappeared after its character device was
308 opened. See clock_gettime(2) for a discussion of dynamic
309 clocks.
310 EOPNOTSUPP
312 The given clk_id does not support adjustment.
313 EPERM buf.modes is neither 0 nor ADJ_OFFSET_SS_READ, and the caller
315 does not have sufficient privilege. Under Linux, the
316 CAP_SYS_TIME capability is required.
317
319 For an explanation of the terms used in this section, see at‐
320 tributes(7).
321 ┌────────────────────────────────────────────┬───────────────┬─────────┐
323 │Interface │ Attribute │ Value │
324 ├────────────────────────────────────────────┼───────────────┼─────────┤
325 │ntp_adjtime() │ Thread safety │ MT-Safe │
326 └────────────────────────────────────────────┴───────────────┴─────────┘
327
329 None of these interfaces is described in POSIX.1
330 adjtimex() and clock_adjtime() are Linux-specific and should not be
332 used in programs intended to be portable.
333 The preferred API for the NTP daemon is ntp_adjtime().
335
337 In struct timex, freq, ppsfreq, and stabil are ppm (parts per million)
338 with a 16-bit fractional part, which means that a value of 1 in one of
339 those fields actually means 2^-16 ppm, and 2^16=65536 is 1 ppm. This
340 is the case for both input values (in the case of freq) and output val‐
341 ues.
342 The leap-second processing triggered by STA_INS and STA_DEL is done by
344 the kernel in timer context. Thus, it will take one tick into the sec‐
345 ond for the leap second to be inserted or deleted.
346
348 clock_gettime(2), clock_settime(2), settimeofday(2), adjtime(3),
349 ntp_gettime(3), capabilities(7), time(7), adjtimex(8), hwclock(8)
350 NTP "Kernel Application Program Interface"
352 ⟨http://www.slac.stanford.edu/comp/unix/package/rtems/src/ssrlApps/
353 ntpNanoclock/api.htm⟩
354
356 This page is part of release 5.13 of the Linux man-pages project. A
357 description of the project, information about reporting bugs, and the
358 latest version of this page, can be found at
359 https://www.kernel.org/doc/man-pages/.
360Linux 2021-03-22 ADJTIMEX(2)