]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. |
55b82822 | 2 | .\" and Copyright (C) 2014, 2016 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 3 | .\" |
1dd72f9c | 4 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
fea681da MK |
5 | .\" This is free documentation; you can redistribute it and/or |
6 | .\" modify it under the terms of the GNU General Public License as | |
7 | .\" published by the Free Software Foundation; either version 2 of | |
8 | .\" the License, or (at your option) any later version. | |
9 | .\" | |
10 | .\" The GNU General Public License's references to "object code" | |
11 | .\" and "executables" are to be interpreted as the output of any | |
12 | .\" document formatting or typesetting system, including | |
13 | .\" intermediate and printed output. | |
14 | .\" | |
15 | .\" This manual is distributed in the hope that it will be useful, | |
16 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
17 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
18 | .\" GNU General Public License for more details. | |
19 | .\" | |
20 | .\" You should have received a copy of the GNU General Public | |
c715f741 MK |
21 | .\" License along with this manual; if not, see |
22 | .\" <http://www.gnu.org/licenses/>. | |
6a8d8745 | 23 | .\" %%%LICENSE_END |
fea681da MK |
24 | .\" |
25 | .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> | |
26 | .\" Modified 1997-07-30 by Paul Slootman <paul@wurtel.demon.nl> | |
c11b1abf | 27 | .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 28 | .\" |
9ba01802 | 29 | .TH ADJTIMEX 2 2019-03-06 "Linux" "Linux Programmer's Manual" |
fea681da | 30 | .SH NAME |
74132c77 | 31 | adjtimex, clock_adjtime, ntp_adjtime \- tune kernel clock |
fea681da | 32 | .SH SYNOPSIS |
5918743b | 33 | .nf |
fea681da | 34 | .B #include <sys/timex.h> |
8c1cb77b | 35 | .PP |
fea681da | 36 | .BI "int adjtimex(struct timex *" "buf" ); |
8c1cb77b | 37 | .PP |
1ebc1dba AB |
38 | .BI "int clock_adjtime(clockid_t " clk_id, " struct timex *" "buf" ); |
39 | .PP | |
b346e7a0 | 40 | .BI "int ntp_adjtime(struct timex *" buf ); |
5918743b | 41 | .fi |
fea681da | 42 | .SH DESCRIPTION |
8fb01fde | 43 | Linux uses David L.\& Mills' clock adjustment algorithm (see RFC\ 5905). |
fea681da | 44 | The system call |
e511ffb6 | 45 | .BR adjtimex () |
fea681da MK |
46 | reads and optionally sets adjustment parameters for this algorithm. |
47 | It takes a pointer to a | |
c13182ef | 48 | .I timex |
46c75010 MK |
49 | structure, updates kernel parameters from (selected) field values, |
50 | and returns the same structure updated with the current kernel values. | |
fea681da MK |
51 | This structure is declared as follows: |
52 | .PP | |
bd191423 | 53 | .in +4n |
8c1cb77b | 54 | .EX |
fea681da | 55 | struct timex { |
4dfc98f2 MK |
56 | int modes; /* Mode selector */ |
57 | long offset; /* Time offset; nanoseconds, if STA_NANO | |
4ed5a32d MK |
58 | status flag is set, otherwise |
59 | microseconds */ | |
60 | long freq; /* Frequency offset; see NOTES for units */ | |
4dfc98f2 MK |
61 | long maxerror; /* Maximum error (microseconds) */ |
62 | long esterror; /* Estimated error (microseconds) */ | |
63 | int status; /* Clock command/status */ | |
64 | long constant; /* PLL (phase-locked loop) time constant */ | |
4ed5a32d MK |
65 | long precision; /* Clock precision |
66 | (microseconds, read-only) */ | |
67 | long tolerance; /* Clock frequency tolerance (read-only); | |
68 | see NOTES for units */ | |
95547282 | 69 | struct timeval time; |
4dfc98f2 MK |
70 | /* Current time (read-only, except for |
71 | ADJ_SETOFFSET); upon return, time.tv_usec | |
72 | contains nanoseconds, if STA_NANO status | |
73 | flag is set, otherwise microseconds */ | |
74 | long tick; /* Microseconds between clock ticks */ | |
4ed5a32d MK |
75 | long ppsfreq; /* PPS (pulse per second) frequency |
76 | (read-only); see NOTES for units */ | |
4dfc98f2 MK |
77 | long jitter; /* PPS jitter (read-only); nanoseconds, if |
78 | STA_NANO status flag is set, otherwise | |
79 | microseconds */ | |
4ed5a32d MK |
80 | int shift; /* PPS interval duration |
81 | (seconds, read-only) */ | |
82 | long stabil; /* PPS stability (read-only); | |
83 | see NOTES for units */ | |
e837b41c MK |
84 | long jitcnt; /* PPS count of jitter limit exceeded |
85 | events (read-only) */ | |
86 | long calcnt; /* PPS count of calibration intervals | |
87 | (read-only) */ | |
88 | long errcnt; /* PPS count of calibration errors | |
89 | (read-only) */ | |
90 | long stbcnt; /* PPS count of stability limit exceeded | |
91 | events (read-only) */ | |
4dfc98f2 MK |
92 | int tai; /* TAI offset, as set by previous ADJ_TAI |
93 | operation (seconds, read-only, | |
94 | since Linux 2.6.26) */ | |
7b69c78c | 95 | /* Further padding bytes to allow for future expansion */ |
fea681da | 96 | }; |
8c1cb77b | 97 | .EE |
bd191423 | 98 | .in |
fea681da MK |
99 | .PP |
100 | The | |
101 | .I modes | |
102 | field determines which parameters, if any, to set. | |
b346e7a0 MK |
103 | (As described later in this page, |
104 | the constants used for | |
105 | .BR ntp_adjtime () | |
106 | are equivalent but differently named.) | |
7431d790 | 107 | It is a bit mask containing a |
fea681da MK |
108 | .RI bitwise- or |
109 | combination of zero or more of the following bits: | |
4f773948 | 110 | .TP |
7431d790 | 111 | .BR ADJ_OFFSET |
abe87b0c MK |
112 | Set time offset from |
113 | .IR buf.offset . | |
88ec900f MK |
114 | Since Linux 2.6.26, |
115 | .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23 | |
116 | the supplied value is clamped to the range (\-0.5s, +0.5s). | |
117 | In older kernels, an | |
1a96e4f2 | 118 | .B EINVAL |
88ec900f | 119 | error occurs if the supplied value is out of range. |
7431d790 MK |
120 | .TP |
121 | .BR ADJ_FREQUENCY | |
abe87b0c MK |
122 | Set frequency offset from |
123 | .IR buf.freq . | |
f4d9c97d MK |
124 | Since Linux 2.6.26, |
125 | .\" commit 074b3b87941c99bc0ce35385b5817924b1ed0c23 | |
126 | the supplied value is clamped to the range (\-32768000, +32768000). | |
127 | In older kernels, an | |
1a96e4f2 | 128 | .B EINVAL |
f4d9c97d | 129 | error occurs if the supplied value is out of range. |
7431d790 MK |
130 | .TP |
131 | .BR ADJ_MAXERROR | |
abe87b0c MK |
132 | Set maximum time error from |
133 | .IR buf.maxerror . | |
7431d790 MK |
134 | .TP |
135 | .BR ADJ_ESTERROR | |
abe87b0c MK |
136 | Set estimated time error from |
137 | .IR buf.esterror . | |
7431d790 MK |
138 | .TP |
139 | .BR ADJ_STATUS | |
94148126 | 140 | Set clock status bits from |
abe87b0c | 141 | .IR buf.status . |
94148126 | 142 | A description of these bits is provided below. |
7431d790 MK |
143 | .TP |
144 | .BR ADJ_TIMECONST | |
abe87b0c MK |
145 | Set PLL time constant from |
146 | .IR buf.constant . | |
373bd098 MK |
147 | If the |
148 | .B STA_NANO | |
149 | status flag (see below) is clear, the kernel adds 4 to this value. | |
7431d790 | 150 | .TP |
85976da3 | 151 | .BR ADJ_SETOFFSET " (since Linux 2.6.39)" |
f7a78a2d MK |
152 | .\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762 |
153 | .\" Author: Richard Cochran <richardcochran@gmail.com> | |
154 | Add | |
155 | .I buf.time | |
156 | to the current time. | |
784f5985 MK |
157 | If |
158 | .I buf.status | |
159 | includes the | |
160 | .B ADJ_NANO | |
161 | flag, then | |
162 | .I buf.time.tv_usec | |
3a77fea5 | 163 | is interpreted as a nanosecond value; |
784f5985 | 164 | otherwise it is interpreted as microseconds. |
1ebc1dba AB |
165 | .IP |
166 | The value of | |
167 | .I buf.time | |
168 | is the sum of its two fields, but the | |
169 | field | |
170 | .I buf.time.tv_usec | |
3a77fea5 | 171 | must always be nonnegative. |
4952e654 | 172 | The following example shows how to |
3a77fea5 MK |
173 | normalize a |
174 | .I timeval | |
175 | with nanosecond resolution. | |
1ebc1dba AB |
176 | .PP |
177 | .in +12n | |
178 | .EX | |
179 | while (buf.time.tv_usec < 0) { | |
180 | buf.time.tv_sec -= 1; | |
181 | buf.time.tv_usec += 1000000000; | |
182 | } | |
183 | .EE | |
184 | .in | |
185 | .PP | |
f7a78a2d | 186 | .TP |
85976da3 | 187 | .BR ADJ_MICRO " (since Linux 2.6.26)" |
078f99d7 MK |
188 | .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db |
189 | .\" Author: Roman Zippel <zippel@linux-m68k.org> | |
190 | Select microsecond resolution. | |
191 | .TP | |
85976da3 | 192 | .BR ADJ_NANO " (since Linux 2.6.26)" |
078f99d7 MK |
193 | .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db |
194 | .\" Author: Roman Zippel <zippel@linux-m68k.org> | |
195 | Select nanosecond resolution. | |
196 | Only one of | |
197 | .BR ADJ_MICRO | |
198 | and | |
199 | .BR ADJ_NANO | |
200 | should be specified. | |
201 | .TP | |
7431d790 | 202 | .BR ADJ_TAI " (since Linux 2.6.26)" |
872feab5 MK |
203 | .\" commit 153b5d054ac2d98ea0d86504884326b6777f683d |
204 | Set TAI (Atomic International Time) offset from | |
2f016202 | 205 | .IR buf.constant . |
8c1cb77b | 206 | .IP |
872feab5 MK |
207 | .BR ADJ_TAI |
208 | should not be used in conjunction with | |
209 | .BR ADJ_TIMECONST , | |
210 | since the latter mode also employs the | |
2f016202 | 211 | .IR buf.constant |
872feab5 | 212 | field. |
8c1cb77b | 213 | .IP |
872feab5 MK |
214 | For a complete explanation of TAI |
215 | and the difference between TAI and UTC, see | |
216 | .UR http://www.bipm.org/en/bipm/tai/tai.html | |
217 | .I BIPM | |
86e1503e | 218 | .UE |
7431d790 MK |
219 | .TP |
220 | .BR ADJ_TICK | |
abe87b0c MK |
221 | Set tick value from |
222 | .IR buf.tick . | |
31d07b1e MK |
223 | .PP |
224 | Alternatively, | |
225 | .I modes | |
cef8628b MK |
226 | can be specified as either of the following (multibit mask) values, |
227 | in which case other bits should not be specified in | |
228 | .IR modes : | |
229 | .\" In general, the other bits are ignored, but ADJ_OFFSET_SINGLESHOT 0x8001 | |
230 | .\" ORed with ADJ_NANO (0x2000) gives 0xa0001 == ADJ_OFFSET_SS_READ!! | |
7431d790 MK |
231 | .TP |
232 | .BR ADJ_OFFSET_SINGLESHOT | |
002d27fb MK |
233 | .\" In user space, ADJ_OFFSET_SINGLESHOT is 0x8001 |
234 | .\" In kernel space it is 0x0001, and must be ANDed with ADJ_ADJTIME (0x8000) | |
7431d790 | 235 | Old-fashioned |
e3a78ee9 | 236 | .BR adjtime (3): |
002d27fb | 237 | (gradually) adjust time by value specified in |
005239ca MK |
238 | .IR buf.offset , |
239 | which specifies an adjustment in microseconds. | |
6eaec6b1 MK |
240 | .TP |
241 | .BR ADJ_OFFSET_SS_READ " (functional since Linux 2.6.28)" | |
242 | .\" In user space, ADJ_OFFSET_SS_READ is 0xa001 | |
243 | .\" In kernel space there is ADJ_OFFSET_READONLY (0x2000) anded with | |
244 | .\" ADJ_ADJTIME (0x8000) and ADJ_OFFSET_SINGLESHOT (0x0001) to give 0xa001) | |
245 | Return (in | |
69256b80 | 246 | .IR buf.offset ) |
6eaec6b1 MK |
247 | the remaining amount of time to be adjusted after an earlier |
248 | .BR ADJ_OFFSET_SINGLESHOT | |
249 | operation. | |
250 | This feature was added in Linux 2.6.24, | |
251 | .\" commit 52bfb36050c8529d9031d2c2513b281a360922ec | |
252 | but did not work correctly | |
253 | .\" commit 916c7a855174e3b53d182b97a26b2e27a29726a1 | |
254 | until Linux 2.6.28. | |
fea681da | 255 | .PP |
6eaec6b1 MK |
256 | Ordinary users are restricted to a value of either 0 or |
257 | .B ADJ_OFFSET_SS_READ | |
258 | for | |
2b375744 | 259 | .IR modes . |
fea681da | 260 | Only the superuser may set any parameters. |
8c1cb77b | 261 | .PP |
b84ba686 MK |
262 | The |
263 | .I buf.status | |
264 | field is a bit mask that is used to set and/or retrieve status | |
265 | bits associated with the NTP implementation. | |
266 | Some bits in the mask are both readable and settable, | |
267 | while others are read-only. | |
268 | .TP | |
2f016202 MK |
269 | .BR STA_PLL " (read-write)" |
270 | Enable phase-locked loop (PLL) updates via | |
b84ba686 MK |
271 | .BR ADJ_OFFSET . |
272 | .TP | |
2f016202 MK |
273 | .BR STA_PPSFREQ " (read-write)" |
274 | Enable PPS (pulse-per-second) frequency discipline. | |
275 | .TP | |
276 | .BR STA_PPSTIME " (read-write)" | |
277 | Enable PPS time discipline. | |
278 | .TP | |
279 | .BR STA_FLL " (read-write)" | |
280 | Select frequency-locked loop (FLL) mode. | |
281 | .TP | |
282 | .BR STA_INS " (read-write)" | |
283 | Insert a leap second after the last second of the UTC day, | |
284 | thus extending the last minute of the day by one second. | |
285 | Leap-second insertion will occur each day, so long as this flag remains set. | |
286 | .\" John Stultz; | |
287 | .\" Usually this is written as extending the day by one second, | |
288 | .\" which is represented as: | |
289 | .\" 23:59:59 | |
290 | .\" 23:59:60 | |
291 | .\" 00:00:00 | |
2c767761 | 292 | .\" |
2f016202 MK |
293 | .\" But since posix cannot represent 23:59:60, we repeat the last second: |
294 | .\" 23:59:59 + TIME_INS | |
295 | .\" 23:59:59 + TIME_OOP | |
296 | .\" 00:00:00 + TIME_WAIT | |
297 | .\" | |
298 | .TP | |
299 | .BR STA_DEL " (read-write)" | |
de69c712 | 300 | Delete a leap second at the last second of the UTC day. |
2f016202 MK |
301 | .\" John Stultz: |
302 | .\" Similarly the progression here is: | |
303 | .\" 23:59:57 + TIME_DEL | |
304 | .\" 23:59:58 + TIME_DEL | |
305 | .\" 00:00:00 + TIME_WAIT | |
306 | Leap second deletion will occur each day, so long as this flag | |
307 | remains set. | |
e3548e1d | 308 | .\" FIXME Does there need to be a statement that it is nonsensical to set |
badba3f6 | 309 | .\" to set both STA_INS and STA_DEL? |
b84ba686 | 310 | .TP |
2f016202 MK |
311 | .BR STA_UNSYNC " (read-write)" |
312 | Clock unsynchronized. | |
313 | .TP | |
314 | .BR STA_FREQHOLD " (read-write)" | |
315 | Hold frequency. | |
316 | .\" Following text from John Stultz: | |
317 | Normally adjustments made via | |
318 | .B ADJ_OFFSET | |
319 | result in dampened frequency adjustments also being made. | |
320 | So a single call corrects the current offset, | |
321 | but as offsets in the same direction are made repeatedly, | |
322 | the small frequency adjustments will accumulate to fix the long-term skew. | |
8c1cb77b | 323 | .IP |
2f016202 MK |
324 | This flag prevents the small frequency adjustment from being made |
325 | when correcting for an | |
326 | .B ADJ_OFFSET | |
327 | value. | |
328 | .\" According to the Kernel Application Program Interface document, | |
329 | .\" STA_FREQHOLD is not used by the NTP version 4 daemon | |
330 | .TP | |
331 | .BR STA_PPSSIGNAL " (read-only)" | |
332 | A valid PPS (pulse-per-second) signal is present. | |
333 | .TP | |
334 | .BR STA_PPSJITTER " (read-only)" | |
335 | PPS signal jitter exceeded. | |
336 | .TP | |
337 | .BR STA_PPSWANDER " (read-only)" | |
338 | PPS signal wander exceeded. | |
339 | .TP | |
340 | .BR STA_PPSERROR " (read-only)" | |
341 | PPS signal calibration error. | |
342 | .TP | |
343 | .BR STA_CLOCKERR " (read-only)" | |
344 | Clock hardware fault. | |
345 | .\" Not set in current kernel (4.5), but checked in a few places | |
346 | .TP | |
347 | .BR STA_NANO " (read-only; since Linux 2.6.26)" | |
b84ba686 MK |
348 | .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db |
349 | .\" Author: Roman Zippel <zippel@linux-m68k.org> | |
2f016202 | 350 | Resolution (0 = microsecond, 1 = nanoseconds). |
6848ba03 | 351 | Set via |
373bd098 MK |
352 | .BR ADJ_NANO , |
353 | cleared via | |
354 | .BR ADJ_MICRO . | |
b84ba686 MK |
355 | .TP |
356 | .BR STA_MODE " (since Linux 2.6.26)" | |
357 | .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db | |
358 | .\" Author: Roman Zippel <zippel@linux-m68k.org> | |
2f016202 | 359 | Mode (0 = Phase Locked Loop, 1 = Frequency Locked Loop). |
b84ba686 | 360 | .TP |
2f016202 | 361 | .BR STA_CLK " (read-only; since Linux 2.6.26)" |
b84ba686 MK |
362 | .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db |
363 | .\" Author: Roman Zippel <zippel@linux-m68k.org> | |
2f016202 | 364 | Clock source (0 = A, 1 = B); currently unused. |
b84ba686 MK |
365 | .PP |
366 | Attempts to set read-only | |
367 | .I status | |
368 | bits are silently ignored. | |
b346e7a0 | 369 | .\" |
1ebc1dba AB |
370 | .SS clock_adjtime () |
371 | The | |
372 | .BR clock_adjtime () | |
3a77fea5 MK |
373 | system call (added in Linux 2.6.39) behaves like |
374 | .BR adjtimex () | |
375 | but takes an additional | |
1ebc1dba AB |
376 | .IR clk_id |
377 | argument to specify the particular clock on which to act. | |
b346e7a0 MK |
378 | .SS ntp_adjtime () |
379 | The | |
380 | .BR ntp_adjtime () | |
381 | library function | |
382 | (described in the NTP "Kernel Application Program API", KAPI) | |
383 | is a more portable interface for performing the same task as | |
384 | .BR adjtimex (). | |
385 | Other than the following points, it is identical to | |
3bf4529e | 386 | .BR adjtimex (): |
b346e7a0 MK |
387 | .IP * 3 |
388 | The constants used in | |
389 | .I modes | |
390 | are prefixed with "MOD_" rather than "ADJ_", and have the same suffixes (thus, | |
391 | .BR MOD_OFFSET , | |
392 | .BR MOD_FREQUENCY , | |
393 | and so on), other than the exceptions noted in the following points. | |
394 | .IP * | |
395 | .BR MOD_CLKA | |
396 | is the synonym for | |
397 | .BR ADJ_OFFSET_SINGLESHOT . | |
398 | .IP * | |
399 | .BR MOD_CLKB | |
400 | is the synonym for | |
401 | .BR ADJ_TICK . | |
402 | .IP * | |
403 | The is no synonym for | |
404 | .BR ADJ_OFFSET_SS_READ , | |
405 | which is not described in the KAPI. | |
47297adb | 406 | .SH RETURN VALUE |
fea681da | 407 | On success, |
e511ffb6 | 408 | .BR adjtimex () |
b346e7a0 MK |
409 | and |
410 | .BR ntp_adjtime () | |
411 | return the clock state; that is, one of the following values: | |
0a8916e6 MK |
412 | .TP 12 |
413 | .BR TIME_OK | |
de69c712 | 414 | Clock synchronized, no leap second adjustment pending. |
0a8916e6 MK |
415 | .TP |
416 | .BR TIME_INS | |
2f016202 | 417 | Indicates that a leap second will be added at the end of the UTC day. |
0a8916e6 MK |
418 | .TP |
419 | .BR TIME_DEL | |
de69c712 | 420 | Indicates that a leap second will be deleted at the end of the UTC day. |
0a8916e6 MK |
421 | .TP |
422 | .BR TIME_OOP | |
2f016202 | 423 | Insertion of a leap second is in progress. |
0a8916e6 MK |
424 | .TP |
425 | .BR TIME_WAIT | |
2f016202 MK |
426 | A leap-second insertion or deletion has been completed. |
427 | This value will be returned until the next | |
428 | .BR ADJ_STATUS | |
429 | operation clears the | |
430 | .B STA_INS | |
431 | and | |
432 | .B STA_DEL | |
433 | flags. | |
0a8916e6 | 434 | .TP |
4ce77a32 | 435 | .BR TIME_ERROR |
2f016202 MK |
436 | The system clock is not synchronized to a reliable server. |
437 | This value is returned when any of the following holds true: | |
438 | .RS | |
439 | .IP * 3 | |
440 | Either | |
441 | .B STA_UNSYNC | |
442 | or | |
443 | .B STA_CLOCKERR | |
444 | is set. | |
445 | .IP * | |
446 | .B STA_PPSSIGNAL | |
447 | is clear and either | |
448 | .B STA_PPSFREQ | |
449 | or | |
450 | .B STA_PPSTIME | |
451 | is set. | |
452 | .IP * | |
453 | .B STA_PPSTIME | |
454 | and | |
455 | .B STA_PPSJITTER | |
456 | are both set. | |
457 | .IP * | |
458 | .B STA_PPSFREQ | |
459 | is set and either | |
460 | .B STA_PPSWANDER | |
461 | or | |
462 | .B STA_PPSJITTER | |
463 | is set. | |
464 | .RE | |
465 | .IP | |
4ce77a32 MK |
466 | The symbolic name |
467 | .B TIME_BAD | |
468 | is a synonym for | |
469 | .BR TIME_ERROR , | |
d58d906e | 470 | provided for backward compatibility. |
2f016202 | 471 | .PP |
f3910b47 WP |
472 | Note that starting with Linux 3.4, |
473 | .\" commit 6b43ae8a619d17c4935c3320d2ef9e92bdeed05d changed to asynchronous | |
474 | .\" operation, so we can no longer rely on the return code. | |
475 | the call operates asynchronously and the return value usually will | |
476 | not reflect a state change caused by the call itself. | |
fea681da | 477 | .PP |
b346e7a0 | 478 | On failure, these calls return \-1 and set |
fea681da MK |
479 | .IR errno . |
480 | .SH ERRORS | |
481 | .TP | |
482 | .B EFAULT | |
483 | .I buf | |
484 | does not point to writable memory. | |
485 | .TP | |
a2300b58 | 486 | .BR EINVAL " (kernels before Linux 2.6.26)" |
b2eeb390 | 487 | An attempt was made to set |
f4d9c97d MK |
488 | .I buf.freq |
489 | to a value outside the range (\-33554432, +33554432). | |
5fec8763 | 490 | .\" From a quick glance, it appears there was no clamping or range check |
f4d9c97d MK |
491 | .\" for buf.freq in kernels before 2.0 |
492 | .TP | |
493 | .BR EINVAL " (kernels before Linux 2.6.26)" | |
494 | An attempt was made to set | |
fea681da | 495 | .I buf.offset |
a2300b58 MK |
496 | to a value outside the permitted range. |
497 | In kernels before Linux 2.0, the permitted range was (\-131072, +131072). | |
498 | From Linux 2.0 onwards, the permitted range was (\-512000, +512000). | |
77a47e47 MK |
499 | .TP |
500 | .B EINVAL | |
501 | An attempt was made to set | |
fea681da | 502 | .I buf.status |
77a47e47 MK |
503 | to a value other than those listed above. |
504 | .TP | |
505 | .B EINVAL | |
1ebc1dba AB |
506 | The |
507 | .I clk_id | |
508 | given to | |
509 | .BR clock_adjtime () | |
4952e654 | 510 | is invalid for one of two reasons. |
3a77fea5 MK |
511 | Either the System-V style hard-coded |
512 | positive clock ID value is out of range, or the dynamic | |
1ebc1dba AB |
513 | .I clk_id |
514 | does not refer to a valid instance of a clock object. | |
515 | See | |
516 | .BR clock_gettime (2) | |
517 | for a discussion of dynamic clocks. | |
518 | .TP | |
519 | .B EINVAL | |
77a47e47 | 520 | An attempt was made to set |
fea681da | 521 | .I buf.tick |
c13182ef | 522 | to a value outside the range |
fea681da | 523 | .RB 900000/ HZ |
c13182ef | 524 | to |
fea681da MK |
525 | .RB 1100000/ HZ , |
526 | where | |
527 | .B HZ | |
528 | is the system timer interrupt frequency. | |
529 | .TP | |
1ebc1dba | 530 | .B ENODEV |
488d9e31 | 531 | The hot-pluggable device (like USB for example) represented by a |
1ebc1dba AB |
532 | dynamic |
533 | .I clk_id | |
534 | has disappeared after its character device was opened. | |
535 | See | |
536 | .BR clock_gettime (2) | |
537 | for a discussion of dynamic clocks. | |
538 | .TP | |
539 | .B EOPNOTSUPP | |
540 | The given | |
541 | .I clk_id | |
542 | does not support adjustment. | |
543 | .TP | |
fea681da | 544 | .B EPERM |
432c7b6a | 545 | .I buf.modes |
6eaec6b1 MK |
546 | is neither 0 nor |
547 | .BR ADJ_OFFSET_SS_READ , | |
548 | and the caller does not have sufficient privilege. | |
5de5062a | 549 | Under Linux, the |
fea681da MK |
550 | .B CAP_SYS_TIME |
551 | capability is required. | |
ebfc893e MK |
552 | .SH ATTRIBUTES |
553 | For an explanation of the terms used in this section, see | |
554 | .BR attributes (7). | |
555 | .TS | |
556 | allbox; | |
557 | lb lb lb | |
558 | l l l. | |
559 | Interface Attribute Value | |
560 | T{ | |
561 | .BR ntp_adjtime () | |
562 | T} Thread safety MT-Safe | |
563 | .TE | |
47297adb | 564 | .SH CONFORMING TO |
1ebc1dba | 565 | None of these interfaces is described in POSIX.1 |
8c1cb77b | 566 | .PP |
60a90ecd | 567 | .BR adjtimex () |
1ebc1dba AB |
568 | and |
569 | .BR clock_adjtime () | |
570 | are Linux-specific and should not be used in programs | |
dffb0109 | 571 | intended to be portable. |
8c1cb77b | 572 | .PP |
c40843ae | 573 | The preferred API for the NTP daemon is |
15431917 | 574 | .BR ntp_adjtime (). |
81036dab MK |
575 | .SH NOTES |
576 | In struct | |
577 | .IR timex , | |
578 | .IR freq , | |
579 | .IR ppsfreq , | |
580 | and | |
581 | .I stabil | |
582 | are ppm (parts per million) with a 16-bit fractional part, | |
583 | which means that a value of 1 in one of those fields | |
584 | actually means 2^-16 ppm, and 2^16=65536 is 1 ppm. | |
585 | This is the case for both input values (in the case of | |
586 | .IR freq ) | |
587 | and output values. | |
8c1cb77b | 588 | .PP |
81036dab MK |
589 | The leap-second processing triggered by |
590 | .B STA_INS | |
591 | and | |
592 | .B STA_DEL | |
f5e98114 | 593 | is done by the kernel in timer context. |
81036dab MK |
594 | Thus, it will take one tick into the second |
595 | for the leap second to be inserted or deleted. | |
47297adb | 596 | .SH SEE ALSO |
bba4bbbd KK |
597 | .BR clock_gettime (2), |
598 | .BR clock_settime (2), | |
fea681da | 599 | .BR settimeofday (2), |
dffb0109 | 600 | .BR adjtime (3), |
cf19a3b9 | 601 | .BR ntp_gettime (3), |
1d7c4d16 | 602 | .BR capabilities (7), |
bd641654 | 603 | .BR time (7), |
1ce611a3 MK |
604 | .BR adjtimex (8), |
605 | .BR hwclock (8) | |
8c1cb77b | 606 | .PP |
2f016202 | 607 | .ad l |
178635c4 | 608 | .UR http://www.slac.stanford.edu/comp/unix/\:package/\:rtems/\:src/\:ssrlApps/\:ntpNanoclock/\:api.htm |
2f016202 MK |
609 | NTP "Kernel Application Program Interface" |
610 | .UE |