diff options
Diffstat (limited to 'clockB/hwclock.8')
| -rw-r--r-- | clockB/hwclock.8 | 599 |
1 files changed, 0 insertions, 599 deletions
diff --git a/clockB/hwclock.8 b/clockB/hwclock.8 deleted file mode 100644 index 0a216840ae..0000000000 --- a/clockB/hwclock.8 +++ /dev/null @@ -1,599 +0,0 @@ -.TH CLOCK 8 "02 March 1998" -.SH NAME -clock \- query and set the hardware clock (RTC) -.SH SYNOPSIS -.B "hwclock --show" -.br -.B "hwclock --set --date=newdate" -.br -.B "hwclock --systohc" -.br -.B "hwclock --hctosys" -.br -.B "hwclock --getepoch" -.br -.B "hwclock --setepoch --epoch=year" -.br -.B "hwclock --adjust" -.br -.B "hwclock --version" -.PP -other options: -.PP -.B "--utc --localtime --directisa --test --debug" -.PP -and arcane options for DEC Alpha: -.PP -.B "--arc --jensen --srm --funky-toy" -.PP -Minimum unique abbreviations of all options are acceptable. -.PP -Also, equivalent options -r, -w, -s, -a, -v, -u, -D, -A, -J, -S, and -F -are accepted for compatibility with the program "clock". - -.SH DESCRIPTION -.I 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. -.PP -You can also run -.I 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). - -.SH OPTIONS -You need exactly one of the following options to tell -.I hwclock -what function to perform: -.PP -.TP -.B \-\-show -Read the Hardware Clock and print the time on Standard Output. -The time is always in local time, even if you keep your Hardware Clock -in Coordinated Universal Time. See the -.B \-\-utc -option. - -.TP -.B \-\-set -Set the Hardware Clock to the time given by the -.B \-\-date -option. -.TP -.B \-\-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 -.IR /usr/lib/zoneinfo , -as -.BR 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 indicated, 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. -.TP -.B \-\-systohc -Set the Hardware Clock to the current System Time. -.TP -.B \-\-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. -.TP -.B \-\-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. -.TP -.B \-\-setepoch -Set the kernel's Hardware Clock epoch value to the value specified by the -.B \-\-epoch -option. See the -.B \-\-getepoch -option for details. -.TP -.B \-\-version -Print the version of -.I hwclock -on Standard Output. -.br -You need the following option if you specify -.B \-\-set -option. Otherwise, it is ignored. -.TP -.B \-\-date=date_string -Specifies the time to which to set the Hardware Clock. The value of this -option is an argument to the -.I date(1) -program. For example, -.sp -.I hwclock --set --date="9/22/96 16:45:05" -.sp -The argument is in local time, even if you keep your Hardware Clock in -Coordinated Universal time. See the -.I \-\-utc -option. - -.TP -.B \-\-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, -.sp -.I hwclock --setepoch --epoch=1952 - -.PP -The following options apply to most functions. -.TP -.B \-\-utc -.TP -.B \-\-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 -.IR 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 -.B \-\-utc -nor -.B \-\-localtime -, the default is whichever was specified the last time -.I hwclock -was used to set the clock (i.e. hwclock was successfully run with the -.B \-\-set -, -.B \-\-systohc -, -or -.B \-\-adjust -options), as recorded in the adjtime file. If the adjtime file doesn't -exist, the default is local time. - -.TP -.B \-\-directisa -is meaningful only on an ISA machine or an Alpha (which implements enough -of ISA to be, roughly speaking, an ISA machine for -.IR hwclock 's -purposes). For other machines, it has no effect. This option tells -.I hwclock -to use explicit I/O instructions to access the Hardware Clock. -Without this option, -.I 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. -.TP -.B \-\-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, -.I 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 -.B \-\-badyear -if you have one of these machines. When -.I 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 -.I hwclock \-\-set -or -.I hwclock \-\-systohc -at least once a year! - -Though -.I 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. - -.I hwclock -warns you that you probably need -.B \-\-badyear -whenever it finds your Hardware Clock set to 1994 or 1995. - -.TP -.B \-\-srm -.TP -.B \-\-arc -.TP -.B \-\-jensen -.TP -.B \-\-funky\-toy -These options all tell -.I hwclock -what kind of Alpha machine you have. They -are invalid if you don't have an Alpha and shouldn't be necessary if you -do, because -.I hwclock -should be able to determine by itself what it's -running on. These options make it possible for -.I hwclock -to work even when -its environment does not conform to its expectations and thus it cannot -accurately determine what sort of system it is running on. If you think -hwclock is incorrectly determining the system's characteristics, try -running with the -.B \-\-debug -option to see what conclusions the program is -reaching and how. If you find you need one of these options to make -.I hwclock -work, contact the -.I hwclock -maintainer to see if the program can be improved to detect your system -automatically. - -.B \-\-jensen -means you are running on a Jensen model. - -.B \-\-arc -means your machine is running with ARC console time. - -.B \-\-srm -means your machine is running with SRM console time. - -.B \-\-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. - - -.TP -.B \-\-test -Do everything except actually updating the Hardware Clock or anything -else. This is useful, especially in conjunction with -.B \-\-debug, -in learning about -.I hwclock. -.TP -.B \-\-debug -Display a lot of information about what -.I hwclock -is doing internally. Some of its function is complex and this output -can help you understand how the program works. - - -.SH NOTES - - -.SH Clocks in a Linux System -.PP -There are two main clocks in a Linux system: -.PP -.B 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. -.PP -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 -.I hwclock -because all of the other names are inappropriate to the point of being -misleading. -.PP -.B 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. -.PP -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. -.PP -It is important that the System Time not have any discontinuities such as -would happen if you used the -.BR 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 -.BR adjtimex (8) -to smoothly adjust the System Time while the system runs. -.PP -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. -.PP -.I hwclock -sets the kernel timezone to the value indicated by TZ and/or -/usr/local/timezone when you set the System Time using the -.B \-\-hctosys -option. -.PP -A complication is that the timezone value actually consists 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 geographical part were to be set to its correct value, the -users of the timezone value would actually compute the wrong local -time. -.PP -Therefore, -.I 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, -.I hwclock -simply adds an hour to the geographical part. - -.SH How hwclock Accesses the Hardware Clock -.PP -.I 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). -.PP -On older systems, the method of accessing the Hardware Clock depends on -the system hardware. -.PP -On an ISA system, -.I hwclock -can directly access the "CMOS memory" registers that -constitute the clock, by doing I/O to Ports 0x70 and 0x71. It does -this with actual I/O instructions and consequently can only do it if -running with superuser effective userid. (In the case of a Jensen -Alpha, there is no way for -.I 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. - -.PP -On an m68k system, -.I hwclock -can access the clock via the console driver, via the device special -file /dev/tty1. -.PP -.I 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, -.I hwclock -will fall back to another method, if available. On an ISA or Alpha -machine, you can force -.I hwclock -to use the direct manipulation of the CMOS registers without even trying -.I /dev/rtc -by specifying the \-\-directisa option. - - -.SH The Adjust Function -.PP -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. -.IR hwclock 's -"adjust" function lets you make systematic corrections to correct the -systematic drift. -.PP -It works like this: -.I hwclock -keeps a file, -.I /etc/adjtime, -that keeps some historical information. This is called the adjtime file. -.PP -Suppose you start with no adjtime file. You issue a -.I hwclock \-\-set -command to set the Hardware Clock to the true current time. -.I 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 -.I hwclock \-\-set -command to set it back 10 seconds. -.I 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 -.I hwclock \-\-adjust -command. -.I 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 -.I hwclock \-\-adjust. -.I 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. -.PP -Every time you calibrate (set) the clock (using -.I \-\-set -or -.I \-\-systohc -), -.I 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. -.PP -A small amount of error creeps in any time -.I 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 -.I hwclock -will do the adjustment then. -.PP -It is good to do a -.I hwclock \-\-adjust -just before the -.I hwclock \-\-hctosys -at system startup time, and maybe periodically while the system is -running via cron. -.PP -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. -.PP -The format of the adjtime file is, in ASCII: -.PP -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 -.IR clock ) -as a decimal integer. -.PP -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. -.PP -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 -.I hwclock -command line. -.PP -You can use an adjtime file that was previously used with the -.I clock -program with -.I hwclock. - - -.SH "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 "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 -.IR "hwclock \-\-hctosys" , -that sets the System Time the old fashioned way. - -To see if it is on or -off, use the command -.I 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 -.I hwclock \-\-adjust -or -.IR "hwclock \-\-hctosys" . -You'll just make a mess. It is acceptable to use a -.I 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. - - -.SH 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. -.I 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 -.I 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. - - - -.SH "ENVIRONMENT VARIABLES" -.I TZ - -.SH FILES -.I /etc/adjtime -.I /usr/lib/zoneinfo/ -.I /dev/rtc -.I /dev/port -.I /dev/tty1 -.I /proc/cpuinfo - -.SH "SEE ALSO" -.BR adjtimex (8), -.BR date (1), -.BR gettimeofday (2), -.BR settimeofday (2), -.BR crontab (1), -.BR tzset (3) - -.SH AUTHORS -Written By Bryan Henderson, September 1996 (bryanh@giraffe-data.com), -based on work done on the -.I clock -program by Charles Hedrick, Rob Hooft, and Harald Koenig. -See the source code for complete history and credits. - - |