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