1adjtimex(2)                   System Calls Manual                  adjtimex(2)
2
3
4

NAME

6       adjtimex, clock_adjtime, ntp_adjtime - tune kernel clock
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <sys/timex.h>
13
14       int adjtimex(struct timex *buf);
15
16       int clock_adjtime(clockid_t clk_id, struct timex *buf);
17
18       int ntp_adjtime(struct timex *buf);
19

DESCRIPTION

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
28           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
71       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
76       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
82       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
88       ADJ_MAXERROR
89              Set maximum time error from buf.maxerror.
90
91       ADJ_ESTERROR
92              Set estimated time error from buf.esterror.
93
94       ADJ_STATUS
95              Set  clock  status bits from buf.status.  A description of these
96              bits is provided below.
97
98       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
102       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
107              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
112                  while (buf.time.tv_usec < 0) {
113                      buf.time.tv_sec  -= 1;
114                      buf.time.tv_usec += 1000000000;
115                  }
116
117       ADJ_MICRO (since Linux 2.6.26)
118              Select microsecond resolution.
119
120       ADJ_NANO (since Linux 2.6.26)
121              Select  nanosecond  resolution.   Only  one  of  ADJ_MICRO   and
122              ADJ_NANO should be specified.
123
124       ADJ_TAI (since Linux 2.6.26)
125              Set TAI (Atomic International Time) offset from buf.constant.
126
127              ADJ_TAI  should  not  be used in conjunction with ADJ_TIMECONST,
128              since the latter mode also employs the buf.constant field.
129
130              For a complete explanation of TAI and the difference between TAI
131              and UTC, see BIPMhttp://www.bipm.org/en/bipm/tai/tai.html
132
133       ADJ_TICK
134              Set tick value from buf.tick.
135
136       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
140       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
145       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
151       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
154       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
158       STA_PLL (read-write)
159              Enable phase-locked loop (PLL) updates via ADJ_OFFSET.
160
161       STA_PPSFREQ (read-write)
162              Enable PPS (pulse-per-second) frequency discipline.
163
164       STA_PPSTIME (read-write)
165              Enable PPS time discipline.
166
167       STA_FLL (read-write)
168              Select frequency-locked loop (FLL) mode.
169
170       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
175       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
180       STA_UNSYNC (read-write)
181              Clock unsynchronized.
182
183       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
190              This  flag  prevents  the  small frequency adjustment from being
191              made when correcting for an ADJ_OFFSET value.
192
193       STA_PPSSIGNAL (read-only)
194              A valid PPS (pulse-per-second) signal is present.
195
196       STA_PPSJITTER (read-only)
197              PPS signal jitter exceeded.
198
199       STA_PPSWANDER (read-only)
200              PPS signal wander exceeded.
201
202       STA_PPSERROR (read-only)
203              PPS signal calibration error.
204
205       STA_CLOCKERR (read-only)
206              Clock hardware fault.
207
208       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
212       STA_MODE (since Linux 2.6.26)
213              Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop).
214
215       STA_CLK (read-only; since Linux 2.6.26)
216              Clock source (0 = A, 1 = B); currently unused.
217
218       Attempts to set read-only status bits are silently ignored.
219
220   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
225   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
231       •  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
235MOD_CLKA is the synonym for ADJ_OFFSET_SINGLESHOT.
236
237MOD_CLKB is the synonym for ADJ_TICK.
238
239       •  The is no synonym for ADJ_OFFSET_SS_READ, which is not described  in
240          the KAPI.
241

RETURN VALUE

243       On  success,  adjtimex() and ntp_adjtime() return the clock state; that
244       is, one of the following values:
245
246       TIME_OK     Clock synchronized, no leap second adjustment pending.
247
248       TIME_INS    Indicates that a leap second will be added at  the  end  of
249                   the UTC day.
250
251       TIME_DEL    Indicates  that a leap second will be deleted at the end of
252                   the UTC day.
253
254       TIME_OOP    Insertion of a leap second is in progress.
255
256       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
260       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
264                   •  Either STA_UNSYNC or STA_CLOCKERR is set.
265
266STA_PPSSIGNAL is clear and either STA_PPSFREQ or STA_PP‐
267                      STIME is set.
268
269STA_PPSTIME and STA_PPSJITTER are both set.
270
271STA_PPSFREQ  is  set and either STA_PPSWANDER or STA_PP‐
272                      SJITTER is set.
273
274                   The symbolic name TIME_BAD is  a  synonym  for  TIME_ERROR,
275                   provided for backward compatibility.
276
277       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
281       On failure, these calls return -1 and set errno to indicate the error.
282

ERRORS

284       EFAULT buf does not point to writable memory.
285
286       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
290       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
296       EINVAL An  attempt  was  made  to  set buf.status to a value other than
297              those listed above.
298
299       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
305       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
309       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
314       EOPNOTSUPP
315              The given clk_id does not support adjustment.
316
317       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

ATTRIBUTES

322       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
323       tributes(7).
324
325       ┌────────────────────────────────────────────┬───────────────┬─────────┐
326Interface                                   Attribute     Value   
327       ├────────────────────────────────────────────┼───────────────┼─────────┤
328ntp_adjtime()                               │ Thread safety │ MT-Safe │
329       └────────────────────────────────────────────┴───────────────┴─────────┘
330

STANDARDS

332       adjtimex()
333       clock_adjtime()
334              Linux.
335
336       The preferred API for the NTP daemon is ntp_adjtime().
337

NOTES

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
345       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

SEE ALSO

350       clock_gettime(2),   clock_settime(2),   settimeofday(2),    adjtime(3),
351       ntp_gettime(3), capabilities(7), time(7), adjtimex(8), hwclock(8)
352
353       NTP "Kernel Application Program Interface"
354http://www.slac.stanford.edu/comp/unix/package/rtems/src/ssrlApps/
355       ntpNanoclock/api.htm⟩
356
357
358
359Linux man-pages 6.05              2023-07-20                       adjtimex(2)
Impressum