1HWCLOCK(8)                   System Administration                  HWCLOCK(8)
2
3
4

NAME

6       hwclock - time clocks utility
7

SYNOPSIS

9       hwclock [function] [option...]
10

DESCRIPTION

12       hwclock is an administration tool for the time clocks.  It can: display
13       the Hardware Clock time; set the Hardware Clock to  a  specified  time;
14       set the Hardware Clock from the System Clock; set the System Clock from
15       the Hardware Clock; compensate for Hardware Clock  drift;  correct  the
16       System  Clock  timescale; set the kernel's timezone, NTP timescale, and
17       epoch (Alpha only); and predict future Hardware Clock values  based  on
18       its drift rate.
19
20       Since  v2.26  important changes were made to the --hctosys function and
21       the --directisa option, and a new option --update-drift was added.  See
22       their respective descriptions below.
23

FUNCTIONS

25       The  following  functions are mutually exclusive, only one can be given
26       at a time.  If none is given, the default is --show.
27
28       -a, --adjust
29              Add or subtract time from the Hardware Clock to account for sys‐
30              tematic drift since the last time the clock was set or adjusted.
31              See the discussion below, under The Adjust Function.
32
33       --getepoch
34       --setepoch
35              These functions are for Alpha machines only, and are only avail‐
36              able through the Linux kernel RTC driver.
37
38              They  are used to read and set the kernel's Hardware Clock epoch
39              value.  Epoch is the number of years into AD  to  which  a  zero
40              year  value  in  the Hardware Clock refers.  For example, if the
41              machine's BIOS sets the year counter in the  Hardware  Clock  to
42              contain  the  number of full years since 1952, then the kernel's
43              Hardware Clock epoch value must be 1952.
44
45              The --setepoch function requires using  the  --epoch  option  to
46              specify the year.  For example:
47
48                  hwclock --setepoch --epoch=1952
49
50              The  RTC  driver  attempts  to guess the correct epoch value, so
51              setting it may not be required.
52
53              This epoch value is used whenever  hwclock  reads  or  sets  the
54              Hardware Clock on an Alpha machine.  For ISA machines the kernel
55              uses the fixed Hardware Clock epoch of 1900.
56
57       --predict
58              Predict what the Hardware Clock will read in  the  future  based
59              upon  the time given by the --date option and the information in
60              /etc/adjtime.  This is useful, for example, to account for drift
61              when   setting   a   Hardware  Clock  wakeup  (aka  alarm).  See
62              rtcwake(8).
63
64              Do not use this function if the Hardware Clock is being modified
65              by  anything  other  than the current operating system's hwclock
66              command, such as '11 minute mode' or from  dual-booting  another
67              OS.
68
69       -r, --show
70       --get
71              Read the Hardware Clock and print its time to standard output in
72              the ISO 8601 format.  The time shown is always  in  local  time,
73              even   if  you  keep  your  Hardware  Clock  in  UTC.   See  the
74              --localtime option.
75
76              Showing the Hardware Clock time is the default when no  function
77              is specified.
78
79              The  --get  function  also  applies drift correction to the time
80              read, based upon the information in /etc/adjtime.   Do  not  use
81              this  function  if  the Hardware Clock is being modified by any‐
82              thing other than the current operating system's hwclock command,
83              such as '11 minute mode' or from dual-booting another OS.
84
85       -s, --hctosys
86              Set  the  System  Clock  from the Hardware Clock.  The time read
87              from the Hardware Clock is compensated to account for systematic
88              drift  before using it to set the System Clock.  See the discus‐
89              sion below, under The Adjust Function.
90
91              The System Clock must be kept in the UTC timescale for date-time
92              applications  to work correctly in conjunction with the timezone
93              configured for the system.  If the Hardware  Clock  is  kept  in
94              local time then the time read from it must be shifted to the UTC
95              timescale  before  using  it  to  set  the  System  Clock.   The
96              --hctosys  function  does this based upon the information in the
97              /etc/adjtime file or the command line arguments --localtime  and
98              --utc.   Note:  no  daylight saving adjustment is made.  See the
99              discussion below, under LOCAL vs UTC.
100
101              The kernel also keeps a timezone value, the  --hctosys  function
102              sets  it  to the timezone configured for the system.  The system
103              timezone is configured by the TZ  environment  variable  or  the
104              /etc/localtime  file,  as  tzset(3)  would  interpret them.  The
105              obsolete tz_dsttime field of the kernel's timezone value is  set
106              to  zero.   (For  details  on  what this field used to mean, see
107              settimeofday(2).)
108
109              When used in a startup script, making the --hctosys function the
110              first  caller  of settimeofday(2) from boot, it will set the NTP
111              '11 minute mode'  timescale  via  the  persistent_clock_is_local
112              kernel  variable.   If the Hardware Clock's timescale configura‐
113              tion is changed then a reboot is required to inform the  kernel.
114              See  the  discussion  below, under Automatic Hardware Clock Syn‐
115              chronization by the Kernel.
116
117              This is a good function to use in  one  of  the  system  startup
118              scripts before the file systems are mounted read/write.
119
120              This  function should never be used on a running system. Jumping
121              system time will cause problems, such  as  corrupted  filesystem
122              timestamps.   Also, if something has changed the Hardware Clock,
123              like NTP's '11 minute mode', then --hctosys will  set  the  time
124              incorrectly by including drift compensation.
125
126              Drift  compensation can be inhibited by setting the drift factor
127              in /etc/adjtime to zero.  This setting  will  be  persistent  as
128              long  as the --update-drift option is not used with --systohc at
129              shutdown (or anywhere else).  Another way to inhibit this is  by
130              using  the  --noadjfile  option when calling the --hctosys func‐
131              tion.  A third  method  is  to  delete  the  /etc/adjtime  file.
132              Hwclock  will  then  default  to using the UTC timescale for the
133              Hardware Clock.  If the Hardware Clock is ticking local time  it
134              will  need to be defined in the file.  This can be done by call‐
135              ing hwclock --localtime --adjust; when the file is  not  present
136              this  command  will  not  actually adjust the Clock, but it will
137              create the file with local time configured, and a  drift  factor
138              of zero.
139
140              A  condition  under  which inhibiting hwclock's drift correction
141              may be desired is when dual-booting multiple operating  systems.
142              If  while  this instance of Linux is stopped, another OS changes
143              the Hardware Clock's value, then when this instance  is  started
144              again the drift correction applied will be incorrect.
145
146              For hwclock's drift correction to work properly it is imperative
147              that nothing changes the Hardware Clock while its Linux instance
148              is not running.
149
150       --set  Set  the  Hardware Clock to the time given by the --date option,
151              and  update  the   timestamps   in   /etc/adjtime.    With   the
152              --update-drift  option also (re)calculate the drift factor.  Try
153              it without the option if --set fails.  See --update-drift below.
154
155       --systz
156              This is an alternate to the --hctosys  function  that  does  not
157              read  the  Hardware Clock nor set the System Clock; consequently
158              there is not any drift correction.  It is intended to be used in
159              a startup script on systems with kernels above version 2.6 where
160              you know the System Clock has been set from the  Hardware  Clock
161              by the kernel during boot.
162
163              It  does  the  following  things  that are detailed above in the
164              --hctosys function:
165
166              · Corrects the System Clock timescale to UTC  as  needed.   Only
167                instead  of  accomplishing  this  by setting the System Clock,
168                hwclock simply informs the kernel and it handles the change.
169
170              · Sets the kernel's NTP '11 minute mode' timescale.
171
172              · Sets the kernel's timezone.
173
174              The  first  two  are  only  available  on  the  first  call   of
175              settimeofday(2) after boot.  Consequently this option only makes
176              sense when used in a startup script.   If  the  Hardware  Clocks
177              timescale  configuration  is  changed  then  a  reboot  would be
178              required to inform the kernel.
179
180       -w, --systohc
181              Set the Hardware Clock from the System  Clock,  and  update  the
182              timestamps in /etc/adjtime.  With the --update-drift option also
183              (re)calculate the drift factor.  Try it without  the  option  if
184              --systohc fails.  See --update-drift below.
185
186       -V, --version
187              Display version information and exit.
188
189       -h, --help
190              Display help text and exit.
191

