From 2ad2196349e25d3af4beea2bfd444f85b987f9da Mon Sep 17 00:00:00 2001 From: Karel Zak Date: Thu, 19 Jun 2014 10:18:46 +0200 Subject: build-sys: support ./configure ADJTIME_PATH= .. to override the default /etc/adjtime path. Reported-by: Bruce Dubbs Signed-off-by: Karel Zak --- sys-utils/hwclock.8.in | 657 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 657 insertions(+) create mode 100644 sys-utils/hwclock.8.in (limited to 'sys-utils/hwclock.8.in') diff --git a/sys-utils/hwclock.8.in b/sys-utils/hwclock.8.in new file mode 100644 index 000000000..1e77269b1 --- /dev/null +++ b/sys-utils/hwclock.8.in @@ -0,0 +1,657 @@ +.TH HWCLOCK 8 "August 2011" "util-linux" "System Administration" +.SH NAME +hwclock \- query or set the hardware clock (RTC) +.SH SYNOPSIS +.B hwclock +.RI [ function ] +.RI [ option ...] + +.SH DESCRIPTION +.B 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 from the System Time, or set the System Time from the +Hardware Clock. +.PP +You can also run +.B hwclock +periodically to add or subtract time from the Hardware Clock to +compensate for systematic drift (where the clock consistently loses or +gains time at a certain rate when left to run). + +.SH FUNCTIONS +You need exactly one of the following options to tell +.B hwclock +what function to perform: +.PP +.TP +.BR \-r , \ \-\-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 +.B \-\-utc +option. +Showing the Hardware Clock time is the default when no function is specified. + +.TP +.B \-\-set +Set the Hardware Clock to the time given by the +.B \-\-date +option. +.TP +.BR \-s , \ \-\-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/share/zoneinfo , +as +.BR 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 +.BR settimeofday (2).) + +This is a good option to use in one of the system startup scripts. +.TP +.BR \-w , \ \-\-systohc +Set the Hardware Clock to the current System Time. +.TP +.B \-\-systz +Set the kernel's timezone and reset the System Time based on the current timezone. + +The system time is only reset on the first call after boot. + +The local timezone is taken to be what is +indicated by the TZ environment variable and/or +.IR /usr/share/zoneinfo , +as +.BR 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 +.BR settimeofday (2).) + +This is an alternate option to +.B \-\-hctosys +that does not read the hardware clock, and may be used in system startup +scripts for recent 2.6 kernels where you know the System Time contains +the Hardware Clock time. If the Hardware Clock is already in UTC, it is +not reset. +.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 the kernel's Hardware Clock epoch value to standard output. +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 Clock epoch value +must be 1952. + +This epoch value is used whenever +.B 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 +.BI \-\-predict +Predict what the RTC will read at time given by the +.B \-\-date +option based on the adjtime file. This is useful for example if you +need to set an RTC wakeup time to distant future and want to account +for the RTC drift. +.TP +.BR \-c , \ \-\-compare +Periodically compare the Hardware Clock to the System Time and output +the difference every 10 seconds. This will also print the frequency +offset and tick. +.TP +.BR \-h , \ \-\-help +Display help text and exit. +.TP +.BR \-V , \ \-\-version +Display version information and exit. + +.SH OPTIONS +.PP +The first two options apply to just a few specific functions, +the others apply to most functions. +.TP +.BI \-\-date= date_string +You need this option if you specify the +.B \-\-set +or +.B \-\-predict +functions, otherwise it is ignored. +It specifies the time to which to set the Hardware Clock, or the +time for which to predict the Hardware Clock reading. +The value of this option is an argument to the +.BR date (1) +program. +For example: +.sp +.B " hwclock" --set --date="2011-08-14 16:45:05" +.sp +The argument must be in local time, even if you keep your Hardware Clock in +Coordinated Universal time. See the +.B \-\-utc +option. + +.TP +.BI \-\-epoch= year +Specifies the year which is the beginning of the Hardware Clock's +epoch, that is 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 \fB\-\-setepoch\fR 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: +.sp +.B " hwclock" --setepoch --epoch=1952 + +.TP +.BR \-u , \ \-\-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 +.BR 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 +.BR \-\-localtime , +the default is whichever was specified the last time +.B hwclock +was used to set the clock (i.e. +.B hwclock +was successfully run with the +.BR \-\-set , +.BR \-\-systohc , +or +.B \-\-adjust +options), as recorded in the adjtime file. If the adjtime file doesn't +exist, the default is UTC time. + +.TP +.B \-\-noadjfile +Disables the facilities provided by +.IR @ADJTIME_PATH@ . +.B hwclock +will not read nor write to that file with this option. Either +.B \-\-utc +or +.B \-\-localtime +must be specified when using this option. + +.TP +.BI \-\-adjfile= filename +Overrides the default @ADJTIME_PATH@. + +.TP +.BR \-f , \ \-\-rtc=\fIfilename\fB +Overrides the default /dev file name, which is +.IR /dev/rtc +on many platforms but may be +.IR /dev/rtc0 , +.IR /dev/rtc1 , +and so on. + +.TP +.B \-\-directisa +This option is meaningful only on an ISA machine or an Alpha (which implements +enough of ISA to be, roughly speaking, an ISA machine for +.BR hwclock 's +purposes). For other machines, it has no effect. This option tells +.B hwclock +to use explicit I/O instructions to access the Hardware Clock. +Without this option, +.B 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 reading), it will +use the explicit I/O instructions anyway. + +.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, +.B 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 +.B 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 date is +within the past year. For this to work, you had better do a +.B hwclock \-\-set +or +.B hwclock \-\-systohc +at least once a year! + +Though +.B 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. + +.B hwclock +warns you that you probably need +.B \-\-badyear +whenever it finds your Hardware Clock set to 1994 or 1995. + +.TP +.B \-\-srm +This option is equivalent to +.B \-\-epoch=1900 +and is used to specify the most common epoch on Alphas +with SRM console. +.TP +.B \-\-arc +This option is equivalent to +.B \-\-epoch=1980 +and is used to specify the most common epoch on Alphas +with ARC console (but Ruffians have epoch 1900). +.TP +.B \-\-jensen +.TP +.B \-\-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 +.B hwclock +should be able to determine by itself what it's +running on, at least when +.I /proc +is mounted. +(If you find you need one of these options to make +.B 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.) + +Option +.B \-\-jensen +means you are running on a Jensen model. And +.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 +.BR \-\-debug , +in learning about +.BR hwclock . +.TP +.B \-\-debug +Display a lot of information about what +.B 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 +.B hwclock +because all of the other names are inappropriate to the point of being +misleading. +.PP +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 external 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. +.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. +.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 +.I /usr/share/zoneinfo +directory, as explained in the man page for +.BR 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 +.B hwclock +sets the kernel timezone to the value indicated by TZ and/or +.I /usr/share/zoneinfo +when you set the System Time using the +.B \-\-hctosys +option. +.PP +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 +.BR settimeofday (2).) + +.SH Users access and setuid +.PP +Sometimes, you need to install +.B hwclock +setuid root. If you want users other than the superuser to be able to +display the clock value using the direct ISA I/O method, install it setuid +root. If you have the /dev/rtc interface on your system or are on a non-ISA +system, there's probably no need for users to use the direct ISA I/O method, +so don't bother. + +In any case, hwclock will not allow you to set anything unless you have the +superuser real uid. (This is restriction is not necessary if you haven't +installed setuid root, but it's there for now). + +.SH How hwclock Accesses the Hardware Clock +.PP +.B 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 specifying +.I /dev/rtc0 +or +.I /dev/rtc1 +instead. +.PP +On older systems, the method of accessing the Hardware Clock depends on +the system hardware. +.PP +On an ISA system, +.B 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 +.B 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, +.B hwclock +can access the clock via the console driver, via the device special +file /dev/tty1. +.PP +.B 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) +.B hwclock +will fall back to another method, if available. On an ISA or Alpha +machine, you can force +.B hwclock +to use the direct manipulation of the CMOS registers without even trying +.I /dev/rtc +by specifying the +.B \-\-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. +.BR hwclock 's +"adjust" function lets you make systematic corrections to correct the +systematic drift. +.PP +It works like this: +.B hwclock +keeps a file, +.IR @ADJTIME_PATH@ , +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. +.B 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. +.B 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. +.B 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 +.IR "hwclock \-\-adjust" . +.B 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 +.IR \-\-systohc ), +.B 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 +.B 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 +.B 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 +.BR clock (8)) +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 +.B hwclock +command line. +.PP +You can use an adjtime file that was previously used with the +.BR clock (8) +program with +.BR 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. + +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. +.B 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 +.B 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. + +.SH "ENVIRONMENT VARIABLES" +.I TZ + +.SH FILES +.I @ADJTIME_PATH@ +.I /usr/share/zoneinfo/ +.RI ( /usr/lib/zoneinfo +on old systems) +.I /dev/rtc +.I /dev/rtc0 +.I /dev/port +.I /dev/tty1 +.I /proc/cpuinfo + +.SH "SEE ALSO" +.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. + +.SH AVAILABILITY +The hwclock command is part of the util-linux package and is available from +ftp://ftp.kernel.org/pub/linux/utils/util-linux/. -- cgit v1.2.3-55-g7522