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       --delay=seconds
215              This option allows to overwrite internally used delay  when  set
216              clock time. The default is 0.5 (500ms) for rtc_cmos, for another
217              RTC types the delay is 0. If RTC type is impossible to determine
218              (from  sysfs) then it defaults also to 0.5 to be backwardly com‐
219              patible.
220
221              The 500ms default is based on commonly used MC146818A-compatible
222              (x86) hardware clock. This Hardware Clock can only be set to any
223              integer time plus one half second.  The integer time is required
224              because there is no interface to set or get a fractional second.
225              The additional half second delay is because the  Hardware  Clock
226              updates  to  the following second precisely 500 ms after setting
227              the new time. Unfortunately, this behavior is hardware  specific
228              and in same cases another delay is required.
229
230
231       -D, --debug
232              Use --verbose.   The --debug option  has  been deprecated
233              and may be repurposed or removed in a future release.
234
235       --directisa
236              This option is meaningful for ISA compatible machines  in
237              the x86 and x86_64 family.  For other machines, it has no
238              effect.  This option tells hwclock to  use  explicit  I/O
239              instructions  to access the Hardware Clock.  Without this
240              option, hwclock will use the rtc device  file,  which  it
241              assumes  to be driven by the Linux RTC device driver.  As
242              of v2.26 it will no longer  automatically  use  directisa
243              when  the  rtc driver is unavailable; this was causing an
244              unsafe condition that could allow two processes to access
245              the  Hardware  Clock  at  the same time.  Direct hardware
246              access from userspace should only be  used  for  testing,
247              troubleshooting,  and  as  a  last  resort when all other
248              methods fail.  See the --rtc option.
249
250       --epoch=year
251              This    option    is    required    when    using     the
252              --setepoch function.  The minimum year value is 1900. The
253              maximum is system dependent (ULONG_MAX - 1).
254
255       -f, --rtc=filename
256              Override hwclock's default rtc device file name.   Other‐
257              wise it will use the first one found in this order:
258                  /dev/rtc0
259                  /dev/rtc
260                  /dev/misc/rtc
261              For IA-64:
262                  /dev/efirtc
263                  /dev/misc/efirtc
264
265       -l, --localtime
266       -u, --utc
267              Indicate which timescale the Hardware Clock is set to.
268
269              The  Hardware  Clock  may be configured to use either the
270              UTC or the local timescale,  but  nothing  in  the  clock
271              itself   says  which  alternative  is  being  used.   The
272              --localtime or --utc options give this information to the
273              hwclock  command.  If you specify the wrong one (or spec‐
274              ify neither and take a wrong default), both  setting  and
275              reading the Hardware Clock will be incorrect.
276
277              If you specify neither --utc nor --localtime then the one
278              last given with a  set  function  (--set,  --systohc,  or
279              --adjust), as recorded in /etc/adjtime, will be used.  If
280              the adjtime file doesn't exist, the default is UTC.
281
282              Note: daylight saving time changes  may  be  inconsistent
283              when  the  Hardware Clock is kept in local time.  See the
284              discussion below, under LOCAL vs UTC.
285
286       --noadjfile
287              Disable the facilities provided by /etc/adjtime.  hwclock
288              will  not  read  nor write to that file with this option.
289              Either --utc or --localtime must be specified when  using
290              this option.
291
292       --test Do  not  actually change anything on the system, that is,
293              the Clocks or /etc/adjtime (--verbose  is  implicit  with
294              this option).
295
296       --update-drift
297              Update the Hardware Clock's drift factor in /etc/adjtime.
298              It can only be used with --set or --systohc,
299
300              A minimum four hour period between settings is  required.
301              This  is  to  avoid invalid calculations.  The longer the
302              period, the more precise the resulting drift factor  will
303              be.
304
305              This option was added in v2.26, because it is typical for
306              systems to call hwclock --systohc at shutdown;  with  the
307              old  behaviour this would automatically (re)calculate the
308              drift factor which caused several problems:
309
310              · When using NTP  with  an  '11 minute mode'  kernel  the
311                drift factor would be clobbered to near zero.
312
313              · It  would not allow the use of 'cold' drift correction.
314                With most configurations using 'cold' drift will  yield
315                favorable  results.   Cold,  means  when the machine is
316                turned off which can have a significant impact  on  the
317                drift factor.
318
319              · (Re)calculating drift factor on every shutdown delivers
320                suboptimal results.  For example, if  ephemeral  condi‐
321                tions  cause the machine to be abnormally hot the drift
322                factor calculation would be out of range.
323
324              · Significantly increased system shutdown  times  (as  of
325                v2.31  when  not  using  --update-drift  the RTC is not
326                read).
327
328              Having hwclock calculate  the  drift  factor  is  a  good
329              starting  point,  but  for optimal results it will likely
330              need to be adjusted by directly editing the  /etc/adjtime
331              file.   For  most configurations once a machine's optimal
332              drift factor is crafted it should not need to be changed.
333              Therefore,  the  old behavior to automatically (re)calcu‐
334              late drift was changed and now requires this option to be
335              used.   See  the discussion below, under The Adjust Func‐
336              tion.
337
338              This option requires reading the  Hardware  Clock  before
339              setting  it.  If it cannot be read, then this option will
340              cause the set functions to fail.  This  can  happen,  for
341              example,  if  the  Hardware Clock is corrupted by a power
342              failure.  In that case, the clock must first be set with‐
343              out  this  option.  Despite it not working, the resulting
344              drift correction factor would be invalid anyway.
345
346       -v, --verbose
347              Display more details about what hwclock is  doing  inter‐
348              nally.
349

