1ADJTIMEX(2) Linux Programmer's Manual ADJTIMEX(2)
2
6 adjtimex, ntp_adjtime - tune kernel clock
7
9 #include <sys/timex.h>
10 int adjtimex(struct timex *buf);
12 int ntp_adjtime(struct timex *buf);
14
16 Linux uses David L. Mills' clock adjustment algorithm (see RFC 5905).
17 The system call adjtimex() reads and optionally sets adjustment parame‐
18 ters for this algorithm. It takes a pointer to a timex structure,
19 updates kernel parameters from (selected) field values, and returns the
20 same structure updated with the current kernel values. This structure
21 is declared as follows:
22 struct timex {
24 int modes; /* Mode selector */
25 long offset; /* Time offset; nanoseconds, if STA_NANO
26 status flag is set, otherwise
27 microseconds */
28 long freq; /* Frequency offset; see NOTES for units */
29 long maxerror; /* Maximum error (microseconds) */
30 long esterror; /* Estimated error (microseconds) */
31 int status; /* Clock command/status */
32 long constant; /* PLL (phase-locked loop) time constant */
33 long precision; /* Clock precision
34 (microseconds, read-only) */
35 long tolerance; /* Clock frequency tolerance (read-only);
36 see NOTES for units */
37 struct timeval time;
38 /* Current time (read-only, except for
39 ADJ_SETOFFSET); upon return, time.tv_usec
40 contains nanoseconds, if STA_NANO status
41 flag is set, otherwise microseconds */
42 long tick; /* Microseconds between clock ticks */
43 long ppsfreq; /* PPS (pulse per second) frequency
44 (read-only); see NOTES for units */
45 long jitter; /* PPS jitter (read-only); nanoseconds, if
46 STA_NANO status flag is set, otherwise
47 microseconds */
48 int shift; /* PPS interval duration
49 (seconds, read-only) */
50 long stabil; /* PPS stability (read-only);
51 see NOTES for units */
52 long jitcnt; /* PPS count of jitter limit exceeded
53 events (read-only) */
54 long calcnt; /* PPS count of calibration intervals
55 (read-only) */
56 long errcnt; /* PPS count of calibration errors
57 (read-only) */
58 long stbcnt; /* PPS count of stability limit exceeded
59 events (read-only) */
60 int tai; /* TAI offset, as set by previous ADJ_TAI
61 operation (seconds, read-only,
62 since Linux 2.6.26) */
63 /* Further padding bytes to allow for future expansion */
64 };
65 The modes field determines which parameters, if any, to set. (As
67 described later in this page, the constants used for ntp_adjtime() are
68 equivalent but differently named.) It is a bit mask containing a bit‐
69 wise-or combination of zero or more of the following bits:
70 ADJ_OFFSET
72 Set time offset from buf.offset. Since Linux 2.6.26, the sup‐
73 plied value is clamped to the range (-0.5s, +0.5s). In older
74 kernels, an EINVAL error occurs if the supplied value is out of
75 range.
76 ADJ_FREQUENCY
78 Set frequency offset from buf.freq. Since Linux 2.6.26, the
79 supplied value is clamped to the range (-32768000, +32768000).
80 In older kernels, an EINVAL error occurs if the supplied value
81 is out of range.
82 ADJ_MAXERROR
84 Set maximum time error from buf.maxerror.
85 ADJ_ESTERROR
87 Set estimated time error from buf.esterror.
88 ADJ_STATUS
90 Set clock status bits from buf.status. A description of these
91 bits is provided below.
92 ADJ_TIMECONST
94 Set PLL time constant from buf.constant. If the STA_NANO status
95 flag (see below) is clear, the kernel adds 4 to this value.
96 ADJ_SETOFFSET (since Linux 2.6.39)
98 Add buf.time to the current time. If buf.status includes the
99 ADJ_NANO flag, then buf.time.tv_usec is interpreted as a
100 nanosecond value; otherwise it is interpreted as microseconds.
101 ADJ_MICRO (since Linux 2.6.26)
103 Select microsecond resolution.
104 ADJ_NANO (since Linux 2.6.26)
106 Select nanosecond resolution. Only one of ADJ_MICRO and
107 ADJ_NANO should be specified.
108 ADJ_TAI (since Linux 2.6.26)
110 Set TAI (Atomic International Time) offset from buf.constant.
111 ADJ_TAI should not be used in conjunction with ADJ_TIMECONST,
113 since the latter mode also employs the buf.constant field.
114 For a complete explanation of TAI and the difference between TAI
116 and UTC, see BIPM ⟨http://www.bipm.org/en/bipm/tai/tai.html⟩
117 ADJ_TICK
119 Set tick value from buf.tick.
120 Alternatively, modes can be specified as either of the following
122 (multibit mask) values, in which case other bits should not be speci‐
123 fied in modes:
124 ADJ_OFFSET_SINGLESHOT
126 Old-fashioned adjtime(): (gradually) adjust time by value speci‐
127 fied in buf.offset, which specifies an adjustment in microsec‐
128 onds.
129 ADJ_OFFSET_SS_READ (functional since Linux 2.6.28)
131 Return (in buf.offset) the remaining amount of time to be
132 adjusted after an earlier ADJ_OFFSET_SINGLESHOT operation. This
133 feature was added in Linux 2.6.24, but did not work correctly
134 until Linux 2.6.28.
135 Ordinary users are restricted to a value of either 0 or ADJ_OFF‐
137 SET_SS_READ for modes. Only the superuser may set any parameters.
138 The buf.status field is a bit mask that is used to set and/or retrieve
140 status bits associated with the NTP implementation. Some bits in the
141 mask are both readable and settable, while others are read-only.
142 STA_PLL (read-write)
144 Enable phase-locked loop (PLL) updates via ADJ_OFFSET.
145 STA_PPSFREQ (read-write)
147 Enable PPS (pulse-per-second) frequency discipline.
148 STA_PPSTIME (read-write)
150 Enable PPS time discipline.
151 STA_FLL (read-write)
153 Select frequency-locked loop (FLL) mode.
154 STA_INS (read-write)
156 Insert a leap second after the last second of the UTC day, thus
157 extending the last minute of the day by one second. Leap-second
158 insertion will occur each day, so long as this flag remains set.
159 STA_DEL (read-write)
161 Delete a leap second at the last second of the UTC day. Leap
162 second deletion will occur each day, so long as this flag
163 remains set.
164 STA_UNSYNC (read-write)
166 Clock unsynchronized.
167 STA_FREQHOLD (read-write)
169 Hold frequency. Normally adjustments made via ADJ_OFFSET result
170 in dampened frequency adjustments also being made. So a single
171 call corrects the current offset, but as offsets in the same
172 direction are made repeatedly, the small frequency adjustments
173 will accumulate to fix the long-term skew.
174 This flag prevents the small frequency adjustment from being
176 made when correcting for an ADJ_OFFSET value.
177 STA_PPSSIGNAL (read-only)
179 A valid PPS (pulse-per-second) signal is present.
180 STA_PPSJITTER (read-only)
182 PPS signal jitter exceeded.
183 STA_PPSWANDER (read-only)
185 PPS signal wander exceeded.
186 STA_PPSERROR (read-only)
188 PPS signal calibration error.
189 STA_CLOCKERR (read-only)
191 Clock hardware fault.
192 STA_NANO (read-only; since Linux 2.6.26)
194 Resolution (0 = microsecond, 1 = nanoseconds). Set via
195 ADJ_NANO, cleared via ADJ_MICRO.
196 STA_MODE (since Linux 2.6.26)
198 Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop).
199 STA_CLK (read-only; since Linux 2.6.26)
201 Clock source (0 = A, 1 = B); currently unused.
202 Attempts to set read-only status bits are silently ignored.
204 ntp_adjtime ()
206 The ntp_adjtime() library function (described in the NTP "Kernel Appli‐
207 cation Program API", KAPI) is a more portable interface for performing
208 the same task as adjtimex(). Other than the following points, it is
209 identical to adjtime():
210 * The constants used in modes are prefixed with "MOD_" rather than
212 "ADJ_", and have the same suffixes (thus, MOD_OFFSET, MOD_FREQUENCY,
213 and so on), other than the exceptions noted in the following points.
214 * MOD_CLKA is the synonym for ADJ_OFFSET_SINGLESHOT.
216 * MOD_CLKB is the synonym for ADJ_TICK.
218 * The is no synonym for ADJ_OFFSET_SS_READ, which is not described in
220 the KAPI.
221
223 On success, adjtimex() and ntp_adjtime() return the clock state; that
224 is, one of the following values:
225 TIME_OK Clock synchronized, no leap second adjustment pending.
227 TIME_INS Indicates that a leap second will be added at the end of
229 the UTC day.
230 TIME_DEL Indicates that a leap second will be deleted at the end of
232 the UTC day.
233 TIME_OOP Insertion of a leap second is in progress.
235 TIME_WAIT A leap-second insertion or deletion has been completed.
237 This value will be returned until the next ADJ_STATUS oper‐
238 ation clears the STA_INS and STA_DEL flags.
239 TIME_ERROR The system clock is not synchronized to a reliable server.
241 This value is returned when any of the following holds
242 true:
243 * Either STA_UNSYNC or STA_CLOCKERR is set.
245 * STA_PPSSIGNAL is clear and either STA_PPSFREQ or
247 STA_PPSTIME is set.
248 * STA_PPSTIME and STA_PPSJITTER are both set.
250 * STA_PPSFREQ is set and either STA_PPSWANDER or
252 STA_PPSJITTER is set.
253 The symbolic name TIME_BAD is a synonym for TIME_ERROR,
255 provided for backward compatibility.
256 Note that starting with Linux 3.4, the call operates asynchronously and
258 the return value usually will not reflect a state change caused by the
259 call itself.
260 On failure, these calls return -1 and set errno.
262
264 EFAULT buf does not point to writable memory.
265 EINVAL (kernels before Linux 2.6.26)
267 An attempt was made to set buf.freq to a value outside the range
268 (-33554432, +33554432).
269 EINVAL (kernels before Linux 2.6.26)
271 An attempt was made to set buf.offset to a value outside the
272 permitted range. In kernels before Linux 2.0, the permitted
273 range was (-131072, +131072). From Linux 2.0 onwards, the per‐
274 mitted range was (-512000, +512000).
275 EINVAL An attempt was made to set buf.status to a value other than
277 those listed above.
278 EINVAL An attempt was made to set buf.tick to a value outside the range
280 900000/HZ to 1100000/HZ, where HZ is the system timer interrupt
281 frequency.
282 EPERM buf.modes is neither 0 nor ADJ_OFFSET_SS_READ, and the caller
284 does not have sufficient privilege. Under Linux, the
285 CAP_SYS_TIME capability is required.
286
288 For an explanation of the terms used in this section, see
289 attributes(7).
290 ┌──────────────┬───────────────┬─────────┐
292 │Interface │ Attribute │ Value │
293 ├──────────────┼───────────────┼─────────┤
294 │ntp_adjtime() │ Thread safety │ MT-Safe │
295 └──────────────┴───────────────┴─────────┘
297 Neither of these interfaces is described in POSIX.1
298 adjtimex() is Linux-specific and should not be used in programs
300 intended to be portable.
301 The preferred API for the NTP daemon is ntp_adjtime().
303
305 In struct timex, freq, ppsfreq, and stabil are ppm (parts per million)
306 with a 16-bit fractional part, which means that a value of 1 in one of
307 those fields actually means 2^-16 ppm, and 2^16=65536 is 1 ppm. This
308 is the case for both input values (in the case of freq) and output val‐
309 ues.
310 The leap-second processing triggered by STA_INS and STA_DEL is done by
312 the kernel in timer context. Thus, it will take one tick into the sec‐
313 ond for the leap second to be inserted or deleted.
314
316 settimeofday(2), adjtime(3), ntp_gettime(3), capabilities(7), time(7),
317 adjtimex(8), hwclock(8)
318 NTP "Kernel Application Program Interface"
320 ⟨http://www.slac.stanford.edu/comp/unix/package/rtems/src/ssrlApps/
321 ntpNanoclock/api.htm⟩
322
324 This page is part of release 5.04 of the Linux man-pages project. A
325 description of the project, information about reporting bugs, and the
326 latest version of this page, can be found at
327 https://www.kernel.org/doc/man-pages/.
328Linux 2019-03-06 ADJTIMEX(2)