OPTIONS

193       --adjfile=filename
194              Override the default /etc/adjtime file path.
195
196       --date=date_string
197              This  option must be used with the --set or --predict functions,
198              otherwise it is ignored.
199
200                  hwclock --set --date='16:45'
201
202                  hwclock --predict --date='2525-08-14 07:11:05'
203
204              The argument must be in local time, even if you keep your  Hard‐
205              ware  Clock in UTC.  See the --localtime option.  Therefore, the
206              argument should not include any timezone information.   It  also
207              should  not  be  a  relative  time  like  "+5  minutes", because
208              hwclock's precision depends upon correlation between  the  argu‐
209              ment's value and when the enter key is pressed.  Fractional sec‐
210              onds are silently dropped.  This option  is  capable  of  under‐
211              standing many time and date formats, but the previous parameters
212              should be observed.
213
214       -D, --debug
215              Use --verbose.  The --debug option has been deprecated  and  may
216              be repurposed or removed in a future release.
217
218       --directisa
219              This option is meaningful for ISA compatible machines in the x86
220              and x86_64 family.  For other machines, it has no effect.   This
221              option  tells hwclock to use explicit I/O instructions to access
222              the Hardware Clock.  Without this option, hwclock will  use  the
223              rtc  device file, which it assumes to be driven by the Linux RTC
224              device driver.  As of v2.26 it will no longer automatically  use
225              directisa  when  the rtc driver is unavailable; this was causing
226              an unsafe condition that could allow two processes to access the
227              Hardware  Clock  at  the same time.  Direct hardware access from
228              userspace should only be used for testing, troubleshooting,  and
229              as  a  last  resort  when all other methods fail.  See the --rtc
230              option.
231
232       --epoch=year
233              This option is required when using the --setepoch function.  The
234              minimum  year  value  is  1900.  The maximum is system dependent
235              (ULONG_MAX - 1).
236
237       -f, --rtc=filename
238              Override hwclock's default rtc device file name.   Otherwise  it
239              will use the first one found in this order:
240                  /dev/rtc0
241                  /dev/rtc
242                  /dev/misc/rtc
243              For IA-64:
244                  /dev/efirtc
245                  /dev/misc/efirtc
246
247       -l, --localtime
248       -u, --utc
249              Indicate which timescale the Hardware Clock is set to.
250
251              The  Hardware  Clock  may be configured to use either the UTC or
252              the local timescale, but nothing in the clock itself says  which
253              alternative  is  being  used.   The --localtime or --utc options
254              give this information to the hwclock command.   If  you  specify
255              the  wrong  one  (or  specify neither and take a wrong default),
256              both setting and reading the Hardware Clock will be incorrect.
257
258              If you specify neither --utc nor --localtime then the  one  last
259              given  with  a  set function (--set, --systohc, or --adjust), as
260              recorded in /etc/adjtime, will be used.   If  the  adjtime  file
261              doesn't exist, the default is UTC.
262
263              Note:  daylight saving time changes may be inconsistent when the
264              Hardware Clock is kept in local time.  See the discussion below,
265              under LOCAL vs UTC.
266
267       --noadjfile
268              Disable  the  facilities provided by /etc/adjtime.  hwclock will
269              not read nor write to that file with this option.  Either  --utc
270              or --localtime must be specified when using this option.
271
272       --test Do  not  actually  change  anything  on the system, that is, the
273              Clocks or /etc/adjtime (--verbose is implicit with this option).
274
275       --update-drift
276              Update the Hardware Clock's drift factor  in  /etc/adjtime.   It
277              can only be used with --set or --systohc,
278
279              A  minimum  four hour period between settings is required.  This
280              is to avoid invalid calculations.  The longer  the  period,  the
281              more precise the resulting drift factor will be.
282
283              This  option  was added in v2.26, because it is typical for sys‐
284              tems to call hwclock --systohc at shutdown; with the old  behav‐
285              iour  this  would  automatically  (re)calculate the drift factor
286              which caused several problems:
287
288              · When using ntpd with an '11 minute mode' kernel the drift fac‐
289                tor would be clobbered to near zero.
290
291              · It  would  not allow the use of 'cold' drift correction.  With
292                most configurations using 'cold' drift  will  yield  favorable
293                results.  Cold, means when the machine is turned off which can
294                have a significant impact on the drift factor.
295
296              · (Re)calculating drift factor on every shutdown delivers subop‐
297                timal results.  For example, if ephemeral conditions cause the
298                machine to be abnormally  hot  the  drift  factor  calculation
299                would be out of range.
300
301              · Significantly  increased  system  shutdown  times (as of v2.31
302                when not using --update-drift the RTC is not read).
303
304              Having hwclock calculate the drift factor  is  a  good  starting
305              point,  but  for  optimal  results  it  will  likely  need to be
306              adjusted by directly editing the /etc/adjtime  file.   For  most
307              configurations  once a machine's optimal drift factor is crafted
308              it should not need to be changed.  Therefore, the  old  behavior
309              to   automatically  (re)calculate  drift  was  changed  and  now
310              requires this option to be  used.   See  the  discussion  below,
311              under The Adjust Function.
312
313              This  option  requires reading the Hardware Clock before setting
314              it.  If it cannot be read, then this option will cause  the  set
315              functions  to  fail.  This can happen, for example, if the Hard‐
316              ware Clock is corrupted by a power failure.  In that  case,  the
317              clock  must  first  be  set without this option.  Despite it not
318              working, the resulting drift correction factor would be  invalid
319              anyway.
320
321       -v, --verbose
322              Display more details about what hwclock is doing internally.
323

