1ADJTIMEX(2)                Linux Programmer's Manual               ADJTIMEX(2)
2
3
4

NAME

6       adjtimex, clock_adjtime, ntp_adjtime - tune kernel clock
7

SYNOPSIS

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

DESCRIPTION

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
25           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
68       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
73       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
79       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
85       ADJ_MAXERROR
86              Set maximum time error from buf.maxerror.
87
88       ADJ_ESTERROR
89              Set estimated time error from buf.esterror.
90
91       ADJ_STATUS
92              Set  clock  status bits from buf.status.  A description of these
93              bits is provided below.
94
95       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
99       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
104              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
109                  while (buf.time.tv_usec < 0) {
110                      buf.time.tv_sec  -= 1;
111                      buf.time.tv_usec += 1000000000;
112                  }
113
114       ADJ_MICRO (since Linux 2.6.26)
115              Select microsecond resolution.
116
117       ADJ_NANO (since Linux 2.6.26)
118              Select  nanosecond  resolution.   Only  one  of  ADJ_MICRO   and
119              ADJ_NANO should be specified.
120
121       ADJ_TAI (since Linux 2.6.26)
122              Set TAI (Atomic International Time) offset from buf.constant.
123
124              ADJ_TAI  should  not  be used in conjunction with ADJ_TIMECONST,
125              since the latter mode also employs the buf.constant field.
126
127              For a complete explanation of TAI and the difference between TAI
128              and UTC, see BIPMhttp://www.bipm.org/en/bipm/tai/tai.html
129
130       ADJ_TICK
131              Set tick value from buf.tick.
132
133       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
137       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
142       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
148       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
151       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
155       STA_PLL (read-write)
156              Enable phase-locked loop (PLL) updates via ADJ_OFFSET.
157
158       STA_PPSFREQ (read-write)
159              Enable PPS (pulse-per-second) frequency discipline.
160
161       STA_PPSTIME (read-write)
162              Enable PPS time discipline.
163
164       STA_FLL (read-write)
165              Select frequency-locked loop (FLL) mode.
166
167       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
172       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
177       STA_UNSYNC (read-write)
178              Clock unsynchronized.
179
180       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
187              This  flag  prevents  the  small frequency adjustment from being
188              made when correcting for an ADJ_OFFSET value.
189
190       STA_PPSSIGNAL (read-only)
191              A valid PPS (pulse-per-second) signal is present.
192
193       STA_PPSJITTER (read-only)
194              PPS signal jitter exceeded.
195
196       STA_PPSWANDER (read-only)
197              PPS signal wander exceeded.
198
199       STA_PPSERROR (read-only)
200              PPS signal calibration error.
201
202       STA_CLOCKERR (read-only)
203              Clock hardware fault.
204
205       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
209       STA_MODE (since Linux 2.6.26)
210              Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop).
211
212       STA_CLK (read-only; since Linux 2.6.26)
213              Clock source (0 = A, 1 = B); currently unused.
214
215       Attempts to set read-only status bits are silently ignored.
216
217   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
222   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
228       *  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
232       *  MOD_CLKA is the synonym for ADJ_OFFSET_SINGLESHOT.
233
234       *  MOD_CLKB is the synonym for ADJ_TICK.
235
236       *  The is no synonym for ADJ_OFFSET_SS_READ, which is not described  in
237          the KAPI.
238

RETURN VALUE

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

ERRORS

281       EFAULT buf does not point to writable memory.
282
283       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
287       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
293       EINVAL An  attempt  was  made  to  set buf.status to a value other than
294              those listed above.
295
296       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
302       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
306       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
311       EOPNOTSUPP
312              The given clk_id does not support adjustment.
313
314       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

ATTRIBUTES

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

CONFORMING TO

329       None of these interfaces is described in POSIX.1
330
331       adjtimex() and clock_adjtime() are Linux-specific  and  should  not  be
332       used in programs intended to be portable.
333
334       The preferred API for the NTP daemon is ntp_adjtime().
335

NOTES

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

SEE ALSO

348       clock_gettime(2),    clock_settime(2),   settimeofday(2),   adjtime(3),
349       ntp_gettime(3), capabilities(7), time(7), adjtimex(8), hwclock(8)
350
351       NTP "Kernel Application Program Interface"
352http://www.slac.stanford.edu/comp/unix/package/rtems/src/ssrlApps/
353       ntpNanoclock/api.htm⟩
354

COLOPHON

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/.
360
361
362
363Linux                             2021-03-22                       ADJTIMEX(2)
Impressum