NOTES

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

DATE-TIME CONFIGURATION

595   Keeping Time without External Synchronization
596       This discussion is based on the following conditions:
597
598       · Nothing is running that alters the date-time clocks,  such  as
599         NTP daemon or a cron job."
600
601       · The  system timezone is configured for the correct local time.
602         See below, under POSIX vs 'RIGHT'.
603
604       · Early during startup the following are called, in this order:
605         adjtimex --tick value --frequency value
606         hwclock --hctosys
607
608       · During shutdown the following is called:
609         hwclock --systohc
610
611           * Systems without adjtimex may use ntptime.
612
613       Whether maintaining precision time with NTP daemon  or  not,  it
614       makes  sense  to  configure  the  system to keep reasonably good
615       date-time on its own.
616
617       The first step in making that happen is having  a  clear  under‐
618       standing  of the big picture.  There are two completely separate
619       hardware devices running at their own speed  and  drifting  away
620       from  the  'correct'  time  at their own rates.  The methods and
621       software for drift correction are different for  each  of  them.
622       However,  most systems are configured to exchange values between
623       these two clocks at startup and shutdown.   Now  the  individual
624       device's  time  keeping  errors  are  transferred back and forth
625       between each other.  Attempt to configure drift  correction  for
626       only  one  of  them, and the other's drift will be overlaid upon
627       it.
628
629       This problem can be avoided when  configuring  drift  correction
630       for  the  System  Clock by simply not shutting down the machine.
631       This, plus the fact that all of hwclock's  precision  (including
632       calculating  drift factors) depends upon the System Clock's rate
633       being correct, means that  configuration  of  the  System  Clock
634       should be done first.
635
636       The  System  Clock  drift is corrected with the adjtimex(8) com‐
637       mand's --tick and --frequency options.  These two work together:
638       tick  is the coarse adjustment and frequency is the fine adjust‐
639       ment.  (For systems  that  do  not  have  an  adjtimex  package,
640       ntptime -f ppm may be used instead.)
641
642       Some  Linux distributions attempt to automatically calculate the
643       System Clock drift with adjtimex's compare operation.  Trying to
644       correct  one drifting clock by using another drifting clock as a
645       reference is akin to a dog trying to catch its own  tail.   Suc‐
646       cess  may  happen  eventually,  but great effort and frustration
647       will likely precede it.  This automation may yield  an  improve‐
648       ment  over no configuration, but expecting optimum results would
649       be in error.  A better choice for manual configuration would  be
650       adjtimex's --log options.
651
652       It  may be more effective to simply track the System Clock drift
653       with sntp, or date -Ins and a precision timepiece, and then cal‐
654       culate the correction manually.
655
656       After  setting  the  tick and frequency values, continue to test
657       and refine the adjustments until the  System  Clock  keeps  good
658       time.   See  adjtimex(2)  for  more  information and the example
659       demonstrating manual drift calculations.
660
661       Once the System Clock is ticking smoothly, move on to the  Hard‐
662       ware Clock.
663
664       As  a  rule, cold drift will work best for most use cases.  This
665       should be true even for 24/7 machines whose normal downtime con‐
666       sists  of  a  reboot.  In that case the drift factor value makes
667       little difference.  But on the rare occasion that the machine is
668       shut  down  for an extended period, then cold drift should yield
669       better results.
670
671       Steps to calculate cold drift:
672
673       1 Ensure that NTP daemon will not be launched at startup.
674
675       2 The System Clock time must be correct at shutdown!
676
677       3 Shut down the system.
678
679       4 Let an extended period  pass  without  changing  the  Hardware
680         Clock.
681
682       5 Start the system.
683
684       6 Immediately  use  hwclock  to set the correct time, adding the
685         --update-drift option.
686
687       Note: if step 6 uses --systohc, then the System  Clock  must  be
688       set correctly (step 6a) just before doing so.
689
690       Having  hwclock  calculate  the  drift factor is a good starting
691       point, but for  optimal  results  it  will  likely  need  to  be
692       adjusted by directly editing the /etc/adjtime file.  Continue to
693       test and refine the drift factor until  the  Hardware  Clock  is
694       corrected  properly  at startup.  To check this, first make sure
695       that the System Time is correct before  shutdown  and  then  use
696       sntp,  or date -Ins and a precision timepiece, immediately after
697       startup.
698
699   LOCAL vs UTC
700       Keeping the Hardware Clock in a local timescale causes inconsis‐
701       tent daylight saving time results:
702
703       · If  Linux is running during a daylight saving time change, the
704         time written to the Hardware Clock will be  adjusted  for  the
705         change.
706
707       · If  Linux is NOT running during a daylight saving time change,
708         the time read from the Hardware Clock will NOT be adjusted for
709         the change.
710
711       The Hardware Clock on an ISA compatible system keeps only a date
712       and time, it has no concept of  timezone  nor  daylight  saving.
713       Therefore,  when  hwclock  is  told that it is in local time, it
714       assumes it is in the 'correct' local time and makes  no  adjust‐
715       ments to the time read from it.
716
717       Linux  handles  daylight  saving time changes transparently only
718       when the Hardware Clock is kept in the UTC timescale.  Doing  so
719       is  made  easy  for  system administrators as hwclock uses local
720       time for its output and as the argument to the --date option.
721
722       POSIX systems, like Linux, are designed to have the System Clock
723       operate in the UTC timescale. The Hardware Clock's purpose is to
724       initialize the System Clock, so also keeping  it  in  UTC  makes
725       sense.
726
727       Linux  does,  however, attempt to accommodate the Hardware Clock
728       being in the local timescale. This is primarily for dual-booting
729       with  older versions of MS Windows. From Windows 7 on, the Real‐
730       TimeIsUniversal registry key is supposed to be working  properly
731       so that its Hardware Clock can be kept in UTC.
732
733   POSIX vs 'RIGHT'
734       A  discussion  on  date-time  configuration  would be incomplete
735       without addressing timezones, this is  mostly  well  covered  by
736       tzset(3).   One  area that seems to have no documentation is the
737       'right' directory of the Time Zone Database, sometimes called tz
738       or zoneinfo.
739
740       There  are  two separate databases in the zoneinfo system, posix
741       and 'right'. 'Right' (now named  zoneinfo-leaps)  includes  leap
742       seconds and posix does not. To use the 'right' database the Sys‐
743       tem Clock must be set to (UTC + leap seconds), which is  equiva‐
744       lent  to (TAI - 10). This allows calculating the exact number of
745       seconds between two dates that cross a leap  second  epoch.  The
746       System  Clock  is  then  converted  to  the  correct civil time,
747       including UTC, by using the 'right' timezone  files  which  sub‐
748       tract  the  leap seconds. Note: this configuration is considered
749       experimental and is known to have issues.
750
751       To configure a system to use a particular database  all  of  the
752       files  located  in  its  directory must be copied to the root of
753       /usr/share/zoneinfo.  Files are never  used  directly  from  the
754       posix or 'right' subdirectories, e.g., TZ='right/Europe/Dublin'.
755       This habit was becoming so common  that  the  upstream  zoneinfo
756       project  restructured the system's file tree by moving the posix
757       and 'right' subdirectories out of  the  zoneinfo  directory  and
758       into sibling directories:
759
760         /usr/share/zoneinfo
761         /usr/share/zoneinfo-posix
762         /usr/share/zoneinfo-leaps
763
764       Unfortunately,  some Linux distributions are changing it back to
765       the old tree structure in their packages. So the problem of sys‐
766       tem  administrators  reaching into the 'right' subdirectory per‐
767       sists. This causes the  system  timezone  to  be  configured  to
768       include  leap  seconds while the zoneinfo database is still con‐
769       figured to exclude them. Then when  an  application  such  as  a
770       World Clock needs the South_Pole timezone file; or an email MTA,
771       or hwclock needs the UTC timezone file; they fetch it  from  the
772       root of /usr/share/zoneinfo , because that is what they are sup‐
773       posed to do. Those files exclude leap seconds,  but  the  System
774       Clock now includes them, causing an incorrect time conversion.
775
776       Attempting  to mix and match files from these separate databases
777       will not work, because they each require the System Clock to use
778       a  different timescale. The zoneinfo database must be configured
779       to use either posix  or  'right',  as  described  above,  or  by
780       assigning a database path to the TZDIR environment variable.
781

