CLOCK(8)                                                 CLOCK(8)

NAME
       clock - query and set the hardware clock (RTC)

SYNOPSIS
       hwclock --show
       hwclock --set --date=newdate
       hwclock --systohc
       hwclock --hctosys
       hwclock --getepoch
       hwclock --setepoch --epoch=year
       hwclock --adjust
       hwclock --version

       other options:

       --utc  --directisa --test --debug

       Minimum  unique  abbreviations  of all options are accept-
       able.

       Also, equivalent options -r, -w, -s, -a, -v,  -u,  and  -D
       are accepted for compatibility with the program "clock".

DESCRIPTION
       hwclock  is  a tool for accessing the Hardware Clock.  You
       can display the current time, set the Hardware Clock to  a
       specified time, set the Hardware Clock to the System Time,
       and set the System Time from the Hardware Clock.

       You can also run hwclock periodically to insert or  remove
       time  from the Hardware Clock to compensate for systematic
       drift (where the clock consistently gains or loses time at
       a certain rate if left to run).

OPTIONS
       You  need  exactly  one  of  the following options to tell
       hwclock what function to perform:

       --show Read the Hardware Clock and print the time on Stan-
              dard Output.

       --set  Set  the  Hardware  Clock  to the time given by the
              --date option.

       --hctosys
              Set the System Time from the Hardware Clock.

              Also set the kernel's timezone value to  the  local
              timezone  as  indicated by the TZ environment vari-
              able and/or /usr/lib/zoneinfo,  as  tzset(3)  would
              interpret  them.   EXCEPT:  always set the Daylight
              Savings Time part of the kernel's timezone value to
              0  ("not  Daylight Savings Time").  If DST is indi-
              cated, just add an hour to the base part.

              See the discussion of timezones below.

              This is a good option to use in one of  the  system
              startup scripts.

       --systohc
              Set  the Hardware Clock to the current System Time.

       --adjust
              Add or subtract time from  the  Hardware  Clock  to
              account  for  systematic  drift since the last time
              the clock was  set  or  adjusted.   See  discussion
              below.

       --getepoch
              Print  out  standard  output  the kernel's Hardware
              Clock epoch value.  This 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 Counter epoch value must
              be 1952.

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

       --setepoch
              Set  the kernel's Hardware Clock epoch value to the
              value specified by the  --epoch  option.   See  the
              --getepoch option for details.

       --version
              Print the version of hwclock on Standard Output.
              You  need the following option if you specify --set
              option.  Otherwise, it is ignored.

       --date=date_string
              Specifies the time to which  to  set  the  Hardware
              Clock.   The value of this option is an argument to
              the date(1) program.  For example,

              hwclock --set --date="9/22/96 16:45:05"

       --epoch=year
              Specifies the year which is the  beginning  of  the
              Hardware  Clock's  epoch.  I.e. the number of years
              into AD to which  a  zero  value  in  the  Hardware
              Clock's year counter refers.

              For example,

              hwclock --setepoch --epoch=1952

       The following options apply to most functions.

       --utc  Indicates  that the Hardware Clock is kept in Coor-
              dinated Universal Time.  It is your choice  whether
              to  keep your clock in UTC or local time, but noth-
              ing in the clock tells  which  you've  chosen.   So
              this  option  is  how  you give that information to
              hwclock.

              In order to avoid any  possible  misunderstandings:
              all  conversation  with the program hwclock is done
              in local time. If you have your clock in UTC (as is
              common  on  a  Unix  system)  then the option --utc
              tells hwclock to do  the  appropriate  conversions:
              `hwclock  --show  --utc'  will  tell  you the local
              time, assuming the hardware clock is  in  UTC,  and
              `hwclock  --set  --date="XXX"  --utc'  will set the
              hardware clock to the UTC equivalent of  the  local
              time XXX.

       --directisa
              is  meaningful  only  on  an  ISA machine.  For all
              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 try to use the /dev/rtc device (which
              it assumes to be driven by the rtc device  driver).
              If  it  is unable to open the device (for read), it
              will use the explicit I/O instructions anyway.

              The rtc device driver was new in Linux Release 2.

       --test Do everything except actually updating the Hardware
              Clock or anything else.  This is useful, especially
              in conjunction  with  --debug,  in  learning  about
              hwclock.

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

NOTES
Clocks in a Linux System
       There are two main clocks in a Linux system:

       The Hardware Clock: This is a  clock  that  runs  indepen-
       dently  of any control program running in the CPU and even
       when the machine is powered off.

       On an ISA system, this clock is specified as part  of  the
       ISA  standard.   The  control program can read or set this
       clock to a whole second, but the control program 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 because all of the other names are inappro-
       priate to the point of being misleading.

       The System Time: This is the time kept by a  clock  inside
       the  Linux kernel and driven by a timer interrupt.  (On an
       ISA machine, the timer interrupt is part of the ISA  stan-
       dard).   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 num-
       ber of seconds since 1969).  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 in a Linux system is  to  keep  time
       when Linux is not running.  You initialize the System Time
       to the time from the Hardware Clock when Linux starts  up,
       and then never use the Hardware Clock again.  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 discon-
       tinuities such as would happen if you  used  the  date(1L)
       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.   You  can  also  use  the  program  adjtimex(8) to
       smoothly adjust the System Time while the system runs.

       A Linux kernel maintains a concept of a local timezone for
       the  system.   But  don't be misled -- almost nobody cares
       what timezone the kernel thinks it is in.   Instead,  pro-
       grams  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    and/or    the
       /usr/local/timezone  directory,  as  explained  in the man
       page for tzset(3).   However,  some  programs  and  fringe
       parts of the Linux kernel such as filesystems use the ker-
       nel 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.

       hwclock sets the kernel timezone to the value indicated by
       TZ and/or /usr/local/timezone when you set the System Time
       using the --hctosys option.

       A complication is that the timezone  value  actually  con-
       sists  of two parts: 1) how far from the Standard Meridian
       the locality is geographically, and 2) whether  or  not  a
       Daylight Savings Time (DST) convention is in effect in the
       locality at the present time.  In practice, the  DST  part
       of the timezone value is almost never used, so if the geo-
       graphical part were to be set to its  correct  value,  the
       users  of  the  timezone  value would actually compute the
       wrong local time.

       Therefore, hwclock violates the definition of the kernel's
       timezone  value  and always sets the DST part to zero.  If
       DST is supposed to be in effect, hwclock  simply  adds  an
       hour to the geographical part.

