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 --- Makefile.am | 1 + configure.ac | 6 + include/pathnames.h | 4 + sys-utils/.gitignore | 2 + sys-utils/Makemodule.am | 2 + sys-utils/hwclock.8 | 657 ------------------------------------------------ sys-utils/hwclock.8.in | 657 ++++++++++++++++++++++++++++++++++++++++++++++++ sys-utils/rtcwake.8 | 155 ------------ sys-utils/rtcwake.8.in | 157 ++++++++++++ 9 files changed, 829 insertions(+), 812 deletions(-) delete mode 100644 sys-utils/hwclock.8 create mode 100644 sys-utils/hwclock.8.in delete mode 100644 sys-utils/rtcwake.8 create mode 100644 sys-utils/rtcwake.8.in diff --git a/Makefile.am b/Makefile.am index 1c52c5382..79b5aea78 100644 --- a/Makefile.am +++ b/Makefile.am @@ -117,6 +117,7 @@ edit_cmd = sed \ -e 's|@usrbin_execdir[@]|$(usrbin_execdir)|g' \ -e 's|@usrsbin_execdir[@]|$(usrsbin_execdir)|g' \ -e 's|@VERSION[@]|$(VERSION)|g' \ + -e 's|@ADJTIME_PATH[@]|$(ADJTIME_PATH)|g' \ -e 's|@LIBUUID_VERSION[@]|$(LIBUUID_VERSION)|g' \ -e 's|@LIBMOUNT_VERSION[@]|$(LIBMOUNT_VERSION)|g' \ -e 's|@LIBSMARTCOLS_VERSION[@]|$(LIBSMARTCOLS_VERSION)|g' \ diff --git a/configure.ac b/configure.ac index cf29f6bcd..1e9669ae9 100644 --- a/configure.ac +++ b/configure.ac @@ -1776,6 +1776,12 @@ AC_ARG_VAR([SOLIB_CFLAGS], AC_ARG_VAR([SOLIB_LDFLAGS], [LDFLAGS used for shared libraries]) +AC_ARG_VAR([ADJTIME_PATH], + [Path to hwclock adjtime file, default /etc/adjtime]) +AS_IF([test "x$ADJTIME_PATH" = x], [ADJTIME_PATH="/etc/adjtime"]) +AC_DEFINE_UNQUOTED([CONFIG_ADJTIME_PATH], "$ADJTIME_PATH", [Path to hwclock adjtime file]) + + LIBS="" diff --git a/include/pathnames.h b/include/pathnames.h index b6efdb7dc..1cc4e15e6 100644 --- a/include/pathnames.h +++ b/include/pathnames.h @@ -150,7 +150,11 @@ #define _PATH_DEV_BYPARTUUID "/dev/disk/by-partuuid" /* hwclock paths */ +#ifdef CONFIG_ADJTIME_PATH +# define _PATH_ADJTIME CONFIG_ADJTIME_PATH +#else # define _PATH_ADJTIME "/etc/adjtime" +#endif #define _PATH_LASTDATE "/var/lib/lastdate" #ifdef __ia64__ diff --git a/sys-utils/.gitignore b/sys-utils/.gitignore index d378b1d2f..0185a0e6e 100644 --- a/sys-utils/.gitignore +++ b/sys-utils/.gitignore @@ -20,3 +20,5 @@ sparc64.8 sparc.8 uname26.8 x86_64.8 +hwclock.8 +rtcwake.8 diff --git a/sys-utils/Makemodule.am b/sys-utils/Makemodule.am index a2a1d6df2..68fd03046 100644 --- a/sys-utils/Makemodule.am +++ b/sys-utils/Makemodule.am @@ -104,6 +104,7 @@ endif if BUILD_RTCWAKE usrsbin_exec_PROGRAMS += rtcwake dist_man_MANS += sys-utils/rtcwake.8 +PATHFILES += sys-utils/rtcwake.8 rtcwake_SOURCES = sys-utils/rtcwake.c rtcwake_LDADD = $(LDADD) libcommon.la endif @@ -334,6 +335,7 @@ endif if BUILD_HWCLOCK sbin_PROGRAMS += hwclock dist_man_MANS += sys-utils/hwclock.8 +PATHFILES += sys-utils/hwclock.8 hwclock_SOURCES = \ sys-utils/hwclock.c \ sys-utils/hwclock.h \ diff --git a/sys-utils/hwclock.8 b/sys-utils/hwclock.8 deleted file mode 100644 index 09f1edc5e..000000000 --- a/sys-utils/hwclock.8 +++ /dev/null @@ -1,657 +0,0 @@ -.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 /etc/adjtime . -.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 /etc/adjtime. - -.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 /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. -.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 /etc/adjtime -.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/. 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/. diff --git a/sys-utils/rtcwake.8 b/sys-utils/rtcwake.8 deleted file mode 100644 index 02ab5cc15..000000000 --- a/sys-utils/rtcwake.8 +++ /dev/null @@ -1,155 +0,0 @@ -.\" Copyright (c) 2007, SUSE LINUX Products GmbH -.\" Bernhard Walle -.\" -.\" This program is free software; you can redistribute it and/or -.\" modify it under the terms of the GNU General Public License -.\" as published by the Free Software Foundation; either version 2 -.\" of the License, or (at your option) any later version. -.\" -.\" This program is distributed in the hope that it will be useful, -.\" but WITHOUT ANY WARRANTY; without even the implied warranty of -.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -.\" GNU General Public License for more details. -.\" -.\" You should have received a copy of the GNU General Public License -.\" along with this program; if not, write to the Free Software -.\" Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA -.\" 02110-1301, USA. -.\" -.TH RTCWAKE 8 "July 2007" "util-linux" "System Administration" -.SH NAME -rtcwake - enter a system sleep state until specified wakeup time -.SH SYNOPSIS -.B rtcwake -.RB [ options ] -.RB [ \-d -.IR device ] -.RB [ \-m -.IR standby_mode ] -.RB { "\-t \fItime_t\fP" | "\-s \fIseconds\fP" } -.SH DESCRIPTION -This program is used to enter a system sleep state until specified wakeup time. -.PP -This uses cross-platform Linux interfaces to enter a system sleep state, and -leave it no later than a specified time. It uses any RTC framework driver that -supports standard driver model wakeup flags. -.PP -This is normally used like the old \fBapmsleep\fP utility, to wake from a suspend -state like ACPI S1 (standby) or S3 (suspend-to-RAM). Most platforms can -implement those without analogues of BIOS, APM, or ACPI. -.P -On some systems, this can also be used like \fBnvram-wakeup\fP, waking from states -like ACPI S4 (suspend to disk). Not all systems have persistent media that are -appropriate for such suspend modes. -.SS Options -.TP -\fB-v\fP | \fB--verbose\fP -Be verbose. -.TP -\fB-h\fP | \fB--help\fP -Display help text and exit. -.TP -\fB-V\fP | \fB--version\fP -Display version information and exit. -.TP -\fB-n\fP | \fB--dry-run\fP -This option does everything apart from actually setting up the alarm, -suspending the system, or waiting for the alarm. -.TP -\fB-A\fP | \fB--adjfile\fP \fIfile\fP -Specifies an alternative path to the adjust file. -.TP -\fB-a\fP | \fB--auto\fP -Reads the clock mode (whether the hardware clock is set to UTC or local time) -from \fI/etc/adjtime\fP. That's the location where the -.BR hwclock (8) -stores that information. This is the default. -.TP -\fB-l\fP | \fB--local\fP -Assumes that the hardware clock is set to local time, regardless of the -contents of \fI/etc/adjtime\fP. -.TP -\fB-u\fP | \fB--utc\fP -Assumes that the hardware clock is set to UTC (Universal Time Coordinated), -regardless of the contents of \fI/etc/adjtime\fP. -.TP -\fB-d\fP \fIdevice\fP | \fB--device\fP \fIdevice\fP -Uses \fIdevice\fP instead of \fIrtc0\fP as realtime clock. This option -is only relevant if your system has more than one RTC. You may specify -\fIrtc1\fP, \fIrtc2\fP, ... here. -.TP -\fB-s\fP \fIseconds\fP | \fB--seconds\fP \fIseconds\fP -Sets the wakeup time to \fIseconds\fP in future from now. -.TP -\fB-t\fP \fItime_t\fP | \fB--time\fP \fItime_t\fP -Sets the wakeup time to the absolute time \fItime_t\fP. \fItime_t\fP -is the time in seconds since 1970-01-01, 00:00 UTC. Use the -.BR date (1) -tool to convert between human-readable time and \fItime_t\fP. -.TP -\fB-m\fP \fImode\fP | \fB--mode\fP \fImode\fP -Use standby state \fImode\fP. Valid values are: -.RS -.TP -.B standby -ACPI state S1. This state offers minimal, though real, power savings, while -providing a very low-latency transition back to a working system. This is the -default mode. -.TP -.B mem -ACPI state S3 (Suspend-to-RAM). This state offers significant power savings as -everything in the system is put into a low-power state, except for memory, -which is placed in self-refresh mode to retain its contents. -.TP -.B freeze -The processes are frozen, all the devices are suspended and all the processors -idles. This state is a general state that does not need any platform specific -support, but it saves less power than susepnd to RAM, because the system is -still in a running state. (since Linux 3.9) -.TP -.B disk -ACPI state S4 (Suspend-to-disk). This state offers the greatest power savings, -and can be used even in the absence of low-level platform support for power -management. This state operates similarly to Suspend-to-RAM, but includes a -final step of writing memory contents to disk. -.TP -.B off -ACPI state S5 (Poweroff). This is done by calling '/sbin/shutdown'. -Not officially supported by ACPI, but usually working. -.TP -.B no -Don't suspend. The rtcwake command sets RTC wakeup time only. -.TP -.B on -Don't suspend, but read RTC device until alarm time appears. This mode is -useful for debugging. -.TP -.B disable -Disable previously set alarm. -.TP -.B show -Print alarm information in format: "alarm: off|on