Charles Steinkuehler's LEAF/LRP Website




       clock - query and set the hardware clock (RTC)


       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­

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


       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).


       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.

              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.

              Set  the Hardware Clock to the current System Time.

              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

              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.

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

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

              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"

              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

              If you don't specify --utc when you should, or vice
              versa,  both  setting  and querying of the Hardware
              Clock will be messed up.

              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

              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.


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
       consists of two parts: 1) how far from the Standard Merid­
       ian  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
       geographical 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

       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.




       /etc/adjtime /usr/lib/zoneinfo/


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


       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.

Man(1) output converted with man2html