NOTES

325   Clocks in a Linux System
326       There are two types of date-time clocks:
327
328       The  Hardware Clock: This clock is an independent hardware device, with
329       its own power domain (battery, capacitor, etc), that operates when  the
330       machine is powered off, or even unplugged.
331
332       On an ISA compatible system, this clock is specified as part of the ISA
333       standard.  A control program can read or set this clock only to a whole
334       second,  but  it can also detect the edges of the 1 second clock ticks,
335       so the clock actually has virtually infinite precision.
336
337       This clock is commonly called the hardware clock, the real time  clock,
338       the  RTC,  the  BIOS clock, and the CMOS clock.  Hardware Clock, in its
339       capitalized form, was coined for use by hwclock.  The Linux kernel also
340       refers to it as the persistent clock.
341
342       Some  non-ISA systems have a few real time clocks with only one of them
343       having its own power domain.  A very low  power  external  I2C  or  SPI
344       clock chip might be used with a backup battery as the hardware clock to
345       initialize a more functional integrated real-time clock which  is  used
346       for most other purposes.
347
348       The  System Clock: This clock is part of the Linux kernel and is driven
349       by a timer interrupt.  (On an ISA machine, the timer interrupt is  part
350       of  the  ISA  standard.)  It has meaning only while Linux is running on
351       the machine.  The System Time is the number of seconds  since  00:00:00
352       January  1,  1970  UTC (or more succinctly, the number of seconds since
353       1969 UTC).  The System Time is not an integer, though.  It  has  virtu‐
354       ally infinite precision.
355
356       The  System  Time is the time that matters.  The Hardware Clock's basic
357       purpose is to keep time when Linux is not running so  that  the  System
358       Clock  can be initialized from it at boot.  Note that in DOS, for which
359       ISA was designed, the Hardware Clock is the only real time clock.
360
361       It is important that the System Time not have any discontinuities  such
362       as  would  happen  if  you used the date(1) program to set it while the
363       system is running.  You can, however, do whatever you want to the Hard‐
364       ware  Clock while the system is running, and the next time Linux starts
365       up, it will do so with the  adjusted  time  from  the  Hardware  Clock.
366       Note:   currently   this  is  not  possible  on  most  systems  because
367       hwclock --systohc is called at shutdown.
368
369       The Linux kernel's timezone is set by hwclock.  But don't be misled  --
370       almost nobody cares what timezone the kernel thinks it is in.  Instead,
371       programs that care about the timezone (perhaps  because  they  want  to
372       display  a  local  time  for  you) almost always use a more traditional
373       method of determining the timezone: They use the TZ  environment  vari‐
374       able  or  the  /etc/localtime  file,  as  explained in the man page for
375       tzset(3).  However, some programs and fringe parts of the Linux  kernel
376       such as filesystems use the kernel's timezone value.  An example is the
377       vfat filesystem.  If the kernel  timezone  value  is  wrong,  the  vfat
378       filesystem  will report and set the wrong timestamps on files.  Another
379       example is the kernel's NTP '11 minute mode'.  If the kernel's timezone
380       value and/or the persistent_clock_is_local variable are wrong, then the
381       Hardware Clock will be set incorrectly by  '11 minute mode'.   See  the
382       discussion below, under Automatic Hardware Clock Synchronization by the
383       Kernel.
384
385       hwclock sets the kernel's timezone to the  value  indicated  by  TZ  or
386       /etc/localtime with the --hctosys or --systz functions.
387
388       The  kernel's timezone value actually consists of two parts: 1) a field
389       tz_minuteswest indicating how many minutes local time (not adjusted for
390       DST)  lags behind UTC, and 2) a field tz_dsttime indicating the type of
391       Daylight Savings Time (DST) convention that is in effect in the  local‐
392       ity at the present time.  This second field is not used under Linux and
393       is always zero.  See also settimeofday(2).
394
395   Hardware Clock Access Methods
396       hwclock uses many different ways to get and set Hardware Clock  values.
397       The  most normal way is to do I/O to the rtc device special file, which
398       is presumed to be driven by the rtc device driver.  Also, Linux systems
399       using  the  rtc framework with udev, are capable of supporting multiple
400       Hardware Clocks.  This may bring about the need to override the default
401       rtc device by specifying one with the --rtc option.
402
403       However,  this  method  is not always available as older systems do not
404       have an rtc driver.  On these systems,  the  method  of  accessing  the
405       Hardware Clock depends on the system hardware.
406
407       On an ISA compatible system, hwclock can directly access the "CMOS mem‐
408       ory" registers that constitute the clock, by doing I/O  to  Ports  0x70
409       and  0x71.   It does this with actual I/O instructions and consequently
410       can only do it if running with superuser effective userid.  This method
411       may be used by specifying the --directisa option.
412
413       This  is  a really poor method of accessing the clock, for all the rea‐
414       sons that userspace programs are generally not supposed  to  do  direct
415       I/O  and  disable  interrupts.   hwclock provides it for testing, trou‐
416       bleshooting, and  because it may be the only method  available  on  ISA
417       systems which do not have a working rtc device driver.
418
419   The Adjust Function
420       The  Hardware Clock is usually not very accurate.  However, much of its
421       inaccuracy is completely predictable -  it  gains  or  loses  the  same
422       amount  of time every day.  This is called systematic drift.  hwclock's
423       --adjust function lets you apply systematic drift  corrections  to  the
424       Hardware Clock.
425
426       It works like this: hwclock keeps a file, /etc/adjtime, that keeps some
427       historical information.  This is called the adjtime file.
428
429       Suppose you start with no adjtime file.  You issue a hwclock --set com‐
430       mand  to set the Hardware Clock to the true current time.  hwclock cre‐
431       ates the adjtime file and records in it the current time  as  the  last
432       time  the  clock was calibrated.  Five days later, the clock has gained
433       10 seconds, so you issue a hwclock --set --update-drift command to  set
434       it  back 10 seconds.  hwclock updates the adjtime file to show the cur‐
435       rent time as the last time the clock was calibrated, and records 2 sec‐
436       onds  per  day  as the systematic drift rate.  24 hours go by, and then
437       you issue a hwclock --adjust command.   hwclock  consults  the  adjtime
438       file  and  sees  that the clock gains 2 seconds per day when left alone
439       and that it has been left alone for exactly one day.  So it subtracts 2
440       seconds  from  the Hardware Clock.  It then records the current time as
441       the last time the clock was adjusted.  Another 24 hours go by  and  you
442       issue another hwclock --adjust.  hwclock does the same thing: subtracts
443       2 seconds and updates the adjtime file with the  current  time  as  the
444       last time the clock was adjusted.
445
446       When  you  use  the  --update-drift option with --set or --systohc, the
447       systematic drift rate is (re)calculated by comparing  the  fully  drift
448       corrected  current Hardware Clock time with the new set time, from that
449       it derives the 24 hour drift rate based on the  last  calibrated  time‐
450       stamp  from  the adjtime file.  This updated drift factor is then saved
451       in /etc/adjtime.
452
453       A small amount of error creeps in when the Hardware Clock  is  set,  so
454       --adjust  refrains  from making any adjustment that is less than 1 sec‐
455       ond.  Later on, when you request an adjustment again,  the  accumulated
456       drift  will be more than 1 second and --adjust will make the adjustment
457       including any fractional amount.
458
459       hwclock --hctosys also uses the adjtime file  data  to  compensate  the
460       value  read  from  the Hardware Clock before using it to set the System
461       Clock.  It does not share the 1 second limitation of --adjust, and will
462       correct  sub-second  drift  values immediately.  It does not change the
463       Hardware Clock time nor the adjtime file.  This may eliminate the  need
464       to use --adjust, unless something else on the system needs the Hardware
465       Clock to be compensated.
466
467   The Adjtime File
468       While named for its historical purpose of controlling adjustments only,
469       it actually contains other information used by hwclock from one invoca‐
470       tion to the next.
471
472       The format of the adjtime file is, in ASCII:
473
474       Line 1: Three numbers, separated by blanks:  1)  the  systematic  drift
475       rate  in seconds per day, floating point decimal; 2) the resulting num‐
476       ber of seconds since 1969 UTC of most recent adjustment or calibration,
477       decimal integer; 3) zero (for compatibility with clock(8)) as a decimal
478       integer.
479
480       Line 2: One number: the resulting number of seconds since 1969  UTC  of
481       most  recent calibration.  Zero if there has been no calibration yet or
482       it is known that any previous calibration is moot (for example, because
483       the  Hardware Clock has been found, since that calibration, not to con‐
484       tain a valid time).  This is a decimal integer.
485
486       Line 3: "UTC" or "LOCAL".  Tells whether the Hardware Clock is  set  to
487       Coordinated Universal Time or local time.  You can always override this
488       value with options on the hwclock command line.
489
490       You can use an adjtime file that was previously used with the  clock(8)
491       program with hwclock.
492
493   Automatic Hardware Clock Synchronization by the Kernel
494       You should be aware of another way that the Hardware Clock is kept syn‐
495       chronized in some systems.  The Linux kernel  has  a  mode  wherein  it
496       copies  the  System  Time  to the Hardware Clock every 11 minutes. This
497       mode is a compile time option, so not all kernels will have this  capa‐
498       bility.   This  is  a  good  mode  to  use when you are using something
499       sophisticated like NTP to keep your System Clock synchronized. (NTP  is
500       a  way  to  keep  your System Time synchronized either to a time server
501       somewhere on the network or to a radio clock hooked up to your  system.
502       See RFC 1305.)
503
504       If  the  kernel is compiled with the '11 minute mode' option it will be
505       active when the kernel's clock discipline is in a  synchronized  state.
506       When  in  this state, bit 6 (the bit that is set in the mask 0x0040) of
507       the kernel's time_status variable is unset. This value is output as the
508       'status' line of the adjtimex --print or ntptime commands.
509
510       It  takes an outside influence, like the NTP daemon ntpd(1), to put the
511       kernel's clock discipline into a synchronized state, and therefore turn
512       on  '11 minute mode'.   It  can  be turned off by running anything that
513       sets   the   System   Clock   the   old   fashioned   way,    including
514       hwclock --hctosys.   However,  if  the  NTP daemon is still running, it
515       will turn '11 minute mode' back on again the next time it  synchronizes
516       the System Clock.
517
518       If your system runs with '11 minute mode' on, it may need to use either
519       --hctosys or --systz in a startup script, especially  if  the  Hardware
520       Clock  is  configured  to use the local timescale. Unless the kernel is
521       informed of what timescale the Hardware Clock is using, it may  clobber
522       it with the wrong one. The kernel uses UTC by default.
523
524       The  first userspace command to set the System Clock informs the kernel
525       what timescale the Hardware Clock  is  using.   This  happens  via  the
526       persistent_clock_is_local  kernel variable.  If --hctosys or --systz is
527       the first, it will set this variable according to the adjtime  file  or
528       the appropriate command-line argument.  Note that when using this capa‐
529       bility and the Hardware Clock timescale configuration is changed,  then
530       a reboot is required to notify the kernel.
531
532       hwclock --adjust should not be used with NTP '11 minute mode'.
533
534   ISA Hardware Clock Century value
535       There  is  some sort of standard that defines CMOS memory Byte 50 on an
536       ISA machine as an indicator of what century it is.   hwclock  does  not
537       use  or set that byte because there are some machines that don't define
538       the byte that way, and it really  isn't  necessary  anyway,  since  the
539       year-of-century does a good job of implying which century it is.
540
541       If  you  have  a  bona  fide  use  for a CMOS century byte, contact the
542       hwclock maintainer; an option may be appropriate.
543
544       Note that this section is only relevant when you are using the  "direct
545       ISA"  method of accessing the Hardware Clock.  ACPI provides a standard
546       way to access century values, when they are supported by the hardware.
547