EXIT STATUS

783       One of the following exit values will be returned:
784
785       EXIT_SUCCESS ('0' on POSIX systems)
786              Successful program execution.
787
788       EXIT_FAILURE ('1' on POSIX systems)
789              The operation failed or the command syntax was not valid.
790

ENVIRONMENT

792       TZ     If  this  variable is set its value takes precedence over
793              the system configured timezone.
794
795       TZDIR  If this variable is set its value takes  precedence  over
796              the system configured timezone database directory path.
797

FILES

799       /etc/adjtime
800              The configuration and state file for hwclock.
801
802       /etc/localtime
803              The system timezone file.
804
805       /usr/share/zoneinfo/
806              The system timezone database directory.
807
808       Device files hwclock may try for Hardware Clock access:
809       /dev/rtc0
810       /dev/rtc
811       /dev/misc/rtc
812       /dev/efirtc
813       /dev/misc/efirtc
814

SEE ALSO

816       date(1),    adjtimex(8),    gettimeofday(2),    settimeofday(2),
817       crontab(1p), tzset(3)
818

AUTHORS

820       Written by  Bryan  Henderson,  September  1996  (bryanh@giraffe-
821       data.com), based on work done on the clock(8) program by Charles
822       Hedrick, Rob Hooft, and Harald Koenig.  See the source code  for
823       complete history and credits.
824

AVAILABILITY

826       The  hwclock  command  is  part of the util-linux package and is
827       available   from    https://www.kernel.org/pub/linux/utils/util-
828       linux/.
829
830
831
832util-linux                         July 2017                        HWCLOCK(8)
Impressum