1ADJTIMEX(8) System Manager's Manual ADJTIMEX(8)
2
6 adjtimex - display or set the kernel time variables
7
9 adjtimex [option]...
10
12 This program gives you raw access to the kernel time variables. Anyone
13 may print out the time variables, but only the superuser may change
14 them.
15 Your computer has two clocks - the "hardware clock" that runs all the
17 time, and the system clock that runs only while the computer is on.
18 Normally, "hwclock --hctosys" should be run at startup to initialize
19 the system clock. The system clock has much better precision (approxi‐
20 mately 1 usec), but the hardware clock probably has better long-term
21 stability. There are three basic strategies for managing these clocks.
22 For a machine connected to the Internet, or equipped with a precision
24 oscillator or radio clock, the best way is to regulate the system clock
25 with ntpd(8). The kernel will automatically update the hardware clock
26 every eleven minutes.
27 In addition, hwclock(8) can be used to approximately correct for a con‐
29 stant drift in the hardware clock. In this case, "hwclock --adjust" is
30 run occasionally. hwclock notes how long it has been since the last
31 adjustment, and nudges the hardware clock forward or back by the appro‐
32 priate amount. The user needs to set the time with "hwclock --set"
33 several times over the course of a few days so hwclock can estimate the
34 drift rate. During that time, ntpd should not be running, or else
35 hwclock will conclude the hardware clock does not drift at all. After
36 you have run "hwclock --set" for the last time, it's okay to start
37 ntpd. Then, "hwclock --systohc" should be run when the machine is shut
38 down. (To see why, suppose the machine runs for a week with ntpd, is
39 shut down for a day, is restarted, and "hwclock --adjust" is run by a
40 startup script. It should only correct for one day's worth of drift.
41 However, it has no way of knowing that ntpd has been adjusting the
42 hardware clock, so it bases its adjustment on the last time hwclock was
43 run.)
44 For a standalone or intermittently connected machine, where it's not
46 possible to run ntpd, you may use adjtimex instead to correct the sys‐
47 tem clock for systematic drift.
48 There are several ways to estimate the drift rate. If your computer
50 can be connected to the net, you might run ntpd for at least several
51 hours and run "adjtimex --print" to learn what values of tick and freq
52 it settled on. Alternately, you could estimate values using as a ref‐
53 erence the CMOS clock (see the --compare and --adjust switches),
54 another host (see --host and --review), or some other source of time
55 (see --watch and --review). You could then add a line to rc.local
56 invoking adjtimex, or configure /etc/init.d/adjtimex or
57 /etc/default/adjtimex, to set those parameters each time you reboot.
58
60 Options may be introduced by either - or --, and unique abbreviations
61 may be used.
62 Here is a summary of the options, grouped by type. Explanations fol‐
64 low.
65 Get/Set Kernel Time Parameters
67 -p --print -t --tick val -f newfreq --frequency newfreq -o val
68 --offset val -s adjustment --singleshot adjustment -S status
69 --status status -m val -R --reset --maxerror val -e val
70 --esterror val -T val --timeconstant val -a[count]
71 --adjust[=count]
72 Estimate Systematic Drifts
74 -c[count] --compare[=count] -i tim --interval tim -l file
75 --logfile file -h timeserver --host timeserver -w --watch
76 -r[file] --review[=file] -u --utc -d --directisa -n
77 --nointerrupt
78 Informative Output
80 --help -v --version -V --verbose
81 -p, --print
83 Print the current values of the kernel time variables. NOTE:
84 The time is "raw", and may be off by up to one timer tick (10
85 msec). "status" gives the value of the time_status variable in
86 the kernel. For Linux 1.0 and 1.2 kernels, the value is as
87 follows:
88 0 clock is synchronized (so the kernel should
89 periodically set the CMOS clock to match the
90 system clock)
91 1 inserting a leap second at midnight
92 2 deleting a leap second at midnight
93 3 leap second in progress
94 4 leap second has occurred
95 5 clock not externally synchronized (so the
96 kernel should leave the CMOS clock alone)
97 For Linux kernels 2.0 through 2.6, the value is a sum of these:
98 1 PLL updates enabled
99 2 PPS freq discipline enabled
100 4 PPS time discipline enabled
101 8 frequency-lock mode enabled
102 16 inserting leap second
103 32 deleting leap second
104 64 clock unsynchronized
105 128 holding frequency
106 256 PPS signal present
107 512 PPS signal jitter exceeded
108 1024 PPS signal wander exceeded
109 2048 PPS signal calibration error
110 4096 clock hardware fault
111 -t val, --tick val
113 Set the number of microseconds that should be added to the
114 system time for each kernel tick interrupt. For a kernel with
115 USER_HZ=100, there are supposed to be 100 ticks per second, so
116 val should be close to 10000. Increasing val by 1 speeds up the
117 system clock by about 100 ppm, or 8.64 sec/day. tick must be in
118 the range 900000/USER_HZ...1100000/USER_HZ. If val is rejected
119 by the kernel, adjtimex will determine the acceptable range
120 through trial and error and print it. (After completing the
121 search, it will restore the original value.)
122 -f newfreq, --frequency newfreq
124 Set the system clock frequency offset to newfreq. newfreq can
125 be negative or positive, and gives a much finer adjustment than
126 the --tick switch. When USER_HZ=100, the value is scaled such
127 that newfreq = 65536 speeds up the system clock by about 1 ppm,
128 or .0864 sec/day. Thus, all of these are about the same:
129 --tick 9995 --frequency 32768000
130 --tick 10000 --frequency 6553600
131 --tick 10001 --frequency 0
132 --tick 10002 --frequency -6553600
133 --tick 10005 --frequency -32768000
134 To see the acceptable range for newfreq, use --print and look at
135 "tolerance", or try an illegal value (e.g. --tick 0).
136 -s adj, --singleshot adj
138 Slew the system clock by adj usec. (Its rate is changed
139 temporarily by about 1 part in 2000.)
140 -o adj, --offset adj
142 Add a time offset of adj usec. The kernel code adjusts the time
143 gradually by adj, notes how long it has been since the last time
144 offset, and then adjusts the frequency offset to correct for the
145 apparent drift. adj must be in the range -512000...512000.
146 -S status, --status status
148 Set kernel system clock status register to value status. Look
149 here above at the --print switch section for the meaning of
150 status, depending on your kernel.
151 -R, --reset
153 Reset clock status after setting a clock parameter. For early
154 Linux kernels, using the adjtimex(2) system call to set any time
155 parameter the kernel think the clock is synchronized with an
156 external time source, so it sets the kernel variable time_status
157 to TIME_OK. Thereafter, at 11 minute intervals, it will adjust
158 the CMOS clock to match. We prevent this "eleven minute mode"
159 by setting the clock, because that has the side effect of
160 resetting time_status to TIME_BAD. We try not to actually
161 change the clock setting. Kernel versions 2.0.40 and later
162 apparently don't need this. If your kernel does require it, use
163 this option with: -t -T -t -e -m -f -s -o -c -r.
164 -m val, --maxerror val
166 Set maximum error (usec).
167 -e val, --esterror val
169 Set estimated error (usec). The maximum and estimated error are
170 not used by the kernel. They are merely made available to user
171 processes via the adjtimex(2) system call.
172 -T val, --timeconstant val
174 Set phase locked loop (PLL) time constant. val determines the
175 bandwidth or "stiffness" of the PLL. The effective PLL time
176 constant will be a multiple of (2^val). For room-temperature
177 quartz oscillators, David Mills recommends the value 2, which
178 corresponds to a PLL time constant of about 900 sec and a
179 maximum update interval of about 64 sec. The maximum update
180 interval scales directly with the time constant, so that at the
181 maximum time constant of 6, the update interval can be as large
182 as 1024 sec.
183 Values of val between zero and 2 give quick convergence; values
185 between 2 and 6 can be used to reduce network load, but at a
186 modest cost in accuracy.
187 -c[count], --compare[=count]
189 Periodically compare the system clock with the CMOS clock.
190 After the first two calls, print values for tick and frequency
191 offset that would bring the system clock into approximate
192 agreement with the CMOS clock. CMOS clock readings are adjusted
193 for systematic drift using using the correction in /etc/adjtime
194 — see hwclock(8). The interval between comparisons is 10
195 seconds, unless changed by the --interval switch. The optional
196 argument is the number of comparisons. (If the argument is
197 supplied, the "=" is required.) If the CMOS clock and the
198 system clock differ by more than six minutes, adjtimex will try
199 shifting the time from the CMOS clock by some multiple of one
200 hour, up to plus or minus 13 hours in all. This should allow
201 correct operation, including logging, if the --utc switch was
202 used when the CMOS clock is set to local time (or vice-versa),
203 or if summer time has started or stopped since the CMOS clock
204 was last set.
205 -a[count], --adjust[=count]
207 By itself, same as --compare, except the recommended values are
208 actually installed after every third comparison. With --review,
209 the tick and frequency are set to the least-squares estimates.
210 (In the latter case, any count value is ignored.)
211 --force-adjust
213 Override the sanity check that prevents changing the clock rate
214 by more than 500 ppm.
215 -i tim, --interval tim
217 Set the interval in seconds between clock comparisons for the
218 --compare and --adjust options.
219 -u, --utc
221 The CMOS clock is set to UTC (universal time) rather than local
222 time.
223 -d, --directisa
225 To read the CMOS clock accurately, adjtimex usually accesses the
226 clock via the /dev/rtc device driver of the kernel, and makes
227 use of its CMOS update-ended interrupt to detect the beginning
228 of seconds. It will also try /dev/rtc0 (for udev), /dev/misc/rtc
229 (for the obsolete devfs) and possibly others. When the /dev/rtc
230 driver is absent, or when the interrupt is not available,
231 adjtimex can sometimes automatically fallback to a direct access
232 method. This method detects the start of seconds by polling the
233 update-in-progress (UIP) flag of the CMOS clock. You can force
234 this direct access to the CMOS chip with the --directisa switch.
235 Note that the /dev/rtc interrupt method is more accurate, less
237 sensible to perturbations due to system load, cleaner, cheaper,
238 and is generally better than the direct access method. It is
239 advisable to not use the --directisa switch, unless the CMOS
240 chip or the motherboard don't properly provide the necessary
241 interrupt.
242 -n, --nointerrupt
244 Force immediate use of busywait access method, without first
245 waiting for the interrupt timeout.
246 -l[file], --log[=file]
248 Save the current values of the system and CMOS clocks, and
249 optionally a reference time, to file (default
250 /var/log/clocks.log). The reference time is taken from a
251 network timeserver (see the --host switch) or supplied by the
252 user (see the --watch switch).
253 -h timeserver, --host timeserver
255 Use ntpdate to query the given timeserver for the current time.
256 This will fail if timeserver is not running a Network Time
257 Protocol (NTP) server, or if that server is not synchronized.
258 Implies --log.
259 -w, --watch
261 Ask for a keypress when the user knows the time, then ask what
262 that time was, and its approximate accuracy. Implies --log.
263 -r[file], --review[=file]
265 Review the clock log file (default /var/log/clocks.log) and
266 estimate, if possible, the rates of the CMOS and system clocks.
267 Calculate least-squares rates using all suitable log entries.
268 Suggest corrections to adjust for systematic drift. With
269 --adjust, the frequency and tick are set to the suggested
270 values. (The CMOS clock correction is not changed.)
271 -V, --verbose
273 Increase verbosity.
274 --help Print the program options.
276 -v, --version
278 Print the program version.
279
281 If your system clock gained 8 seconds in 24 hours, you could set the
282 tick to 9999, and then it would lose 0.64 seconds a day (that is, 1
283 tick unit = 8.64 seconds per day). To correct the rest of the error,
284 you could set the frequency offset to (2^16)*0.64/.0864 = 485452.
285 Thus, putting the following in rc.local would approximately correct the
286 system clock:
287 adjtimex --tick 9999 --freq 485452
289
291 adjtimex adjusts only the system clock — the one that runs while the
292 computer is powered up. To set or regulate the CMOS clock, see
293 hwclock(8).
294
296 Steven S. Dick <ssd at nevets.oau.org>, Jim Van Zandt <jrv at
297 comcast.net>.
298
300 date(1L), gettimeofday(2), settimeofday(2), hwclock(8), ntpdate(8),
301 ntpd(8), /usr/src/linux/include/linux/timex.h,
302 /usr/src/linux/include/linux/sched.h, /usr/src/linux/kernel/time.c,
303 /usr/src/linux/kernel/sched.c
304 March 11, 2009 ADJTIMEX(8)