Differences between version 2 and previous revision of clock(8).
Other diffs: Previous Major Revision, Previous Author, or view the Annotated Edit History
| Newer page: | version 2 | Last edited on Friday, October 3, 2003 4:33:24 pm | by JohnMcPherson | Revert |
| Older page: | version 1 | Last edited on Tuesday, June 4, 2002 12:31:09 am | by perry | Revert |
@@ -1,648 +1 @@
-HWCLOCK
-!!!HWCLOCK
-NAME
-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 - query and set the hardware clock (RTC)
-!!SYNOPSIS
-
-
-__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:
-
-
-__
[[-u|--utc
] --localtime --noadjfile --directisa --test
-[-D|--debug
]__
-
-
-and arcane options for DEC Alpha:
-
-
-__[[-A|--arc] [[-J|--jensen] [[-S|--srm]
-[[-F|--funky-toy]__
-
-
-Minimum unique abbreviations of all options are
-acceptable.
-
-
-Also
, -h asks for a help message.
-!!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 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.
-
-
-__--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 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).)
-
-
-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=
-''
-
-
-The argument is in local time, even if you keep your
-Hardware Clock in Coordinated Universal time. See the
-__--utc__ option.
-
-
-__--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.
-
-
-For example, on a Digital Unix machine:
-
-
-''hwclock --setepoch --epoch=1952''
-
-
-The following options apply to most functions.
-
-
-__--utc__
-
-
-__--localtime__
-
-
-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__.
-
-
-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.
-
-
-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.
-
-
-__--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.
-
-
-__--directisa__
-
-
-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.
-
-
-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__ 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 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 setting it, this scheme could be
-defeated and you could end up losing a day.
-
-
-__hwclock__ warns you that you probably need
-__--badyear__ whenever it finds your Hardware Clock set
-to 1994 or 1995.
-
-
-__--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).
-
-
-__--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
-by __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
-
-
-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
.
-----
+On
[GNU
]/
[Linux
] OperatingSystems
, this manpage now points
to hwclock(8).
