diff options
Diffstat (limited to 'man4/rtc.4')
| -rw-r--r-- | man4/rtc.4 | 347 |
1 files changed, 0 insertions, 347 deletions
diff --git a/man4/rtc.4 b/man4/rtc.4 deleted file mode 100644 index 5a04a7b..0000000 --- a/man4/rtc.4 +++ /dev/null @@ -1,347 +0,0 @@ -.\" rtc.4 -.\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de) -.\" -.\" SPDX-License-Identifier: GPL-2.0-or-later -.\" -.\" $Id: rtc.4,v 1.4 2005/12/05 17:19:49 urs Exp $ -.\" -.\" 2006-02-08 Various additions by mtk -.\" 2006-11-26 cleanup, cover the generic rtc framework; David Brownell -.\" -.TH rtc 4 2023-10-31 "Linux man-pages 6.7" -.SH NAME -rtc \- real-time clock -.SH SYNOPSIS -.nf -#include <linux/rtc.h> -.P -.BI "int ioctl(" fd ", RTC_" request ", " param ");" -.fi -.SH DESCRIPTION -This is the interface to drivers for real-time clocks (RTCs). -.P -Most computers have one or more hardware clocks which record the -current "wall clock" time. -These are called "Real Time Clocks" (RTCs). -One of these usually has battery backup power so that it tracks the time -even while the computer is turned off. -RTCs often provide alarms and other interrupts. -.P -All i386 PCs, and ACPI-based systems, have an RTC that is compatible with -the Motorola MC146818 chip on the original PC/AT. -Today such an RTC is usually integrated into the mainboard's chipset -(south bridge), and uses a replaceable coin-sized backup battery. -.P -Non-PC systems, such as embedded systems built around system-on-chip -processors, use other implementations. -They usually won't offer the same functionality as the RTC from a PC/AT. -.SS RTC vs system clock -RTCs should not be confused with the system clock, which is -a software clock maintained by the kernel and used to implement -.BR gettimeofday (2) -and -.BR time (2), -as well as setting timestamps on files, and so on. -The system clock reports seconds and microseconds since a start point, -defined to be the POSIX Epoch: 1970-01-01 00:00:00 +0000 (UTC). -(One common implementation counts timer interrupts, once -per "jiffy", at a frequency of 100, 250, or 1000 Hz.) -That is, it is supposed to report wall clock time, which RTCs also do. -.P -A key difference between an RTC and the system clock is that RTCs -run even when the system is in a low power state (including "off"), -and the system clock can't. -Until it is initialized, the system clock can only report time since -system boot ... not since the POSIX Epoch. -So at boot time, and after resuming from a system low power state, the -system clock will often be set to the current wall clock time using an RTC. -Systems without an RTC need to set the system clock using another clock, -maybe across the network or by entering that data manually. -.SS RTC functionality -RTCs can be read and written with -.BR hwclock (8), -or directly with the -.BR ioctl (2) -requests listed below. -.P -Besides tracking the date and time, many RTCs can also generate -interrupts -.IP \[bu] 3 -on every clock update (i.e., once per second); -.IP \[bu] -at periodic intervals with a frequency that can be set to -any power-of-2 multiple in the range 2 Hz to 8192 Hz; -.IP \[bu] -on reaching a previously specified alarm time. -.P -Each of those interrupt sources can be enabled or disabled separately. -On many systems, the alarm interrupt can be configured as a system wakeup -event, which can resume the system from a low power state such as -Suspend-to-RAM (STR, called S3 in ACPI systems), -Hibernation (called S4 in ACPI systems), -or even "off" (called S5 in ACPI systems). -On some systems, the battery backed RTC can't issue -interrupts, but another one can. -.P -The -.I /dev/rtc -(or -.IR /dev/rtc0 , -.IR /dev/rtc1 , -etc.) -device can be opened only once (until it is closed) and it is read-only. -On -.BR read (2) -and -.BR select (2) -the calling process is blocked until the next interrupt from that RTC -is received. -Following the interrupt, the process can read a long integer, of which -the least significant byte contains a bit mask encoding -the types of interrupt that occurred, -while the remaining 3 bytes contain the number of interrupts since the -last -.BR read (2). -.SS ioctl(2) interface -The following -.BR ioctl (2) -requests are defined on file descriptors connected to RTC devices: -.TP -.B RTC_RD_TIME -Returns this RTC's time in the following structure: -.IP -.in +4n -.EX -struct rtc_time { - int tm_sec; - int tm_min; - int tm_hour; - int tm_mday; - int tm_mon; - int tm_year; - int tm_wday; /* unused */ - int tm_yday; /* unused */ - int tm_isdst; /* unused */ -}; -.EE -.in -.IP -The fields in this structure have the same meaning and ranges as for the -.I tm -structure described in -.BR gmtime (3). -A pointer to this structure should be passed as the third -.BR ioctl (2) -argument. -.TP -.B RTC_SET_TIME -Sets this RTC's time to the time specified by the -.I rtc_time -structure pointed to by the third -.BR ioctl (2) -argument. -To set the -RTC's time the process must be privileged (i.e., have the -.B CAP_SYS_TIME -capability). -.TP -.B RTC_ALM_READ -.TQ -.B RTC_ALM_SET -Read and set the alarm time, for RTCs that support alarms. -The alarm interrupt must be separately enabled or disabled using the -.BR RTC_AIE_ON ", " RTC_AIE_OFF -requests. -The third -.BR ioctl (2) -argument is a pointer to an -.I rtc_time -structure. -Only the -.IR tm_sec , -.IR tm_min , -and -.I tm_hour -fields of this structure are used. -.TP -.B RTC_IRQP_READ -.TQ -.B RTC_IRQP_SET -Read and set the frequency for periodic interrupts, -for RTCs that support periodic interrupts. -The periodic interrupt must be separately enabled or disabled using the -.BR RTC_PIE_ON ", " RTC_PIE_OFF -requests. -The third -.BR ioctl (2) -argument is an -.I "unsigned long\ *" -or an -.IR "unsigned long" , -respectively. -The value is the frequency in interrupts per second. -The set of allowable frequencies is the multiples of two -in the range 2 to 8192. -Only a privileged process (i.e., one having the -.B CAP_SYS_RESOURCE -capability) can set frequencies above the value specified in -.IR /proc/sys/dev/rtc/max\-user\-freq . -(This file contains the value 64 by default.) -.TP -.B RTC_AIE_ON -.TQ -.B RTC_AIE_OFF -Enable or disable the alarm interrupt, for RTCs that support alarms. -The third -.BR ioctl (2) -argument is ignored. -.TP -.B RTC_UIE_ON -.TQ -.B RTC_UIE_OFF -Enable or disable the interrupt on every clock update, -for RTCs that support this once-per-second interrupt. -The third -.BR ioctl (2) -argument is ignored. -.TP -.B RTC_PIE_ON -.TQ -.B RTC_PIE_OFF -Enable or disable the periodic interrupt, -for RTCs that support these periodic interrupts. -The third -.BR ioctl (2) -argument is ignored. -Only a privileged process (i.e., one having the -.B CAP_SYS_RESOURCE -capability) can enable the periodic interrupt if the frequency is -currently set above the value specified in -.IR /proc/sys/dev/rtc/max\-user\-freq . -.TP -.B RTC_EPOCH_READ -.TQ -.B RTC_EPOCH_SET -Many RTCs encode the year in an 8-bit register which is either -interpreted as an 8-bit binary number or as a BCD number. -In both cases, -the number is interpreted relative to this RTC's Epoch. -The RTC's Epoch is -initialized to 1900 on most systems but on Alpha and MIPS it might -also be initialized to 1952, 1980, or 2000, depending on the value of -an RTC register for the year. -With some RTCs, -these operations can be used to read or to set the RTC's Epoch, -respectively. -The third -.BR ioctl (2) -argument is an -.I "unsigned long\ *" -or an -.IR "unsigned long" , -respectively, and the value returned (or assigned) is the Epoch. -To set the RTC's Epoch the process must be privileged (i.e., have the -.B CAP_SYS_TIME -capability). -.TP -.B RTC_WKALM_RD -.TQ -.B RTC_WKALM_SET -Some RTCs support a more powerful alarm interface, using these ioctls -to read or write the RTC's alarm time (respectively) with this structure: -.P -.RS -.in +4n -.EX -struct rtc_wkalrm { - unsigned char enabled; - unsigned char pending; - struct rtc_time time; -}; -.EE -.in -.RE -.IP -The -.I enabled -flag is used to enable or disable the alarm interrupt, -or to read its current status; when using these calls, -.BR RTC_AIE_ON " and " RTC_AIE_OFF -are not used. -The -.I pending -flag is used by -.B RTC_WKALM_RD -to report a pending interrupt -(so it's mostly useless on Linux, except when talking -to the RTC managed by EFI firmware). -The -.I time -field is as used with -.B RTC_ALM_READ -and -.B RTC_ALM_SET -except that the -.IR tm_mday , -.IR tm_mon , -and -.I tm_year -fields are also valid. -A pointer to this structure should be passed as the third -.BR ioctl (2) -argument. -.SH FILES -.TP -.I /dev/rtc -.TQ -.I /dev/rtc0 -.TQ -.I /dev/rtc1 -.TQ -\&.\|.\|. -RTC special character device files. -.TP -.I /proc/driver/rtc -status of the (first) RTC. -.SH NOTES -When the kernel's system time is synchronized with an external -reference using -.BR adjtimex (2) -it will update a designated RTC periodically every 11 minutes. -To do so, the kernel has to briefly turn off periodic interrupts; -this might affect programs using that RTC. -.P -An RTC's Epoch has nothing to do with the POSIX Epoch which is -used only for the system clock. -.P -If the year according to the RTC's Epoch and the year register is -less than 1970 it is assumed to be 100 years later, that is, between 2000 -and 2069. -.P -Some RTCs support "wildcard" values in alarm fields, to support -scenarios like periodic alarms at fifteen minutes after every hour, -or on the first day of each month. -Such usage is nonportable; -portable user-space code expects only a single alarm interrupt, and -will either disable or reinitialize the alarm after receiving it. -.P -Some RTCs support periodic interrupts with periods that are multiples -of a second rather than fractions of a second; -multiple alarms; -programmable output clock signals; -nonvolatile memory; -and other hardware -capabilities that are not currently exposed by this API. -.SH SEE ALSO -.BR date (1), -.BR adjtimex (2), -.BR gettimeofday (2), -.BR settimeofday (2), -.BR stime (2), -.BR time (2), -.BR gmtime (3), -.BR time (7), -.BR hwclock (8) -.P -.I Documentation/rtc.txt -in the Linux kernel source tree |