1ADJTIMEX(8)                 System Manager's Manual                ADJTIMEX(8)
2
3
4

NAME

6       adjtimex - display or set the kernel time variables
7

SYNOPSIS

9       adjtimex [option]...
10

DESCRIPTION

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
16       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
23       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
28       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
45       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
49       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

OPTIONS

60       Options may be introduced by either - or --, and unique abbreviations
61       may be used.
62
63       Here is a summary of the options, grouped by type.  Explanations fol‐
64       low.
65
66       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
73       Estimate Systematic Drifts
74              -c[count] --compare[=count] -i tim --interval tim -l file --log
75              file -h timeserver --host timeserver -w --watch -r[file]
76              --review[=file] -u --utc -d --directisa -n --nointerrupt
77
78       Informative Output
79              --help -v --version -V --verbose
80
81       -p, --print
82              Print the current values of the kernel time variables.  NOTE:
83              The time is "raw", and may be off by up to one timer tick (10
84              msec).  "status" gives the value of the time_status variable in
85              the kernel.  For Linux 1.0 and 1.2 kernels, the value is as
86              follows:
87                    0   clock is synchronized (so the kernel should
88                        periodically set the CMOS clock to match the
89                        system clock)
90                    1   inserting a leap second at midnight
91                    2   deleting a leap second at midnight
92                    3   leap second in progress
93                    4   leap second has occurred
94                    5   clock not externally synchronized (so the
95                        kernel should leave the CMOS clock alone)
96              For Linux kernels 2.0 through 2.6, the value is a sum of these:
97                    1   PLL updates enabled
98                    2   PPS freq discipline enabled
99                    4   PPS time discipline enabled
100                    8   frequency-lock mode enabled
101                   16   inserting leap second
102                   32   deleting leap second
103                   64   clock unsynchronized
104                  128   holding frequency
105                  256   PPS signal present
106                  512   PPS signal jitter exceeded
107                 1024   PPS signal wander exceeded
108                 2048   PPS signal calibration error
109                 4096   clock hardware fault
110
111       -t val, --tick val
112              Set the number of microseconds that should be added to the
113              system time for each kernel tick interrupt.  For a kernel with
114              USER_HZ=100, there are supposed to be 100 ticks per second, so
115              val should be close to 10000.  Increasing val by 1 speeds up the
116              system clock by about 100 ppm, or 8.64 sec/day.  tick must be in
117              the range 900000/USER_HZ...1100000/USER_HZ.  If val is rejected
118              by the kernel, adjtimex will determine the acceptable range
119              through trial and error and print it.  (After completing the
120              search, it will restore the original value.)
121
122       -f newfreq, --frequency newfreq
123              Set the system clock frequency offset to newfreq.  newfreq can
124              be negative or positive, and gives a much finer adjustment than
125              the --tick switch.  When USER_HZ=100, the value is scaled such
126              that newfreq = 65536 speeds up the system clock by about 1 ppm,
127              or .0864 sec/day.  Thus, all of these are about the same:
128                   --tick  9995 --frequency  32768000
129                   --tick 10000 --frequency   6553600
130                   --tick 10001 --frequency         0
131                   --tick 10002 --frequency  -6553600
132                   --tick 10005 --frequency -32768000
133              To see the acceptable range for newfreq, use --print and look at
134              "tolerance", or try an illegal value (e.g. --tick 0).
135
136       -s adj, --singleshot adj
137              Slew the system clock by adj usec.  (Its rate is changed
138              temporarily by about 1 part in 2000.)
139
140       -o adj, --offset adj
141              Add a time offset of adj usec.  The kernel code adjusts the time
142              gradually by adj, notes how long it has been since the last time
143              offset, and then adjusts the frequency offset to correct for the
144              apparent drift.  adj must be in the range -512000...512000.
145
146       -S status, --status status
147              Set kernel system clock status register to value status. Look
148              here above at the --print switch section for the meaning of
149              status, depending on your kernel.
150
151       -R, --reset
152              Reset clock status after setting a clock parameter.  For early
153              Linux kernels, using the adjtimex(2) system call to set any time
154              parameter the kernel think the clock is synchronized with an
155              external time source, so it sets the kernel variable time_status
156              to TIME_OK.  Thereafter, at 11 minute intervals, it will adjust
157              the CMOS clock to match.  We prevent this "eleven minute mode"
158              by setting the clock, because that has the side effect of
159              resetting time_status to TIME_BAD.  We try not to actually
160              change the clock setting.  Kernel versions 2.0.40 and later
161              apparently don't need this.  If your kernel does require it, use
162              this option with: -t -T -t -e -m -f -s -o -c -r.
163
164       -m val, --maxerror val
165              Set maximum error (usec).
166
167       -e val, --esterror val
168              Set estimated error (usec).  The maximum and estimated error are
169              not used by the kernel.  They are merely made available to user
170              processes via the adjtimex(2) system call.
171
172       -T val, --timeconstant val
173              Set phase locked loop (PLL) time constant.  val determines the
174              bandwidth or "stiffness" of the PLL.  The effective PLL time
175              constant will be a multiple of (2^val).  For room-temperature
176              quartz oscillators, David Mills recommends the value 2, which
177              corresponds to a PLL time constant of about 900 sec and a
178              maximum update interval of about 64 sec.  The maximum update
179              interval scales directly with the time constant, so that at the
180              maximum time constant of 6, the update interval can be as large
181              as 1024 sec.
182
183              Values of val between zero and 2 give quick convergence; values
184              between 2 and 6 can be used to reduce network load, but at a
185              modest cost in accuracy.
186
187       -c[count], --compare[=count]
188              Periodically compare the system clock with the CMOS clock.
189              After the first two calls, print values for tick and frequency
190              offset that would bring the system clock into approximate
191              agreement with the CMOS clock.  CMOS clock readings are adjusted
192              for systematic drift using using the correction in /etc/adjtime
193              — see hwclock(8).  The interval between comparisons is 10
194              seconds, unless changed by the --interval switch.  The optional
195              argument is the number of comparisons.  (If the argument is
196              supplied, the "=" is required.)  If the CMOS clock and the
197              system clock differ by more than six minutes, adjtimex will try
198              shifting the time from the CMOS clock by some multiple of one
199              hour, up to plus or minus 13 hours in all.  This should allow
200              correct operation, including logging, if the --utc switch was
201              used when the CMOS clock is set to local time (or vice-versa),
202              or if summer time has started or stopped since the CMOS clock
203              was last set.
204
205       -a[count], --adjust[=count]
206              By itself, same as --compare, except the recommended values are
207              actually installed after every third comparison.  With --review,
208              the tick and frequency are set to the least-squares estimates.
209              (In the latter case, any count value is ignored.)
210
211       --force-adjust
212              Override the sanity check that prevents changing the clock rate
213              by more than 500 ppm.
214
215       -i tim, --interval tim
216              Set the interval in seconds between clock comparisons for the
217              --compare and --adjust options.
218
219       -u, --utc
220              The CMOS clock is set to UTC (universal time) rather than local
221              time.
222
223       -d, --directisa
224              To read the CMOS clock accurately, adjtimex usually accesses the
225              clock via the /dev/rtc device driver of the kernel, and makes
226              use of its CMOS update-ended interrupt to detect the beginning
227              of seconds. It will also try /dev/rtc0 (for udev), /dev/misc/rtc
228              (for the obsolete devfs) and possibly others.  When the /dev/rtc
229              driver is absent, or when the interrupt is not available,
230              adjtimex can sometimes automatically fallback to a direct access
231              method. This method detects the start of seconds by polling the
232              update-in-progress (UIP) flag of the CMOS clock. You can force
233              this direct access to the CMOS chip with the --directisa switch.
234
235              Note that the /dev/rtc interrupt method is more accurate, less
236              sensible to perturbations due to system load, cleaner, cheaper,
237              and is generally better than the direct access method. It is
238              advisable to not use the --directisa switch, unless the CMOS
239              chip or the motherboard don't properly provide the necessary
240              interrupt.
241
242       -n, --nointerrupt
243              Force immediate use of busywait access method, without first
244              waiting for the interrupt timeout.
245
246       -l[file], --log[=file]
247              Save the current values of the system and CMOS clocks, and
248              optionally a reference time, to file (default
249              /var/log/clocks.log).  The reference time is taken from a
250              network timeserver (see the --host switch) or supplied by the
251              user (see the --watch switch).
252
253       -h timeserver, --host timeserver
254              Use ntpdate to query the given timeserver for the current time.
255              This will fail if timeserver is not running a Network Time
256              Protocol (NTP) server, or if that server is not synchronized.
257              Implies --log.
258
259       -w, --watch
260              Ask for a keypress when the user knows the time, then ask what
261              that time was, and its approximate accuracy.  Implies --log.
262
263       -r[file], --review[=file]
264              Review the clock log file (default /var/log/clocks.log) and
265              estimate, if possible, the rates of the CMOS and system clocks.
266              Calculate least-squares rates using all suitable log entries.
267              Suggest corrections to adjust for systematic drift.  With
268              --adjust, the frequency and tick are set to the suggested
269              values.  (The CMOS clock correction is not changed.)
270
271       -V, --verbose
272              Increase verbosity.
273
274       --help Print the program options.
275
276       -v, --version
277              Print the program version.
278

EXAMPLES

280       If your system clock gained 8 seconds in 24 hours, you could set the
281       tick to 9999, and then it would lose 0.64 seconds a day (that is, 1
282       tick unit = 8.64 seconds per day).  To correct the rest of the error,
283       you could set the frequency offset to (2^16)*0.64/.0864 = 485452.
284       Thus, putting the following in rc.local would approximately correct the
285       system clock:
286
287            adjtimex  --tick 9999  --frequency 485452
288

NOTES

290       adjtimex adjusts only the system clock — the one that runs while the
291       computer is powered up.  To set or regulate the CMOS clock, see
292       hwclock(8).
293

AUTHORS

295       Steven S. Dick <ssd at nevets.oau.org>, Jim Van Zandt <jrv at
296       comcast.net>.
297

SEE ALSO

299       date(1L), gettimeofday(2), settimeofday(2), hwclock(8), ntpdate(8),
300       ntpd(8), /usr/src/linux/include/linux/timex.h,
301       /usr/src/linux/include/linux/sched.h, /usr/src/linux/kernel/time.c,
302       /usr/src/linux/kernel/sched.c
303
304
305
306                                March 11, 2009                     ADJTIMEX(8)
Impressum