Differences between current version and previous revision of hwclock(8).
Other diffs: Previous Major Revision, Previous Author, or view the Annotated Edit History
| Newer page: | version 2 | Last edited on Monday, October 15, 2007 4:02:24 pm | by IanMcDonald | |
| Older page: | version 1 | Last edited on Tuesday, June 4, 2002 12:31:13 am | by perry | Revert |
@@ -1,648 +1,488 @@
-HWCLOCK
-!!!HWCLOCK
+<verbatim>
NAME
+ hwclock - query and set the hardware clock (RTC)
+
SYNOPSIS
-DESCRIPTION
-OPTIONS
-NOTES
-Clocks in
a Linux System
-How
hwclock Accesses the Hardware Clock
-The Adjust Function
-Automatic Hardware Clock Synchronization By the Kernel
-ISA Hardware Clock Century value
-ENVIRONMENT VARIABLES
-FILES
-SEE ALSO
-AUTHORS
-----
-!!NAME
+ hwclock -r or hwclock --show
+ hwclock -w or hwclock --systohc
+ hwclock -s or hwclock --hctosys
+ hwclock -
a or hwclock --adjust
+
hwclock -v or hwclock --version
+ hwclock --set --date=newdate
+ hwclock --getepoch
+ hwclock
--setepoch
--epoch=year
+ other options:
-hwclock
- query and set the hardware clock (RTC)
-!!SYNOPSIS
+ [
-u|--utc] --localtime --noadjfile --directisa --test [-D|--debug]
+ --rtc=filename
+ and arcane options for DEC Alpha:
-__hwclock
-r__ or __hwclock
--show
-hwclock
-w__ or __hwclock
--systohc
-hwclock
-s__ or __hwclock
--hctosys
-hwclock
-a__ or __hwclock
--adjust
-hwclock
-v__ or __hwclock --version
-hwclock --set --date=newdate
-hwclock --getepoch
-hwclock --setepoch --epoch=year__
+ [
-A|
--arc] [
-J|
--jensen] [
-S|
--srm] [
-F|
--funky
-toy]
+ Minimum unique abbreviations of all options are acceptable.
-other options:
+ Also, -h asks for a help message.
-__[[-u|--utc] --localtime --noadjfile --directisa --test
-[[-D|--debug]__
+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 con‐
+ sistently gains or loses time at a certain rate if left to run).
-and arcane options for DEC Alpha:
+OPTIONS
+ You need exactly one of the following options to tell hwclock what
+ function to perform:
-__[[-A|--arc] [[-J|--jensen] [[-S|--srm]
-[[-F|--funky-toy]__
+ --show Read the Hardware Clock and print the time on Standard Output.
+ The time shown is always in local time, even if you keep your
+ Hardware Clock in Coordinated Universal Time. See the --utc
+ option.
-Minimum unique abbreviations of all options are
-acceptable.
+ --set Set the Hardware Clock to the time given by the --date option.
-Also,
-h asks for a help message.
-!!DESCRIPTION
+
--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 variable and/or /usr/share/zone‐
+ info, as tzset(3) would interpret them. The obsolete tz_dsttime
+ field of the kernel’s timezone value is set to DST_NONE. (For
+ details on what this field used to mean, see settimeofday(2).)
-__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
.
+ This
is
a good option
to use in one of
the system startup
+ scripts
.
+ --systohc
+ Set the Hardware Clock to the current System Time.
-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
+ --adjust
+ Add
or subtract
time from the Hardware Clock to account
for sys‐
+ tematic
drift since the last time
the clock was set
or adjusted.
+ See discussion below
.
+ --getepoch
+ Print the kernel’s Hardware Clock epoch value to standard out‐
+ put. 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.
-You need exactly one of
the following options to tell
-__hwclock__ what function to perform:
+ 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 speci‐
+ fied by the --epoch option. See the --getepoch option for
+ details.
-__
--show__
+
--version
+ Print the version of hwclock on Standard Output.
+ --date=date_string
+ You need this option if you specify the --set option. Other‐
+ wise, it is ignored. This 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,
-Read the Hardware Clock and print the time on Standard
-Output. The time shown is always in local time, even if you
-keep your Hardware Clock in Coordinated Universal Time. See
-the __
--utc__ option.
+ hwclock
--set --date="9/22/96 16:45:05"
+ The argument is in local time, even if you keep your Hardware
+ Clock in Coordinated Universal time. See the --utc option.
-__--set__
+ --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. It is used
+ together with the --setepoch option to set the kernel’s idea of
+ the epoch of the Hardware Clock, or otherwise to specify the
+ epoch for use with direct ISA access.
-Set the Hardware Clock to the time given by the
-__--date__ option.
+ For example, on a Digital Unix machine:
+ hwclock --setepoch --epoch=1952
-__--hctosys__
+ The following options apply to most functions.
-Set the System Time from the Hardware Clock.
+ --utc
+ --localtime
+ Indicates that the Hardware Clock is kept in Coordinated Univer‐
+ sal Time or local time, respectively. It is your choice whether
+ to keep your clock in UTC or local time, but nothing in the
+ clock tells which you’ve chosen. So this option is how you give
+ that information to hwclock.
-Also set
the kernel's timezone value to the local timezone
-as indicated by the TZ environment variable
and/or
-''/usr/share/zoneinfo''
, as tzset(3) would
-interpret them. The obsolete tz_dsttime field
of the
-kernel's timezone value is set to DST_NONE
. (For details on
-what this field used to mean, see
-settimeofday(2).)
+ If you specify
the wrong one of these options (or specify nei‐
+ ther
and take a wrong default)
, both setting and querying
of the
+ Hardware Clock will be messed up
.
+ If you specify neither --utc nor --localtime , the default is
+ whichever was specified the last time hwclock was used to set
+ the clock (i.e. hwclock was successfully run with the --set ,
+ --systohc , or --adjust options), as recorded in the adjtime
+ file. If the adjtime file doesn’t exist, the default is local
+ time.
-This is a good option to use in one of the system startup
-scripts.
+ --noadjfile
+ disables 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.
-__--systohc__
+ --rtc=filename
+ overrides the default /dev file name, which is /dev/rtc on many
+ platforms but may be /dev/rtc0, /dev/rtc1, and so on.
-Set the Hardware Clock to the current System
-Time.
+ --directisa
+ is meaningful only on an ISA machine or an Alpha (which imple‐
+ ments enough of ISA to be, roughly speaking, an ISA machine for
+ hwclock’s purposes). 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
+ 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.
-__--adjust__
+ The rtc device driver was new in Linux Release 2.
+ --badyear
+ Indicates 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 can‐
+ not set the year after 1999 and cannot use the value of the
+ clock as the true time in the normal way.
-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.
+ 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 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 year!
+ 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 set‐
+ ting it, this scheme could be defeated and you could end up los‐
+ ing a day.
-__
--getepoch__
+ hwclock warns you that you probably need
--badyear whenever it
+ finds your Hardware Clock set to 1994 or 1995.
-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
.
+ --srm
This option
is equivalent
to --epoch=1900 and is used to specify
+
the most common
epoch on Alphas with SRM console
.
+ --arc This option is equivalent to --epoch=1980 and is used to specify
+ the most common epoch on Alphas with ARC console (but Ruffians
+ have epoch 1900).
-This epoch value is used whenever hwclock reads or sets the
-Hardware Clock.
+ --jensen
+ --funky-toy
+ These two options specify what kind of Alpha machine you have.
+ They are invalid if you don’t have an Alpha and are usually
+ unnecessary if you do, because hwclock should be able to deter‐
+ mine by itself what it’s running on, at least when /proc is
+ mounted. (If you find you need one of these options to make
+ hwclock work, contact the maintainer to see if the program can
+ be improved to detect your system automatically. Output of
+ ‘hwclock --debug’ and ‘cat /proc/cpuinfo’ may be of interest.)
-__
--setepoch__
+
--jensen means you are running on a Jensen model.
+ --funky-toy means that on your machine, one has to use the UF
+ bit instead of the UIP bit in the Hardware Clock to detect a
+ time transition. "Toy" in the option name refers to the Time Of
+ Year facility of the machine.
-Set the kernel's Hardware Clock epoch value to the value
-specified by the __--epoch__ option. See the
-__--getepoch__ option for details.
-__
--version__
+
--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 inter‐
+ nally. Some of its function is complex and this output can help
+ you understand how the program works.
-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__
+NOTES
+Clocks in a Linux System
+ There are two main clocks in a Linux system:
+ The Hardware Clock: This is a clock that runs independently of any con‐
+ trol program running in the CPU and even when the machine is powered
+ off.
-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
,
+ 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 inappropriate to the point of being misleading.
-''hwclock --set
--date=
-''
+ So for example, some non
-ISA systems have a few real time clocks with
+ only one of them having its own power domain. A very low power exter‐
+ nal 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 Time: This is the time kept by a clock inside the Linux ker‐
+ nel and 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 sec‐
+ onds since 00:00:00 January 1, 1970 UTC (or more succinctly, the number
+ of seconds since 1969). The System Time is not an integer, though. It
+ has virtually infinite precision.
-The argument
is in local
time, even if you keep your
-Coordinated Universal
time. See
the
-__--utc__ option
.
+
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 discontinuities 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 Hard‐
+ ware 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.
-__
--epoch=year__
+ 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, programs that care about the timezone (per‐
+ haps 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/share/zoneinfo 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 kernel
+ 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/share/zoneinfo when you set the System Time using the --hctosys
+ option.
-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
. It
-together with the --setepoch option to set the
-kernel's idea of the epoch of the Hardware Clock, or
-otherwise to specify the epoch for use with direct ISA
-access
.
+ The timezone value actually consists
of two parts: 1) a field tz_min‐
+ uteswest indicating how many minutes local time (not adjusted for DST)
+ lags behind UTC, and 2) a field tz_dsttime indicating
the type
of Day‐
+ light 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)
.)
-For example
, on a Digital Unix machine:
+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.
+ Also, though there are versions of the rtc driver that work
on DEC
+ Alphas, there appear to be plenty of Alphas on which the rtc driver
+ does not work (
a common symptom is hwclock hanging). Moreover, recent
+ Linux systems have more generic support for RTCs, even systems that
+ have more than one, so you might need to override the default by speci‐
+ fying /dev/rtc0 or /dev/rtc1 instead.
+ On older systems, the method of accessing the Hardware Clock depends on
+ the system hardware.
-''
hwclock --setepoch --epoch=1952''
+ On an ISA system,
hwclock can directly access the "CMOS memory" regis‐
+ ters 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. (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).
+ This is a really poor method of accessing the clock, for all the rea‐
+ sons 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 on ISA and Alpha systems which don’t have working rtc
+ device drivers available.
-The following options apply to most functions.
+ On an m68k system, hwclock can access the clock via the console driver,
+ via the device special file /dev/tty1.
-__
--utc__
+ 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 (or the
+ alternative special file you’ve defined on the command line) hwclock
+ will fall back to another method, if available. On an ISA or Alpha
+ machine, you can force hwclock to use the direct manipulation of the
+ CMOS registers without even trying /dev/rtc by specifying the
--direc‐
+ tisa option.
-__--localtime__
+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.
-Indicates
that the Hardware Clock is kept in Coordinated
-Universal Time or local time, respectively
. It
is your
-choice whether to keep your clock in UTC or local time, but
-nothing in
the clock tells which you've chosen. So this
-option is how you give that information to
-__hwclock__
.
+ 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 com‐
+ mand to set the Hardware Clock to the true current time. Hwclock cre‐
+ ates 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 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 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.
-If
you specify
the wrong one of these options
(or specify
-neither and take a wrong default
), both setting and querying
-of
the Hardware Clock will be messed up
.
+ 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 calibration, 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.
-If you specify neither __--utc__ nor __--localtime__ ,
-the default
is whichever was specified the last time
-__hwclock__ was used
to set the clock (i.e.
hwclock was
-successfully run with the __
--set__ , __
--systohc__ ,
-or __--adjust__ options)
, as recorded in
the adjtime
-file. If the adjtime file doesn't exist, the default
is
-local time
.
+ It
is good
to do a
hwclock --adjust just before the hwclock
--hctosys
+ at system startup time
, and maybe periodically while
the system
is run‐
+ ning via cron
.
+ The adjtime file, while named for its historical purpose of controlling
+ adjustments only, actually contains other information for use by
+ hwclock in remembering information from one invocation to the next.
-__--noadjfile__
+ 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 inte‐
+ ger; 3) zero (for compatibility with clock(8)) as a decimal integer.
-disables 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
.
+ Line 2: 1 number: 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.
-__--directisa__
+ You can use an adjtime file that was previously used with the clock(8)
+ program with hwclock.
-is meaningful only on an ISA machine or an Alpha (which
-implements enough of ISA to be, roughly speaking, an ISA
-machine for __hwclock__'s purposes). 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 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.
+Automatic Hardware Clock Synchronization By the Kernel
+ You should be aware of another way that the Hardware Clock is kept syn‐
+ chronized in some systems. The Linux kernel has a mode wherein it
+ copies the System Time to the Hardware 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 Sys‐
+ tem Time synchronized either to a time server somewhere on the network
+ or to a radio clock hooked up to your system. See RFC 1305).
-The rtc device driver was new in Linux Release
-2
.
+ 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 anything, 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.
-__
--badyear__
+ 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.
-Indicates 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.
+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.
-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 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 year!
+ 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.
-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.
+ENVIRONMENT VARIABLES
+ TZ
-__hwclock__ warns you that you probably need
-__--badyear__ whenever it finds your Hardware Clock set
-to 1994 or 1995.
+FILES
+ /etc/adjtime /usr/share/zoneinfo/ /dev/rtc /dev/rtc0 /dev/port
+ /dev/tty1 /proc/cpuinfo
-__--srm__
+SEE ALSO
+</verbatim>
+<pre>
+ [adjtimex(8)], [date(1)], [gettimeofday(2)], [settimeofday(2)], [crontab(1)],
+ [tzset(3)] /etc/init.d/hwclock.sh, /usr/share/doc/util-
+ linux/README.Debian.hwclock
+</pre>
+<verbatim>
-This option is equivalent to __--epoch=1900__ and is used
-to specify the most common epoch on Alphas with SRM
-console.
-
-
-__--arc__
-
-
-This option is equivalent to __--epoch=1980__ and is used
-to specify the most common epoch on Alphas with ARC console
-(but Ruffians have epoch 1900).
-
-
-__--jensen__
-
-
-__--funky-toy__
-
-
-These two options specify what kind of Alpha machine you
-have. They are invalid if you don't have an Alpha and are
-usually unnecessary if you do, because __hwclock__ should
-be able to determine
by itself what it's running on
, at
-least when ''/proc'' is mounted.
(If you find you need
-one of these options to make __hwclock__ work, contact
-the maintainer to see if the program can be improved to
-detect your system automatically. Output of `hwclock
--debug' and `cat /proc/cpuinfo' may be of
-interest
.)
-
-
-__--jensen__ means you are running
on a Jensen
-model.
-
-
-__--funky-toy__ means that
on your machine, one has to
-use
the UF bit instead of the UIP bit in the Hardware Clock
-to detect a time transition.
-__
-
-
-__--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
-independently 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
-__hwclock__ because all of the other names are
-inappropriate 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
-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). 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
-discontinuities 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, 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 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 kernel 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.
-
-
-The 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).)
-!!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. Also, though there are versions of the rtc driver
-that work on DEC Alphas, there appear to be plenty of Alphas
-on which the rtc driver does not work (a common symptom is
-hwclock hanging).
-
-
-On older systems, the method of accessing the Hardware Clock
-depends on the system hardware.
-
-
-On an ISA system, __hwclock__ can directly access the
-__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).
-
-
-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 on ISA
-and Alpha systems which don't have working rtc device
-drivers available.
-
-
-On an m68k system, __hwclock__ can access the clock via
-the console driver, via the device special file
-/dev/tty1.
-
-
-__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 or Alpha 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
-__
-
-
-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 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 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 calibration, 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
-periodically while the system is running via
-cron.
-
-
-The adjtime file, while named for its historical purpose of
-controlling adjustments only, actually contains other
-information for use by hwclock in remembering information
-from one invocation to the next.
-
-
-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(8)) as a decimal
-integer.
-
-
-Line 2: 1 number: 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:
-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 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
-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
-''
-
-
-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.
-!!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
-!!ENVIRONMENT VARIABLES
-
-
-''TZ''
-!!FILES
-
-
-''/etc/adjtime /usr/share/zoneinfo/ /dev/rtc /dev/port
-/dev/tty1 /proc/cpuinfo''
-!!SEE ALSO
-
-
-adjtimex(8), date(1), gettimeofday(2),
-settimeofday(2), crontab(1), tzset(3)
-__/etc/init.d/hwclock.sh,
-/usr/share/doc/util-linux/README.Debian.hwclock__
-!!AUTHORS
+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 cred‐
+
its.
-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
.
---
--
+AVAILABILITY
+ The hwclock command is part of the util
-linux-ng package
and is avail‐
+ able from ftp://ftp
.kernel
.org/pub/linux/utils/util
-linux
-ng/.
+</verbatim>