DATE-TIME CONFIGURATION

549   Keeping Time without External Synchronization
550       This discussion is based on the following conditions:
551
552       · Nothing is running that alters the date-time clocks, such as  ntpd(1)
553         or a cron job.
554
555       · The  system  timezone  is configured for the correct local time.  See
556         below, under POSIX vs 'RIGHT'.
557
558       · Early during startup the following are called, in this order:
559         adjtimex --tick value --frequency value
560         hwclock --hctosys
561
562       · During shutdown the following is called:
563         hwclock --systohc
564
565           * Systems without adjtimex may use ntptime.
566
567       Whether maintaining precision time with ntpd(1) or not, it makes  sense
568       to configure the system to keep reasonably good date-time on its own.
569
570       The first step in making that happen is having a clear understanding of
571       the big picture.  There are two completely  separate  hardware  devices
572       running at their own speed and drifting away from the 'correct' time at
573       their own rates.  The methods and software  for  drift  correction  are
574       different  for  each  of them.  However, most systems are configured to
575       exchange values between these two clocks at startup and shutdown.   Now
576       the  individual  device's  time keeping errors are transferred back and
577       forth between each other.  Attempt to configure  drift  correction  for
578       only one of them, and the other's drift will be overlaid upon it.
579
580       This  problem  can be avoided when configuring drift correction for the
581       System Clock by simply not shutting down the machine.  This,  plus  the
582       fact  that all of hwclock's precision (including calculating drift fac‐
583       tors) depends upon the System Clock's rate being  correct,  means  that
584       configuration of the System Clock should be done first.
585
586       The  System  Clock  drift  is  corrected with the adjtimex(8) command's
587       --tick and --frequency options.  These two work together: tick  is  the
588       coarse  adjustment  and frequency is the fine adjustment.  (For systems
589       that do not have  an  adjtimex  package,  ntptime -f ppm  may  be  used
590       instead.)
591
592       Some  Linux distributions attempt to automatically calculate the System
593       Clock drift with adjtimex's compare operation.  Trying to  correct  one
594       drifting  clock  by using another drifting clock as a reference is akin
595       to a dog trying to catch its own tail.  Success may happen  eventually,
596       but  great effort and frustration will likely precede it.  This automa‐
597       tion may yield an improvement  over  no  configuration,  but  expecting
598       optimum results would be in error.  A better choice for manual configu‐
599       ration would be adjtimex's --log options.
600
601       It may be more effective to simply track the System  Clock  drift  with
602       sntp,  or  date -Ins  and a precision timepiece, and then calculate the
603       correction manually.
604
605       After setting the tick and  frequency  values,  continue  to  test  and
606       refine  the  adjustments  until  the System Clock keeps good time.  See
607       adjtimex(8) for more information and the example  demonstrating  manual
608       drift calculations.
609
610       Once  the  System  Clock  is  ticking smoothly, move on to the Hardware
611       Clock.
612
613       As a rule, cold drift will work best for most use cases.   This  should
614       be  true  even  for  24/7  machines whose normal downtime consists of a
615       reboot.  In that case the drift factor value makes  little  difference.
616       But  on the rare occasion that the machine is shut down for an extended
617       period, then cold drift should yield better results.
618
619       Steps to calculate cold drift:
620
621       1 Ensure that ntpd(1) will not be launched at startup.
622
623       2 The System Clock time must be correct at shutdown!
624
625       3 Shut down the system.
626
627       4 Let an extended period pass without changing the Hardware Clock.
628
629       5 Start the system.
630
631       6 Immediately  use  hwclock  to  set  the  correct  time,  adding   the
632         --update-drift option.
633
634       Note:  if step 6 uses --systohc, then the System Clock must be set cor‐
635       rectly (step 6a) just before doing so.
636
637       Having hwclock calculate the drift factor is a good starting point, but
638       for  optimal  results  it  will  likely need to be adjusted by directly
639       editing the /etc/adjtime file.  Continue to test and refine  the  drift
640       factor  until  the Hardware Clock is corrected properly at startup.  To
641       check this, first make sure that the  System  Time  is  correct  before
642       shutdown  and  then  use  sntp, or date -Ins and a precision timepiece,
643       immediately after startup.
644
645   LOCAL vs UTC
646       Keeping the Hardware Clock in a  local  timescale  causes  inconsistent
647       daylight saving time results:
648
649       · If  Linux  is  running during a daylight saving time change, the time
650         written to the Hardware Clock will be adjusted for the change.
651
652       · If Linux is NOT running during a daylight  saving  time  change,  the
653         time  read  from  the  Hardware  Clock  will  NOT be adjusted for the
654         change.
655
656       The Hardware Clock on an ISA compatible system keeps only  a  date  and
657       time,  it  has  no  concept of timezone nor daylight saving. Therefore,
658       when hwclock is told that it is in local time, it assumes it is in  the
659       'correct' local time and makes no adjustments to the time read from it.
660
661       Linux  handles daylight saving time changes transparently only when the
662       Hardware Clock is kept in the UTC timescale. Doing so is made easy  for
663       system  administrators as hwclock uses local time for its output and as
664       the argument to the --date option.
665
666       POSIX systems, like Linux, are designed to have the System Clock  oper‐
667       ate in the UTC timescale. The Hardware Clock's purpose is to initialize
668       the System Clock, so also keeping it in UTC makes sense.
669
670       Linux does, however, attempt to accommodate the Hardware Clock being in
671       the local timescale. This is primarily for dual-booting with older ver‐
672       sions of MS Windows. From Windows 7 on,  the  RealTimeIsUniversal  reg‐
673       istry key is supposed to be working properly so that its Hardware Clock
674       can be kept in UTC.
675
676   POSIX vs 'RIGHT'
677       A discussion on date-time configuration  would  be  incomplete  without
678       addressing  timezones,  this  is  mostly well covered by tzset(3).  One
679       area that seems to have no documentation is the  'right'  directory  of
680       the Time Zone Database, sometimes called tz or zoneinfo.
681
682       There  are  two  separate  databases  in the zoneinfo system, posix and
683       'right'. 'Right' (now named zoneinfo-leaps) includes leap  seconds  and
684       posix  does  not.  To use the 'right' database the System Clock must be
685       set to (UTC + leap seconds), which is equivalent  to  (TAI - 10).  This
686       allows  calculating  the exact number of seconds between two dates that
687       cross a leap second epoch. The System Clock is then  converted  to  the
688       correct  civil time, including UTC, by using the 'right' timezone files
689       which subtract the leap seconds. Note: this configuration is considered
690       experimental and is known to have issues.
691
692       To  configure  a  system  to use a particular database all of the files
693       located  in  its  directory   must   be   copied   to   the   root   of
694       /usr/share/zoneinfo.   Files  are never used directly from the posix or
695       'right' subdirectories, e.g., TZ='right/Europe/Dublin'.  This habit was
696       becoming  so common that the upstream zoneinfo project restructured the
697       system's file tree by moving the posix and 'right'  subdirectories  out
698       of the zoneinfo directory and into sibling directories:
699
700         /usr/share/zoneinfo
701         /usr/share/zoneinfo-posix
702         /usr/share/zoneinfo-leaps
703
704       Unfortunately, some Linux distributions are changing it back to the old
705       tree structure in their packages. So the problem of system  administra‐
706       tors  reaching  into the 'right' subdirectory persists. This causes the
707       system timezone to be configured to  include  leap  seconds  while  the
708       zoneinfo  database  is  still  configured to exclude them. Then when an
709       application such as a World Clock needs the South_Pole  timezone  file;
710       or  an email MTA, or hwclock needs the UTC timezone file; they fetch it
711       from the root of /usr/share/zoneinfo , because that is  what  they  are
712       supposed  to do. Those files exclude leap seconds, but the System Clock
713       now includes them, causing an incorrect time conversion.
714
715       Attempting to mix and match files from these  separate  databases  will
716       not work, because they each require the System Clock to use a different
717       timescale. The zoneinfo database must be configured to use either posix
718       or  'right', as described above, or by assigning a database path to the
719       TZDIR environment variable.
720

