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

NAME

6       adjtimex, ntp_adjtime - tune kernel clock
7

SYNOPSIS

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

DESCRIPTION

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
23           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
66       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
71       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
77       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
83       ADJ_MAXERROR
84              Set maximum time error from buf.maxerror.
85
86       ADJ_ESTERROR
87              Set estimated time error from buf.esterror.
88
89       ADJ_STATUS
90              Set  clock  status bits from buf.status.  A description of these
91              bits is provided below.
92
93       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
97       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
102       ADJ_MICRO (since Linux 2.6.26)
103              Select microsecond resolution.
104
105       ADJ_NANO (since Linux 2.6.26)
106              Select   nanosecond  resolution.   Only  one  of  ADJ_MICRO  and
107              ADJ_NANO should be specified.
108
109       ADJ_TAI (since Linux 2.6.26)
110              Set TAI (Atomic International Time) offset from buf.constant.
111
112              ADJ_TAI should not be used in  conjunction  with  ADJ_TIMECONST,
113              since the latter mode also employs the buf.constant field.
114
115              For a complete explanation of TAI and the difference between TAI
116              and UTC, see BIPMhttp://www.bipm.org/en/bipm/tai/tai.html
117
118       ADJ_TICK
119              Set tick value from buf.tick.
120
121       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
125       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
130       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
136       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
139       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
143       STA_PLL (read-write)
144              Enable phase-locked loop (PLL) updates via ADJ_OFFSET.
145
146       STA_PPSFREQ (read-write)
147              Enable PPS (pulse-per-second) frequency discipline.
148
149       STA_PPSTIME (read-write)
150              Enable PPS time discipline.
151
152       STA_FLL (read-write)
153              Select frequency-locked loop (FLL) mode.
154
155       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
160       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
165       STA_UNSYNC (read-write)
166              Clock unsynchronized.
167
168       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
175              This flag prevents the small  frequency  adjustment  from  being
176              made when correcting for an ADJ_OFFSET value.
177
178       STA_PPSSIGNAL (read-only)
179              A valid PPS (pulse-per-second) signal is present.
180
181       STA_PPSJITTER (read-only)
182              PPS signal jitter exceeded.
183
184       STA_PPSWANDER (read-only)
185              PPS signal wander exceeded.
186
187       STA_PPSERROR (read-only)
188              PPS signal calibration error.
189
190       STA_CLOCKERR (read-only)
191              Clock hardware fault.
192
193       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
197       STA_MODE (since Linux 2.6.26)
198              Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop).
199
200       STA_CLK (read-only; since Linux 2.6.26)
201              Clock source (0 = A, 1 = B); currently unused.
202
203       Attempts to set read-only status bits are silently ignored.
204
205   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
211       *  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
215       *  MOD_CLKA is the synonym for ADJ_OFFSET_SINGLESHOT.
216
217       *  MOD_CLKB is the synonym for ADJ_TICK.
218
219       *  The  is no synonym for ADJ_OFFSET_SS_READ, which is not described in
220          the KAPI.
221

RETURN VALUE

223       On success, adjtimex() and ntp_adjtime() return the clock  state;  that
224       is, one of the following values:
225
226       TIME_OK     Clock synchronized, no leap second adjustment pending.
227
228       TIME_INS    Indicates  that  a  leap second will be added at the end of
229                   the UTC day.
230
231       TIME_DEL    Indicates that a leap second will be deleted at the end  of
232                   the UTC day.
233
234       TIME_OOP    Insertion of a leap second is in progress.
235
236       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
240       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
244                   *  Either STA_UNSYNC or STA_CLOCKERR is set.
245
246                   *  STA_PPSSIGNAL   is   clear  and  either  STA_PPSFREQ  or
247                      STA_PPSTIME is set.
248
249                   *  STA_PPSTIME and STA_PPSJITTER are both set.
250
251                   *  STA_PPSFREQ  is  set   and   either   STA_PPSWANDER   or
252                      STA_PPSJITTER is set.
253
254                   The  symbolic  name  TIME_BAD  is a synonym for TIME_ERROR,
255                   provided for backward compatibility.
256
257       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
261       On failure, these calls return -1 and set errno.
262

ERRORS

264       EFAULT buf does not point to writable memory.
265
266       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
270       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
276       EINVAL An attempt was made to set buf.status  to  a  value  other  than
277              those listed above.
278
279       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
283       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

ATTRIBUTES

288       For   an   explanation   of   the  terms  used  in  this  section,  see
289       attributes(7).
290
291       ┌──────────────┬───────────────┬─────────┐
292Interface     Attribute     Value   
293       ├──────────────┼───────────────┼─────────┤
294ntp_adjtime() │ Thread safety │ MT-Safe │
295       └──────────────┴───────────────┴─────────┘

CONFORMING TO

297       Neither of these interfaces is described in POSIX.1
298
299       adjtimex() is  Linux-specific  and  should  not  be  used  in  programs
300       intended to be portable.
301
302       The preferred API for the NTP daemon is ntp_adjtime().
303

NOTES

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

SEE ALSO

316       settimeofday(2),  adjtime(3), ntp_gettime(3), capabilities(7), time(7),
317       adjtimex(8), hwclock(8)
318
319       NTP "Kernel Application Program Interface"
320http://www.slac.stanford.edu/comp/unix/package/rtems/src/ssrlApps/
321       ntpNanoclock/api.htm⟩
322

COLOPHON

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/.
328
329
330
331Linux                             2019-03-06                       ADJTIMEX(2)
Impressum