How hwclock Accesses the Hardware Clock
       hwclock  Uses  many different ways to get and set Hardware
       Clock values.  The most normal way is to  do  I/O  to  the
       device  special  file  /dev/rtc,  which  is presumed to be
       driven by the rtc device driver.  However, this method  is
       not  always available.  For one thing, the rtc driver is a
       relatively recent addition to Linux.  Older systems  don't
       have it.

       On  older  systems,  the  method of accessing the Hardware
       Clock depends on the system hardware.

       On an ISA system, hwclock can directly  access  the  "CMOS
       memory"  registers that constitute the clock, by doing I/O
       to Ports 0x70 and 0x71.  It can only do  this  if  running
       with superuser effective userid.

       This  is  a really poor method of accessing the clock, for
       all the reasons that user space programs are generally not
       supposed to do direct I/O and disable interrupts.  Hwclock
       provides it because it is the only method  available  with
       older Linux kernels for ISA machines.

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

       On an Alpha, /dev/rtc is the only choice.

       There are or were some Alpha Linux systems that don't have
       /dev/rtc  and there are or were programs that accessed the
       clock via almost direct  I/O  using  /dev/port.   However,
       this is not as good a method as /dev/rtc and such programs
       were not widely enough used that hwclock has any  need  to
       be  backward  compatible  with  them.  So hwclock does not
       provide the /dev/port method  and  consequently  will  not
       work on an Alpha that doesn't have /dev/rtc.

       hwclock  tries  to  use /dev/rtc.  If it is compiled for a
       kernel that doesn't have that function or it is unable  to
       open  /dev/rtc,  hwclock will fall back to another method,
       if available.  On an ISA machine, you can force hwclock to
       use  the direct manipulation of the CMOS registers without
       even trying /dev/rtc by specifying the --directisa option.

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  make systematic corrections to correct the systematic
       drift.

       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.  5 days later, the  clock  has  gained  10
       seconds, so you issue another hwclock --set command to set
       it back 10 seconds.  Hwclock updates the adjtime  file  to
       show the current time as the last time the clock was cali-
       brated, 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  goes 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.

       Every time you calibrate (set) the clock (using  --set  or
       --systohc  ),  hwclock  recalculates  the systematic drift
       rate based on how long it has been since the last calibra-
       tion, how long it has been since the last adjustment, what
       drift rate was assumed in any intervening adjustments, and
       the amount by which the clock is presently off.

       A  small  amount  of error creeps in any time hwclock sets
       the clock, so it refrains from making an  adjustment  that
       would  be  less than 1 second.  Later on, when you request
       an adjustment again, the accumulated drift  will  be  more
       than a second and hwclock will do the adjustment then.

       It  is  good  to  do  a  hwclock  --adjust just before the
       hwclock --hctosys at system startup time, and maybe  peri-
       odically while the system is running via cron.

       The format of the adjtime file is, in ASCII:

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

       Line  2:  1 number: Resulting number of seconds since 1969
       UTC of most recent calibration.

       You can use an adjtime file that was previously used  with
       the clock 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 Hard-
       ware Clock every 11 minutes.  This is a good mode  to  use
       when  you  are  using  something sophisticated like ntp to
       keep your System Time 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).

       This  mode  (we'll  call it "11 minute mode") is off until
       something turns it on.  The ntp daemon xntpd is one  thing
       that  turns  it  on.   You can turn it off by running any-
       thing, including hwclock --hctosys , that sets the  System
       Time the old fashioned way.

       To  see  if  it  is  on  or  off, use the command adjtimex
       --print and look at the value of "status".   If  the  "64"
       bit  of  this  number (expressed in binary) equal to 0, 11
       minute mode is on.  Otherwise, it is off.

       If your system runs with 11  minute  mode  on,  don't  use
       hwclock  --adjust or hwclock --hctosys .  You'll just make
       a mess.  It is acceptable to use a  hwclock  --hctosys  at
       startup  time  to  get a reasonable System Time until your
       system is able to set the System Time  from  the  external
       source and start 11 minute mode.

ENVIRONMENT VARIABLES
       TZ

FILES
       /etc/adjtime /usr/lib/zoneinfo/

SEE ALSO
       adjtimex(8),  date(1),  gettimeofday(2),  settimeofday(2),
       crontab(1), tzset(3)

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

                          02 March 1998                         1