EXIT STATUS

722       One of the following exit values will be returned:
723
724       EXIT_SUCCESS ('0' on POSIX systems)
725              Successful program execution.
726
727       EXIT_FAILURE ('1' on POSIX systems)
728              The operation failed or the command syntax was not valid.
729

ENVIRONMENT

731       TZ     If this variable is set its value takes precedence over the sys‐
732              tem configured timezone.
733
734       TZDIR  If this variable is set its value takes precedence over the sys‐
735              tem configured timezone database directory path.
736

FILES

738       /etc/adjtime
739              The configuration and state file for hwclock.
740
741       /etc/localtime
742              The system timezone file.
743
744       /usr/share/zoneinfo/
745              The system timezone database directory.
746
747       Device files hwclock may try for Hardware Clock access:
748       /dev/rtc0
749       /dev/rtc
750       /dev/misc/rtc
751       /dev/efirtc
752       /dev/misc/efirtc
753

SEE ALSO

755       date(1),  adjtimex(8),  gettimeofday(2),  settimeofday(2),  crontab(1),
756       tzset(3)
757

AUTHORS

759       Written  by  Bryan Henderson, September 1996 (bryanh@giraffe-data.com),
760       based on work done on the clock(8)  program  by  Charles  Hedrick,  Rob
761       Hooft, and Harald Koenig.  See the source code for complete history and
762       credits.
763

AVAILABILITY

765       The hwclock command is part of the util-linux package and is  available
766       from https://www.kernel.org/pub/linux/utils/util-linux/.
767
768
769
770util-linux                         July 2017                        HWCLOCK(8)
Impressum