]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (c) 1995 Michael Chastain (mec@shell.portal.com), 15 April 1995. |
2 | .\" | |
1dd72f9c | 3 | .\" %%%LICENSE_START(GPLv2+_DOC_FULL) |
fea681da MK |
4 | .\" This is free documentation; you can redistribute it and/or |
5 | .\" modify it under the terms of the GNU General Public License as | |
6 | .\" published by the Free Software Foundation; either version 2 of | |
7 | .\" the License, or (at your option) any later version. | |
8 | .\" | |
9 | .\" The GNU General Public License's references to "object code" | |
10 | .\" and "executables" are to be interpreted as the output of any | |
11 | .\" document formatting or typesetting system, including | |
12 | .\" intermediate and printed output. | |
13 | .\" | |
14 | .\" This manual is distributed in the hope that it will be useful, | |
15 | .\" but WITHOUT ANY WARRANTY; without even the implied warranty of | |
16 | .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the | |
17 | .\" GNU General Public License for more details. | |
18 | .\" | |
19 | .\" You should have received a copy of the GNU General Public | |
c715f741 MK |
20 | .\" License along with this manual; if not, see |
21 | .\" <http://www.gnu.org/licenses/>. | |
6a8d8745 | 22 | .\" %%%LICENSE_END |
fea681da MK |
23 | .\" |
24 | .\" Modified 1997-01-31 by Eric S. Raymond <esr@thyrsus.com> | |
25 | .\" Modified 1997-07-30 by Paul Slootman <paul@wurtel.demon.nl> | |
c11b1abf | 26 | .\" Modified 2004-05-27 by Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 27 | .\" |
8660ef9f | 28 | .TH ADJTIMEX 2 2014-05-28 "Linux" "Linux Programmer's Manual" |
fea681da MK |
29 | .SH NAME |
30 | adjtimex \- tune kernel clock | |
31 | .SH SYNOPSIS | |
5918743b MK |
32 | .nf |
33 | .BR "#define _BSD_SOURCE" " /* See feature_test_macros(7) */" | |
fea681da | 34 | .B #include <sys/timex.h> |
5918743b | 35 | |
fea681da | 36 | .BI "int adjtimex(struct timex *" "buf" ); |
5918743b | 37 | .fi |
fea681da | 38 | .SH DESCRIPTION |
331da7c3 | 39 | Linux uses David L. Mills' clock adjustment algorithm (see RFC\ 1305). |
fea681da | 40 | The system call |
e511ffb6 | 41 | .BR adjtimex () |
fea681da MK |
42 | reads and optionally sets adjustment parameters for this algorithm. |
43 | It takes a pointer to a | |
c13182ef | 44 | .I timex |
fea681da MK |
45 | structure, updates kernel parameters from field values, |
46 | and returns the same structure with current kernel values. | |
47 | This structure is declared as follows: | |
48 | .PP | |
bd191423 | 49 | .in +4n |
fea681da MK |
50 | .nf |
51 | struct timex { | |
d5f787f1 MK |
52 | int modes; /* Mode selector */ |
53 | long offset; /* Time offset (microseconds) */ | |
54 | long freq; /* Frequency offset, as scaled PPM | |
55 | (parts per million) */ | |
bea08fec | 56 | .\" FIXME What is the scaling unit of timex.freq? 2^16 ? |
d5f787f1 MK |
57 | long maxerror; /* Maximum error (microseconds) */ |
58 | long esterror; /* Estimated error (microseconds) */ | |
59 | int status; /* Clock command/status */ | |
a87ba63b | 60 | long constant; /* PLL (phase-lock loop) time constant */ |
d5f787f1 | 61 | long precision; /* Clock precision (microseconds) |
972a8ec7 | 62 | (read-only) */ |
d5f787f1 MK |
63 | long tolerance; /* Clock frequency tolerance (PPM) |
64 | (read-only) */ | |
f7a78a2d MK |
65 | struct timeval time; /* Current time (read-only, except |
66 | for ADJ_SETOFFSET) */ | |
d5f787f1 MK |
67 | long tick; /* Usecs between clock ticks */ |
68 | long ppsfreq; /* PPS frequency (scaled PPM) (read-only) */ | |
69 | long jitter; /* PPS jitter (microseconds) | |
70 | (read-only) */ | |
71 | int shift; /* Interval duration (sec) (read-only) */ | |
72 | long stabil; /* PPS stability (scaled PPM) (read-only) */ | |
73 | long jitcnt; /* Jitter limit exceeded (read-only) */ | |
74 | long calcnt; /* Calibration intervals (read-only) */ | |
75 | long errcnt; /* Calibration errors (read-only) */ | |
76 | long stbcnt; /* Stability limit exceeded (read-only) */ | |
077a8db3 | 77 | int tai; /* TAI offset (sec) (read-only) */ |
fea681da MK |
78 | }; |
79 | .fi | |
bd191423 | 80 | .in |
fea681da MK |
81 | .PP |
82 | The | |
83 | .I modes | |
84 | field determines which parameters, if any, to set. | |
7431d790 | 85 | It is a bit mask containing a |
fea681da MK |
86 | .RI bitwise- or |
87 | combination of zero or more of the following bits: | |
4f773948 | 88 | .TP |
7431d790 MK |
89 | .BR ADJ_OFFSET |
90 | Time offset. | |
91 | .TP | |
92 | .BR ADJ_FREQUENCY | |
93 | Frequency offset. | |
94 | .TP | |
95 | .BR ADJ_MAXERROR | |
96 | Maximum time error. | |
97 | .TP | |
98 | .BR ADJ_ESTERROR | |
99 | Estimated time error. | |
100 | .TP | |
101 | .BR ADJ_STATUS | |
102 | Clock status. | |
103 | .TP | |
104 | .BR ADJ_TIMECONST | |
105 | PLL time constant. | |
106 | .TP | |
f7a78a2d MK |
107 | .BR ADJ_SETOFFSET " (since Linux 2.6.29)" |
108 | .\" commit 094aa1881fdc1b8889b442eb3511b31f3ec2b762 | |
109 | .\" Author: Richard Cochran <richardcochran@gmail.com> | |
110 | Add | |
111 | .I buf.time | |
112 | to the current time. | |
113 | .TP | |
114 | .TP | |
078f99d7 MK |
115 | .BR ADJ_MICRO " (since Linux 2.6.36)" |
116 | .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db | |
117 | .\" Author: Roman Zippel <zippel@linux-m68k.org> | |
118 | Select microsecond resolution. | |
119 | .TP | |
120 | .BR ADJ_NANO " (since Linux 2.6.36)" | |
121 | .\" commit eea83d896e318bda54be2d2770d2c5d6668d11db | |
122 | .\" Author: Roman Zippel <zippel@linux-m68k.org> | |
123 | Select nanosecond resolution. | |
124 | Only one of | |
125 | .BR ADJ_MICRO | |
126 | and | |
127 | .BR ADJ_NANO | |
128 | should be specified. | |
129 | .TP | |
7431d790 MK |
130 | .BR ADJ_TAI " (since Linux 2.6.26)" |
131 | TAI offset. | |
132 | .TP | |
133 | .BR ADJ_TICK | |
134 | Tick value. | |
135 | .TP | |
136 | .BR ADJ_OFFSET_SINGLESHOT | |
137 | Old-fashioned | |
138 | .BR adjtime (). | |
fea681da MK |
139 | .PP |
140 | Ordinary users are restricted to a zero value for | |
2b375744 | 141 | .IR modes . |
fea681da | 142 | Only the superuser may set any parameters. |
6c9b2fe0 MK |
143 | |
144 | In the case of | |
145 | .BR ADJ_TAI , | |
146 | as | |
147 | .I buf->tai | |
148 | is read-only, the new value is passed through | |
149 | .IR buf->constant . | |
150 | Therefore | |
151 | .BR ADJ_TAI | |
152 | should not be used in conjunction with | |
153 | .BR ADJ_TIMECONST , | |
154 | since the latter mode also employs the | |
155 | .IR buf->constant | |
156 | field. | |
157 | .PP | |
158 | Support for TAI (Atomic International Time) | |
159 | was added | |
160 | .\" commit 153b5d054ac2d98ea0d86504884326b6777f683d | |
161 | in Linux 2.6.26. | |
162 | For a complete explanation of TAI | |
163 | and the difference between TAI and UTC, see | |
164 | .UR http://www.bipm.org/en/bipm/tai/tai.html | |
165 | .I BIPM | |
166 | .UE ) | |
47297adb | 167 | .SH RETURN VALUE |
fea681da | 168 | On success, |
e511ffb6 | 169 | .BR adjtimex () |
0a8916e6 MK |
170 | returns the clock state; that is, one of the following values: |
171 | .TP 12 | |
172 | .BR TIME_OK | |
173 | Clock synchronized. | |
174 | .TP | |
175 | .BR TIME_INS | |
176 | Insert leap second. | |
177 | .TP | |
178 | .BR TIME_DEL | |
179 | Delete leap second. | |
180 | .TP | |
181 | .BR TIME_OOP | |
182 | Leap second in progress. | |
183 | .TP | |
184 | .BR TIME_WAIT | |
185 | Leap second has occurred. | |
186 | .TP | |
187 | .BR TIME_BAD | |
188 | Clock not synchronized. | |
fea681da MK |
189 | .PP |
190 | On failure, | |
e511ffb6 | 191 | .BR adjtimex () |
fea681da MK |
192 | returns \-1 and sets |
193 | .IR errno . | |
194 | .SH ERRORS | |
195 | .TP | |
196 | .B EFAULT | |
197 | .I buf | |
198 | does not point to writable memory. | |
199 | .TP | |
200 | .B EINVAL | |
b2eeb390 | 201 | An attempt was made to set |
fea681da MK |
202 | .I buf.offset |
203 | to a value outside the range \-131071 to +131071, | |
204 | or to set | |
205 | .I buf.status | |
206 | to a value other than those listed above, | |
207 | or to set | |
208 | .I buf.tick | |
c13182ef | 209 | to a value outside the range |
fea681da | 210 | .RB 900000/ HZ |
c13182ef | 211 | to |
fea681da MK |
212 | .RB 1100000/ HZ , |
213 | where | |
214 | .B HZ | |
215 | is the system timer interrupt frequency. | |
216 | .TP | |
217 | .B EPERM | |
432c7b6a | 218 | .I buf.modes |
c7094399 | 219 | is nonzero and the caller does not have sufficient privilege. |
fea681da MK |
220 | Under Linux the |
221 | .B CAP_SYS_TIME | |
222 | capability is required. | |
47297adb | 223 | .SH CONFORMING TO |
60a90ecd | 224 | .BR adjtimex () |
8382f16d | 225 | is Linux-specific and should not be used in programs |
dffb0109 MK |
226 | intended to be portable. |
227 | See | |
228 | .BR adjtime (3) | |
c13182ef | 229 | for a more portable, but less flexible, |
dffb0109 | 230 | method of adjusting the system clock. |
47297adb | 231 | .SH SEE ALSO |
fea681da | 232 | .BR settimeofday (2), |
dffb0109 | 233 | .BR adjtime (3), |
1d7c4d16 | 234 | .BR capabilities (7), |
bd641654 MK |
235 | .BR time (7), |
236 | .BR adjtimex (8) |