hwclock - read or set the hardware clock (RTC)


   hwclock [function] [option...]


   hwclock  is  a  tool for accessing the Hardware Clock.  It can: display
   the Hardware Clock time; set the Hardware Clock to  a  specified  time;
   set the Hardware Clock from the System Clock; set the System Clock from
   the Hardware Clock; compensate for Hardware Clock  drift;  correct  the
   System  Clock  timescale; set the kernel's timezone, NTP timescale, and
   epoch (Alpha only); compare the System and Hardware Clocks; and predict
   future Hardware Clock values based on its drift rate.

   Since  v2.26  important changes were made to the --hctosys function and
   the --directisa option, and a new option --update-drift was added.  See
   their respective descriptions below.


   The  following  functions are mutually exclusive, only one can be given
   at a time.  If none is given, the default is --show.

          Add or subtract time from the  Hardware  Clock  to  account  for
          systematic  drift  since  the  last  time  the  clock was set or
          adjusted.  See the discussion below, under The Adjust Function.

   -c, --compare
          Periodically compare the Hardware Clock to the System  Time  and
          output  the  difference  every 10 seconds.  This will also print
          the frequency offset and tick.

          These functions are for Alpha machines only.

          Read and set the kernel's Hardware Clock epoch value.  Epoch  is
          the  number  of  years into AD to which a zero year value in the
          Hardware Clock refers.   For  example,  if  you  are  using  the
          convention that the year counter in your Hardware Clock contains
          the number of full years since 1952, then the kernel's  Hardware
          Clock epoch value must be 1952.

          The  --setepoch  function  requires  using the --epoch option to
          specify the year.

          This epoch value is used whenever  hwclock  reads  or  sets  the
          Hardware Clock.

          Predict  what  the  Hardware Clock will read in the future based
          upon the time given by the --date option and the information  in
          /etc/adjtime.  This is useful, for example, to account for drift
          when  setting  a  Hardware  Clock  wakeup   (aka   alarm).   See

          Do not use this function if the Hardware Clock is being modified
          by anything other than the current  operating  system's  hwclock
          command,  such  as '11 minute mode' or from dual-booting another

   -r, --show
          Read the Hardware Clock and print its time to standard output in
          the  ISO  8601  format.  The time shown is always in local time,
          even  if  you  keep  your  Hardware  Clock  in  UTC.   See   the
          --localtime option.

          Showing  the Hardware Clock time is the default when no function
          is specified.

          The --get function also applies drift  correction  to  the  time
          read,  based  upon  the information in /etc/adjtime.  Do not use
          this function  if  the  Hardware  Clock  is  being  modified  by
          anything  other  than  the  current  operating  system's hwclock
          command, such as '11 minute mode' or from  dual-booting  another

   -s, --hctosys
          Set  the  System  Clock  from the Hardware Clock.  The time read
          from the Hardware Clock is compensated to account for systematic
          drift  before  using  it  to  set  the  System  Clock.   See the
          discussion below, under The Adjust Function.

          The System Clock must be kept in the UTC timescale for date-time
          applications  to work correctly in conjunction with the timezone
          configured for the system.  If the Hardware  Clock  is  kept  in
          local time then the time read from it must be shifted to the UTC
          timescale  before  using  it  to  set  the  System  Clock.   The
          --hctosys  function  does this based upon the information in the
          /etc/adjtime file or the command line arguments --localtime  and
          --utc.   Note:  no  daylight saving adjustment is made.  See the
          discussion below, under LOCAL vs UTC.

          The kernel also keeps a timezone value, the  --hctosys  function
          sets  it  to the timezone configured for the system.  The system
          timezone is configured by the TZ  environment  variable  or  the
          /etc/localtime  file,  as  tzset(3)  would  interpret them.  The
          obsolete tz_dsttime field of the kernel's timezone value is  set
          to  zero.   (For  details  on  what this field used to mean, see

          When used in a startup script, making the --hctosys function the
          first  caller  of settimeofday(2) from boot, it will set the NTP
          '11 minute mode'  timescale  via  the  persistent_clock_is_local
          kernel    variable.    If   the   Hardware   Clock's   timescale
          configuration is changed then a reboot is required to inform the
          kernel.   See  the  discussion  below,  under Automatic Hardware
          Clock Synchronization by the Kernel.

          This is a good function to use in  one  of  the  system  startup
          scripts before the file systems are mounted read/write.

          This  function should never be used on a running system. Jumping
          system time will cause problems, such  as  corrupted  filesystem
          timestamps.   Also, if something has changed the Hardware Clock,
          like NTP's '11 minute mode', then --hctosys will  set  the  time
          incorrectly by including drift compensation.

          Drift  compensation can be inhibited by setting the drift factor
          in /etc/adjtime to zero.  This setting  will  be  persistent  as
          long  as the --update-drift option is not used with --systohc at
          shutdown (or anywhere else).  Another way to inhibit this is  by
          using   the   --noadjfile  option  when  calling  the  --hctosys
          function.  A third method is to delete  the  /etc/adjtime  file.
          Hwclock  will  then  default  to using the UTC timescale for the
          Hardware Clock.  If the Hardware Clock is ticking local time  it
          will  need  to  be  defined  in  the  file.  This can be done by
          calling  hwclock --localtime --adjust;  when  the  file  is  not
          present  this command will not actually adjust the Clock, but it
          will create the file with local time  configured,  and  a  drift
          factor of zero.

          A  condition  under  which inhibiting hwclock's drift correction
          may be desired is when dual-booting multiple operating  systems.
          If  while  this instance of Linux is stopped, another OS changes
          the Hardware Clock's value, then when this instance  is  started
          again the drift correction applied will be incorrect.

          For hwclock's drift correction to work properly it is imperative
          that nothing changes the Hardware Clock while its Linux instance
          is not running.

   --set  Set  the  Hardware Clock to the time given by the --date option,
          and update the timestamps in /etc/adjtime.  With  the  --update-
          drift option (re)calculate the drift factor.

          This  is  an  alternate  to the --hctosys function that does not
          read the Hardware Clock nor set the System  Clock;  consequently
          there is not any drift correction.  It is intended to be used in
          a startup script on systems with kernels above version 2.6 where
          you  know  the System Clock has been set from the Hardware Clock
          by the kernel during boot.

          It does the following things that  are  detailed  above  in  the
          --hctosys function:

          * Corrects  the  System  Clock timescale to UTC as needed.  Only
            instead of accomplishing this by  setting  the  System  Clock,
            hwclock simply informs the kernel and it handles the change.

          * Sets the kernel's NTP '11 minute mode' timescale.

          * Sets the kernel's timezone.

          The   first  two  are  only  available  on  the  first  call  of
          settimeofday(2) after boot.  Consequently this option only makes
          sense  when  used  in  a startup script.  If the Hardware Clocks
          timescale configuration  is  changed  then  a  reboot  would  be
          required to inform the kernel.

   -w, --systohc
          Set  the  Hardware  Clock  from the System Clock, and update the
          timestamps in /etc/adjtime.  When the --update-drift  option  is
          given, then also (re)calculate the drift factor.

   -V, --version
          Display version information and exit.

   -h, --help
          Display help text and exit.


          Override the default /etc/adjtime file path.

          Indicate  that  the Hardware Clock is incapable of storing years
          outside the range 1994-1999.  There is a problem in some  BIOSes
          (almost  all  Award  BIOSes  made  between  4/26/94 and 5/31/95)
          wherein they are unable to deal with years after 1999.   If  one
          attempts to set the year-of-century value to something less than
          94 (or 95 in some cases), the value that actually gets set is 94
          (or  95).   Thus,  if  you  have  one of these machines, hwclock
          cannot set the year after 1999 and cannot use the value  of  the
          clock as the true time in the normal way.

          To  compensate  for  this  (without  your getting a BIOS update,
          which would definitely be preferable), always use  --badyear  if
          you have one of these machines.  When hwclock knows it's working
          with a brain-damaged clock, it ignores  the  year  part  of  the
          Hardware  Clock  value and instead tries to guess the year based
          on the last calibrated date in the  adjtime  file,  by  assuming
          that  date  is  within the past year.  For this to work, you had
          better do a hwclock --set or hwclock --systohc at least  once  a

          Though hwclock ignores the year value when it reads the Hardware
          Clock, it sets the year value when it sets the clock.   It  sets
          it  to  1995,  1996,  1997,  or 1998, whichever one has the same
          position in the leap year cycle as the true year.  That way, the
          Hardware  Clock  inserts leap days where they belong.  Again, if
          you let the Hardware Clock run for  more  than  a  year  without
          setting  it,  this scheme could be defeated and you could end up
          losing a day.

          You need this option if  you  specify  the  --set  or  --predict
          functions,  otherwise  it  is ignored.  It specifies the time to
          which to set the Hardware  Clock,  or  the  time  for  which  to
          predict the Hardware Clock reading.  The value of this option is
          used as an argument to the date(1) program's --date option.  For

              hwclock --set --date='2011-08-14 16:45:05'

          The  argument  must  be  in  local  time,  even if you keep your
          Hardware  Clock  in  UTC.   See  the  --localtime  option.   The
          argument  must not be a relative time like "+5 minutes", because
          hwclock's  precision  depends  upon  correlation   between   the
          argument's value and when the enter key is pressed.

   -D, --debug
          Display  a  lot  of  information  about  what  hwclock  is doing
          internally.  Some of its functions are complex and  this  output
          can help you understand how the program works.

          This option is meaningful for: ISA compatible machines including
          x86, and x86_64; and Alpha (which has a similar  Hardware  Clock
          interface).   For other machines, it has no effect.  This option
          tells hwclock to use explicit I/O  instructions  to  access  the
          Hardware  Clock.   Without this option, hwclock will use the rtc
          device, which it assumes to be driven by the RTC device  driver.
          As  of  v2.26 it will no longer automatically use directisa when
          the rtc driver  is  unavailable;  this  was  causing  an  unsafe
          condition  that could allow two processes to access the Hardware
          Clock at the same time.  Direct hardware access  from  userspace
          should  only be used for testing, troubleshooting, and as a last
          resort when all other methods fail.  See the --rtc option.

   -f, --rtc=filename
          Override hwclock's default rtc device file name.   Otherwise  it
          will use the first one found in this order:
          For IA-64:

   -u, --utc
          Indicate which timescale the Hardware Clock is set to.

          The  Hardware  Clock  may be configured to use either the UTC or
          the local timescale, but nothing in the clock itself says  which
          alternative  is  being  used.   The --localtime or --utc options
          give this information to the hwclock command.   If  you  specify
          the  wrong  one  (or  specify neither and take a wrong default),
          both setting and reading the Hardware Clock will be incorrect.

          If you specify neither --utc nor --localtime then the  one  last
          given  with  a  set function (--set, --systohc, or --adjust), as
          recorded in /etc/adjtime, will be used.   If  the  adjtime  file
          doesn't exist, the default is UTC.

          Note:  daylight saving time changes may be inconsistent when the
          Hardware Clock is kept in local time.  See the discussion below,
          under LOCAL vs UTC.

          Disable  the  facilities provided by /etc/adjtime.  hwclock will
          not read nor write to that file with this option.  Either  --utc
          or --localtime must be specified when using this option.

   --test Do  not actually change anything on the system, i.e., the Clocks
          or adjtime file.  This is useful, especially in conjunction with
          --debug, in learning about the internal operations of hwclock.

          Update the Hardware Clock's drift factor in /etc/adjtime.  It is
          used with --set or --systohc, otherwise it is ignored.

          A minimum four hour period between settings is  required.   This
          is  to  avoid  invalid calculations.  The longer the period, the
          more precise the resulting drift factor will be.

          This option was added  in  v2.26,  because  it  is  typical  for
          systems  to  call  hwclock --systohc  at  shutdown; with the old
          behaviour  this  would  automatically  (re)calculate  the  drift
          factor which caused several problems:

          * When  using  ntpd  with  an  '11 minute mode' kernel the drift
            factor would be clobbered to near zero.

          * It would not allow the use of 'cold' drift  correction.   With
            most  configurations  using  'cold' drift will yield favorable
            results.  Cold, means when the machine is turned off which can
            have a significant impact on the drift factor.

          * (Re)calculating   drift  factor  on  every  shutdown  delivers
            suboptimal results.   For  example,  if  ephemeral  conditions
            cause  the  machine  to  be  abnormally  hot  the drift factor
            calculation would be out of range.

          Having hwclock calculate the drift factor  is  a  good  starting
          point,  but  for  optimal  results  it  will  likely  need to be
          adjusted by directly editing the /etc/adjtime  file.   For  most
          configurations  once a machine's optimal drift factor is crafted
          it should not need to be changed.  Therefore, the  old  behavior
          to   automatically  (re)calculate  drift  was  changed  and  now
          requires this option to be  used.   See  the  discussion  below,
          under The Adjust Function.


   --arc  This option is equivalent to --epoch=1980 and is used to specify
          the most common epoch on Alphas with an  ARC  console  (although
          Ruffians have an epoch of 1900).

          Specifies  the  year  which  is  the  beginning  of the Hardware
          Clock's epoch, that is the number of years into AD  to  which  a
          zero  value  in the Hardware Clock's year counter refers.  It is
          used together with the --setepoch option  to  set  the  kernel's
          idea of the epoch of the Hardware Clock.

          For example, on a Digital Unix machine:

              hwclock --setepoch --epoch=1952

          These  two  options specify what kind of Alpha machine you have.
          They are invalid if you do not have an  Alpha  and  are  usually
          unnecessary  if you do; hwclock should be able to determine what
          it is running on when /proc is mounted.

          The --jensen option is used for Jensen models; --funky-toy means
          that  the  machine requires the UF bit instead of the UIP bit in
          the Hardware Clock to detect a time transition.   The  "toy"  in
          the  option  name  refers  to  the  Time Of Year facility of the

   --srm  This option is equivalent to --epoch=1900 and is used to specify
          the most common epoch on Alphas with an SRM console.


   Clocks in a Linux System
   There are two types of date-time clocks:

   The  Hardware Clock: This clock is an independent hardware device, with
   its own power domain (battery, capacitor, etc), that operates when  the
   machine is powered off, or even unplugged.

   On an ISA compatible system, this clock is specified as part of the ISA
   standard.  A control program can read or set this clock only to a whole
   second,  but  it can also detect the edges of the 1 second clock ticks,
   so the clock actually has virtually infinite precision.

   This clock is commonly called the hardware clock, the real time  clock,
   the  RTC,  the  BIOS clock, and the CMOS clock.  Hardware Clock, in its
   capitalized form, was coined for use by hwclock.  The Linux kernel also
   refers to it as the persistent clock.

   Some  non-ISA systems have a few real time clocks with only one of them
   having its own power domain.  A very low  power  external  I2C  or  SPI
   clock chip might be used with a backup battery as the hardware clock to
   initialize a more functional integrated real-time clock which  is  used
   for most other purposes.

   The  System Clock: This clock is part of the Linux kernel and is driven
   by a timer interrupt.  (On an ISA machine, the timer interrupt is  part
   of  the  ISA  standard.)  It has meaning only while Linux is running on
   the machine.  The System Time is the number of seconds  since  00:00:00
   January  1,  1970  UTC (or more succinctly, the number of seconds since
   1969 UTC).  The  System  Time  is  not  an  integer,  though.   It  has
   virtually infinite precision.

   The  System  Time is the time that matters.  The Hardware Clock's basic
   purpose is to keep time when Linux is not running so  that  the  System
   Clock  can be initialized from it at boot.  Note that in DOS, for which
   ISA was designed, the Hardware Clock is the only real time clock.

   It is important that the System Time not have any discontinuities  such
   as  would  happen  if  you used the date(1) program to set it while the
   system is running.  You can, however,  do  whatever  you  want  to  the
   Hardware  Clock  while  the  system is running, and the next time Linux
   starts up, it will do so with  the  adjusted  time  from  the  Hardware
   Clock.   Note:  currently  this is not possible on most systems because
   hwclock --systohc is called at shutdown.

   The Linux kernel's timezone is set by hwclock.  But don't be misled  --
   almost nobody cares what timezone the kernel thinks it is in.  Instead,
   programs that care about the timezone (perhaps  because  they  want  to
   display  a  local  time  for  you) almost always use a more traditional
   method of  determining  the  timezone:  They  use  the  TZ  environment
   variable  or  the /etc/localtime file, as explained in the man page for
   tzset(3).  However, some programs and fringe parts of the Linux  kernel
   such as filesystems use the kernel's timezone value.  An example is the
   vfat filesystem.  If the kernel  timezone  value  is  wrong,  the  vfat
   filesystem  will report and set the wrong timestamps on files.  Another
   example is the kernel's NTP '11 minute mode'.  If the kernel's timezone
   value and/or the persistent_clock_is_local variable are wrong, then the
   Hardware Clock will be set incorrectly by  '11 minute mode'.   See  the
   discussion below, under Automatic Hardware Clock Synchronization by the

   hwclock sets the kernel's timezone to the  value  indicated  by  TZ  or
   /etc/localtime with the --hctosys or --systz functions.

   The  kernel's timezone value actually consists of two parts: 1) a field
   tz_minuteswest indicating how many minutes local time (not adjusted for
   DST)  lags behind UTC, and 2) a field tz_dsttime indicating the type of
   Daylight Savings Time  (DST)  convention  that  is  in  effect  in  the
   locality  at  the  present  time.   This second field is not used under
   Linux and is always zero.  See also settimeofday(2).

   Hardware Clock Access Methods
   hwclock uses many different ways to get and set Hardware Clock  values.
   The  most normal way is to do I/O to the rtc device special file, which
   is presumed to be driven by the rtc device driver.  Also, Linux systems
   using  the  rtc framework with udev, are capable of supporting multiple
   Hardware Clocks.  This may bring about the need to override the default
   rtc device by specifying one with the --rtc option.

   However,  this  method  is not always available as older systems do not
   have an rtc driver.  On these systems,  the  method  of  accessing  the
   Hardware Clock depends on the system hardware.

   On  an  ISA  compatible  system,  hwclock can directly access the "CMOS
   memory" registers that constitute the clock, by doing I/O to Ports 0x70
   and  0x71.   It does this with actual I/O instructions and consequently
   can only do it if running with superuser effective userid.  This method
   may be used by specifying the --directisa option.

   This  is  a  really  poor  method  of  accessing the clock, for all the
   reasons that userspace programs are generally not supposed to do direct
   I/O   and   disable  interrupts.   hwclock  provides  it  for  testing,
   troubleshooting, and  because it may be the only  method  available  on
   ISA compatible and Alpha systems which do not have a working rtc device

   In the case of a Jensen Alpha, there is no way for hwclock  to  execute
   those  I/O  instructions,  and  so it uses instead the /dev/port device
   special file, which provides almost as low-level an  interface  to  the
   I/O subsystem.

   On  an  m68k  system,  hwclock  can  access  the clock with the console
   driver, via the device special file /dev/tty1.

   The Adjust Function
   The Hardware Clock is usually not very accurate.  However, much of  its
   inaccuracy  is  completely  predictable  -  it  gains or loses the same
   amount of time every day.  This is called systematic drift.   hwclock's
   --adjust  function  lets  you apply systematic drift corrections to the
   Hardware Clock.

   It works like this: hwclock keeps a file, /etc/adjtime, that keeps some
   historical information.  This is called the adjtime file.

   Suppose  you  start  with  no  adjtime file.  You issue a hwclock --set
   command to set the Hardware Clock to the true  current  time.   hwclock
   creates the adjtime file and records in it the current time as the last
   time the clock was calibrated.  Five days later, the clock  has  gained
   10  seconds, so you issue a hwclock --set --update-drift command to set
   it back 10 seconds.  hwclock updates  the  adjtime  file  to  show  the
   current  time  as the last time the clock was calibrated, and records 2
   seconds per day as the systematic drift rate.  24 hours go by, and then
   you  issue  a  hwclock --adjust  command.  hwclock consults the adjtime
   file and sees that the clock gains 2 seconds per day  when  left  alone
   and that it has been left alone for exactly one day.  So it subtracts 2
   seconds from the Hardware Clock.  It then records the current  time  as
   the  last  time the clock was adjusted.  Another 24 hours go by and you
   issue another hwclock --adjust.  hwclock does the same thing: subtracts
   2  seconds  and  updates  the adjtime file with the current time as the
   last time the clock was adjusted.

   When you use the --update-drift option with  --set  or  --systohc,  the
   systematic  drift  rate  is (re)calculated by comparing the fully drift
   corrected current Hardware Clock time with the new set time, from  that
   it  derives  the  24  hour  drift  rate  based  on  the last calibrated
   timestamp from the adjtime file.  This updated  drift  factor  is  then
   saved in /etc/adjtime.

   A  small  amount  of error creeps in when the Hardware Clock is set, so
   --adjust refrains from making  any  adjustment  that  is  less  than  1
   second.    Later   on,  when  you  request  an  adjustment  again,  the
   accumulated drift will be more than 1 second and --adjust will make the
   adjustment including any fractional amount.

   hwclock --hctosys  also  uses  the  adjtime file data to compensate the
   value read from the Hardware Clock before using it to  set  the  System
   Clock.  It does not share the 1 second limitation of --adjust, and will
   correct sub-second drift values immediately.  It does  not  change  the
   Hardware  Clock time nor the adjtime file.  This may eliminate the need
   to use --adjust, unless something else on the system needs the Hardware
   Clock to be compensated.

   The Adjtime File
   While named for its historical purpose of controlling adjustments only,
   it actually  contains  other  information  used  by  hwclock  from  one
   invocation to the next.

   The format of the adjtime file is, in ASCII:

   Line  1:  Three  numbers,  separated by blanks: 1) the systematic drift
   rate in seconds per day,  floating  point  decimal;  2)  the  resulting
   number  of  seconds  since  1969  UTC  of  most  recent  adjustment  or
   calibration, decimal integer; 3) zero (for compatibility with clock(8))
   as a decimal integer.

   Line  2:  One number: the resulting number of seconds since 1969 UTC of
   most recent calibration.  Zero if there has been no calibration yet  or
   it is known that any previous calibration is moot (for example, because
   the Hardware Clock has been  found,  since  that  calibration,  not  to
   contain a valid time).  This is a decimal integer.

   Line  3:  "UTC" or "LOCAL".  Tells whether the Hardware Clock is set to
   Coordinated Universal Time or local time.  You can always override this
   value with options on the hwclock command line.

   You  can use an adjtime file that was previously used with the clock(8)
   program with hwclock.

   Automatic Hardware Clock Synchronization by the Kernel
   You should be aware of another way that  the  Hardware  Clock  is  kept
   synchronized  in  some systems.  The Linux kernel has a mode wherein it
   copies the System Time to the Hardware Clock  every  11  minutes.  This
   mode  is  a  compile  time  option,  so  not all kernels will have this
   capability.  This is a good mode to use when you  are  using  something
   sophisticated  like NTP to keep your System Clock synchronized. (NTP is
   a way to keep your System Time synchronized either  to  a  time  server
   somewhere  on the network or to a radio clock hooked up to your system.
   See RFC 1305.)

   If the kernel is compiled with the '11 minute mode' option it  will  be
   active  when  the kernel's clock discipline is in a synchronized state.
   When in this state, bit 6 (the bit that is set in the mask  0x0040)  of
   the kernel's time_status variable is unset. This value is output as the
   'status' line of the adjtimex --print or ntptime commands.

   It takes an outside influence, like the NTP daemon ntpd(1), to put  the
   kernel's clock discipline into a synchronized state, and therefore turn
   on '11 minute mode'.  It can be turned off  by  running  anything  that
   sets    the   System   Clock   the   old   fashioned   way,   including
   hwclock --hctosys.  However, if the NTP daemon  is  still  running,  it
   will  turn '11 minute mode' back on again the next time it synchronizes
   the System Clock.

   If your system runs with '11 minute mode' on, it may need to use either
   --hctosys  or  --systz  in a startup script, especially if the Hardware
   Clock is configured to use the local timescale. Unless  the  kernel  is
   informed  of what timescale the Hardware Clock is using, it may clobber
   it with the wrong one. The kernel uses UTC by default.

   The first userspace command to set the System Clock informs the  kernel
   what  timescale  the  Hardware  Clock  is  using.  This happens via the
   persistent_clock_is_local kernel variable.  If --hctosys or --systz  is
   the  first,  it will set this variable according to the adjtime file or
   the appropriate command-line  argument.   Note  that  when  using  this
   capability  and  the Hardware Clock timescale configuration is changed,
   then a reboot is required to notify the kernel.

   hwclock --adjust should not be used with NTP '11 minute mode'.

   ISA Hardware Clock Century value
   There is some sort of standard that defines CMOS memory Byte 50  on  an
   ISA  machine  as  an indicator of what century it is.  hwclock does not
   use or set that byte because there are some machines that don't  define
   the  byte  that  way,  and  it really isn't necessary anyway, since the
   year-of-century does a good job of implying which century it is.

   If you have a bona fide use  for  a  CMOS  century  byte,  contact  the
   hwclock maintainer; an option may be appropriate.

   Note  that this section is only relevant when you are using the "direct
   ISA" method of accessing the Hardware Clock.  ACPI provides a  standard
   way to access century values, when they are supported by the hardware.


   Keeping Time without External Synchronization
   This discussion is based on the following conditions:

   * Nothing  is running that alters the date-time clocks, such as ntpd(1)
     or a cron job.

   * The system timezone is configured for the correct  local  time.   See
     below, under POSIX vs 'RIGHT'.

   * Early during startup the following are called, in this order:
     adjtimex --tick value --frequency value
     hwclock --hctosys

   * During shutdown the following is called:
     hwclock --systohc

       * Systems without adjtimex may use ntptime.

   Whether  maintaining precision time with ntpd(1) or not, it makes sense
   to configure the system to keep reasonably good date-time on its own.

   The first step in making that happen is having a clear understanding of
   the  big  picture.   There are two completely separate hardware devices
   running at their own speed and drifting away from the 'correct' time at
   their  own  rates.   The  methods and software for drift correction are
   different for each of them.  However, most systems  are  configured  to
   exchange  values between these two clocks at startup and shutdown.  Now
   the individual device's time keeping errors are  transferred  back  and
   forth  between  each  other.  Attempt to configure drift correction for
   only one of them, and the other's drift will be overlaid upon it.

   This problem can be avoided when configuring drift correction  for  the
   System  Clock  by simply not shutting down the machine.  This, plus the
   fact that all  of  hwclock's  precision  (including  calculating  drift
   factors) depends upon the System Clock's rate being correct, means that
   configuration of the System Clock should be done first.

   The System Clock drift is  corrected  with  the  adjtimex(8)  command's
   --tick  and  --frequency options.  These two work together: tick is the
   coarse adjustment and frequency is the fine adjustment.   (For  systems
   that  do  not  have  an  adjtimex  package,  ntptime -f ppm may be used

   Some Linux distributions attempt to automatically calculate the  System
   Clock  drift  with adjtimex's compare operation.  Trying to correct one
   drifting clock by using another drifting clock as a reference  is  akin
   to  a dog trying to catch its own tail.  Success may happen eventually,
   but  great  effort  and  frustration  will  likely  precede  it.   This
   automation   may  yield  an  improvement  over  no  configuration,  but
   expecting optimum results would be  in  error.   A  better  choice  for
   manual configuration would be adjtimex's --log options.

   It  may  be  more effective to simply track the System Clock drift with
   sntp, or date -Ins and a precision timepiece, and  then  calculate  the
   correction manually.

   After  setting  the  tick  and  frequency  values, continue to test and
   refine the adjustments until the System Clock  keeps  good  time.   See
   adjtimex(8)  for  more information and the example demonstrating manual
   drift calculations.

   Once the System Clock is ticking smoothly,  move  on  to  the  Hardware

   As  a  rule, cold drift will work best for most use cases.  This should
   be true even for 24/7 machines whose  normal  downtime  consists  of  a
   reboot.   In  that case the drift factor value makes little difference.
   But on the rare occasion that the machine is shut down for an  extended
   period, then cold drift should yield better results.

   Steps to calculate cold drift:

   1 Ensure that ntpd(1) will not be launched at startup.

   2 The System Clock time must be correct at shutdown!

   3 Shut down the system.

   4 Let an extended period pass without changing the Hardware Clock.

   5 Start the system.

   6 Immediately   use  hwclock  to  set  the  correct  time,  adding  the
     --update-drift option.

   Note: if step 6 uses --systohc, then  the  System  Clock  must  be  set
   correctly (step 6a) just before doing so.

   Having hwclock calculate the drift factor is a good starting point, but
   for optimal results it will likely need  to  be  adjusted  by  directly
   editing  the  /etc/adjtime file.  Continue to test and refine the drift
   factor until the Hardware Clock is corrected properly at  startup.   To
   check  this,  first  make  sure  that the System Time is correct before
   shutdown and then use sntp, or date -Ins  and  a  precision  timepiece,
   immediately after startup.

   Keeping  the  Hardware  Clock  in a local timescale causes inconsistent
   daylight saving time results:

   * If Linux is running during a daylight saving time  change,  the  time
     written to the Hardware Clock will be adjusted for the change.

   * If  Linux  is  NOT  running during a daylight saving time change, the
     time read from the Hardware  Clock  will  NOT  be  adjusted  for  the

   The  Hardware  Clock  on an ISA compatible system keeps only a date and
   time, it has no concept of timezone  nor  daylight  saving.  Therefore,
   when  hwclock is told that it is in local time, it assumes it is in the
   'correct' local time and makes no adjustments to the time read from it.

   Linux handles daylight saving time changes transparently only when  the
   Hardware  Clock is kept in the UTC timescale. Doing so is made easy for
   system administrators as hwclock uses local time for its output and  as
   the argument to the --date option.

   POSIX  systems,  like  Linux,  are  designed  to  have the System Clock
   operate in the UTC  timescale.  The  Hardware  Clock's  purpose  is  to
   initialize the System Clock, so also keeping it in UTC makes sense.

   Linux does, however, attempt to accommodate the Hardware Clock being in
   the local timescale. This is  primarily  for  dual-booting  with  older
   versions  of  MS  Windows.  From  Windows 7 on, the RealTimeIsUniversal
   registry key is supposed to be working properly so  that  its  Hardware
   Clock can be kept in UTC.

   A  discussion  on  date-time  configuration would be incomplete without
   addressing timezones, this is mostly well  covered  by  tzset(3).   One
   area  that  seems  to have no documentation is the 'right' directory of
   the Time Zone Database, sometimes called tz or zoneinfo.

   There are two separate databases in  the  zoneinfo  system,  posix  and
   'right'.  'Right'  (now named zoneinfo-leaps) includes leap seconds and
   posix does not. To use the 'right' database the System  Clock  must  be
   set  to  (UTC + leap  seconds), which is equivalent to (TAI - 10). This
   allows calculating the exact number of seconds between two  dates  that
   cross  a  leap  second epoch. The System Clock is then converted to the
   correct civil time, including UTC, by using the 'right' timezone  files
   which subtract the leap seconds. Note: this configuration is considered
   experimental and is known to have issues.

   To configure a system to use a particular database  all  of  the  files
   located   in   its   directory   must   be   copied   to  the  root  of
   /usr/share/zoneinfo.  Files are never used directly from the  posix  or
   'right' subdirectories, e.g., TZ='right/Europe/Dublin'.  This habit was
   becoming so common that the upstream zoneinfo project restructured  the
   system's  file  tree by moving the posix and 'right' subdirectories out
   of the zoneinfo directory and into sibling directories:


   Unfortunately, some Linux distributions are changing it back to the old
   tree   structure   in   their   packages.  So  the  problem  of  system
   administrators reaching into the 'right'  subdirectory  persists.  This
   causes  the  system  timezone  to be configured to include leap seconds
   while the zoneinfo database is still configured to exclude  them.  Then
   when an application such as a World Clock needs the South_Pole timezone
   file; or an email MTA, or hwclock needs the  UTC  timezone  file;  they
   fetch  it  from  the root of /usr/share/zoneinfo , because that is what
   they are supposed to do. Those files  exclude  leap  seconds,  but  the
   System Clock now includes them, causing an incorrect time conversion.

   Attempting  to  mix  and match files from these separate databases will
   not work, because they each require the System Clock to use a different
   timescale. The zoneinfo database must be configured to use either posix
   or 'right', as described above, or by assigning a database path to  the
   TZDIR environment variable.


   TZ     If  this  variable  is  set  its value takes precedence over the
          system configured timezone.

   TZDIR  If this variable is set its  value  takes  precedence  over  the
          system configured timezone database directory path.


          The configuration and state file for hwclock.

          The system timezone file.

          The system timezone database directory.

   Device files hwclock may try for Hardware Clock access:


   date(1),  adjtimex(8),  gettimeofday(2),  settimeofday(2),  crontab(1),


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


   The  hwclock command is part of the util-linux package and is available
   from ftp://ftp.kernel.org/pub/linux/utils/util-linux/.


Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.

Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.

Free Software

Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.

Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.

Free Books

The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.

Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.


Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.

Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.