man4/rtc.4

   1 .\" rtc.4
   2 .\" Copyright 2002 Urs Thuermann (urs@isnogud.escape.de)
   3 .\"
   4 .\" SPDX-License-Identifier: GPL-2.0-or-later
   5 .\"
   6 .\" $Id: rtc.4,v 1.4 2005/12/05 17:19:49 urs Exp $
   7 .\"
   8 .\" 2006-02-08 Various additions by mtk
   9 .\" 2006-11-26 cleanup, cover the generic rtc framework; David Brownell
  10 .\"
  11 .TH RTC 4 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  12 .SH NAME
  13 rtc \- real-time clock
  14 .SH SYNOPSIS
  15 .nf
  16 #include <linux/rtc.h>
  17 .PP
  18 .BI "int ioctl(" fd ", RTC_" request ", " param ");"
  19 .fi
  20 .SH DESCRIPTION
  21 This is the interface to drivers for real-time clocks (RTCs).
  22 .PP
  23 Most computers have one or more hardware clocks which record the
  24 current "wall clock" time.
  25 These are called "Real Time Clocks" (RTCs).
  26 One of these usually has battery backup power so that it tracks the time
  27 even while the computer is turned off.
  28 RTCs often provide alarms and other interrupts.
  29 .PP
  30 All i386 PCs, and ACPI-based systems, have an RTC that is compatible with
  31 the Motorola MC146818 chip on the original PC/AT.
  32 Today such an RTC is usually integrated into the mainboard's chipset
  33 (south bridge), and uses a replaceable coin-sized backup battery.
  34 .PP
  35 Non-PC systems, such as embedded systems built around system-on-chip
  36 processors, use other implementations.
  37 They usually won't offer the same functionality as the RTC from a PC/AT.
  38 .SS RTC vs system clock
  39 RTCs should not be confused with the system clock, which is
  40 a software clock maintained by the kernel and used to implement
  41 .BR gettimeofday (2)
  42 and
  43 .BR time (2),
  44 as well as setting timestamps on files, and so on.
  45 The system clock reports seconds and microseconds since a start point,
  46 defined to be the POSIX Epoch: 1970-01-01 00:00:00 +0000 (UTC).
  47 (One common implementation counts timer interrupts, once
  48 per "jiffy", at a frequency of 100, 250, or 1000 Hz.)
  49 That is, it is supposed to report wall clock time, which RTCs also do.
  50 .PP
  51 A key difference between an RTC and the system clock is that RTCs
  52 run even when the system is in a low power state (including "off"),
  53 and the system clock can't.
  54 Until it is initialized, the system clock can only report time since
  55 system boot ... not since the POSIX Epoch.
  56 So at boot time, and after resuming from a system low power state, the
  57 system clock will often be set to the current wall clock time using an RTC.
  58 Systems without an RTC need to set the system clock using another clock,
  59 maybe across the network or by entering that data manually.
  60 .SS RTC functionality
  61 RTCs can be read and written with
  62 .BR hwclock (8),
  63 or directly with the
  64 .BR ioctl (2)
  65 requests listed below.
  66 .PP
  67 Besides tracking the date and time, many RTCs can also generate
  68 interrupts
  69 .IP * 3
  70 on every clock update (i.e., once per second);
  71 .IP *
  72 at periodic intervals with a frequency that can be set to
  73 any power-of-2 multiple in the range 2 Hz to 8192 Hz;
  74 .IP *
  75 on reaching a previously specified alarm time.
  76 .PP
  77 Each of those interrupt sources can be enabled or disabled separately.
  78 On many systems, the alarm interrupt can be configured as a system wakeup
  79 event, which can resume the system from a low power state such as
  80 Suspend-to-RAM (STR, called S3 in ACPI systems),
  81 Hibernation (called S4 in ACPI systems),
  82 or even "off" (called S5 in ACPI systems).
  83 On some systems, the battery backed RTC can't issue
  84 interrupts, but another one can.
  85 .PP
  86 The
  87 .I /dev/rtc
  88 (or
  89 .IR /dev/rtc0 ,
  90 .IR /dev/rtc1 ,
  91 etc.)
  92 device can be opened only once (until it is closed) and it is read-only.
  93 On
  94 .BR read (2)
  95 and
  96 .BR select (2)
  97 the calling process is blocked until the next interrupt from that RTC
  98 is received.
  99 Following the interrupt, the process can read a long integer, of which
 100 the least significant byte contains a bit mask encoding
 101 the types of interrupt that occurred,
 102 while the remaining 3 bytes contain the number of interrupts since the
 103 last
 104 .BR read (2).
 105 .SS ioctl(2) interface
 106 The following
 107 .BR ioctl (2)
 108 requests are defined on file descriptors connected to RTC devices:
 109 .TP
 110 .B RTC_RD_TIME
 111 Returns this RTC's time in the following structure:
 112 .IP
 113 .in +4n
 114 .EX
 115 struct rtc_time {
 116     int tm_sec;
 117     int tm_min;
 118     int tm_hour;
 119     int tm_mday;
 120     int tm_mon;
 121     int tm_year;
 122     int tm_wday;     /* unused */
 123     int tm_yday;     /* unused */
 124     int tm_isdst;    /* unused */
 125 };
 126 .EE
 127 .in
 128 .IP
 129 The fields in this structure have the same meaning and ranges as for the
 130 .I tm
 131 structure described in
 132 .BR gmtime (3).
 133 A pointer to this structure should be passed as the third
 134 .BR ioctl (2)
 135 argument.
 136 .TP
 137 .B RTC_SET_TIME
 138 Sets this RTC's time to the time specified by the
 139 .I rtc_time
 140 structure pointed to by the third
 141 .BR ioctl (2)
 142 argument.
 143 To set the
 144 RTC's time the process must be privileged (i.e., have the
 145 .B CAP_SYS_TIME
 146 capability).
 147 .TP
 148 .BR RTC_ALM_READ ", " RTC_ALM_SET
 149 Read and set the alarm time, for RTCs that support alarms.
 150 The alarm interrupt must be separately enabled or disabled using the
 151 .BR RTC_AIE_ON ", " RTC_AIE_OFF
 152 requests.
 153 The third
 154 .BR ioctl (2)
 155 argument is a pointer to an
 156 .I rtc_time
 157 structure.
 158 Only the
 159 .IR tm_sec ,
 160 .IR tm_min ,
 161 and
 162 .I tm_hour
 163 fields of this structure are used.
 164 .TP
 165 .BR RTC_IRQP_READ ", " RTC_IRQP_SET
 166 Read and set the frequency for periodic interrupts,
 167 for RTCs that support periodic interrupts.
 168 The periodic interrupt must be separately enabled or disabled using the
 169 .BR RTC_PIE_ON ", " RTC_PIE_OFF
 170 requests.
 171 The third
 172 .BR ioctl (2)
 173 argument is an
 174 .I "unsigned long\ *"
 175 or an
 176 .IR "unsigned long" ,
 177 respectively.
 178 The value is the frequency in interrupts per second.
 179 The set of allowable frequencies is the multiples of two
 180 in the range 2 to 8192.
 181 Only a privileged process (i.e., one having the
 182 .B CAP_SYS_RESOURCE
 183 capability) can set frequencies above the value specified in
 184 .IR /proc/sys/dev/rtc/max\-user\-freq .
 185 (This file contains the value 64 by default.)
 186 .TP
 187 .BR RTC_AIE_ON ", " RTC_AIE_OFF
 188 Enable or disable the alarm interrupt, for RTCs that support alarms.
 189 The third
 190 .BR ioctl (2)
 191 argument is ignored.
 192 .TP
 193 .BR RTC_UIE_ON ", " RTC_UIE_OFF
 194 Enable or disable the interrupt on every clock update,
 195 for RTCs that support this once-per-second interrupt.
 196 The third
 197 .BR ioctl (2)
 198 argument is ignored.
 199 .TP
 200 .BR RTC_PIE_ON ", " RTC_PIE_OFF
 201 Enable or disable the periodic interrupt,
 202 for RTCs that support these periodic interrupts.
 203 The third
 204 .BR ioctl (2)
 205 argument is ignored.
 206 Only a privileged process (i.e., one having the
 207 .B CAP_SYS_RESOURCE
 208 capability) can enable the periodic interrupt if the frequency is
 209 currently set above the value specified in
 210 .IR /proc/sys/dev/rtc/max\-user\-freq .
 211 .TP
 212 .BR RTC_EPOCH_READ ", " RTC_EPOCH_SET
 213 Many RTCs encode the year in an 8-bit register which is either
 214 interpreted as an 8-bit binary number or as a BCD number.
 215 In both cases,
 216 the number is interpreted relative to this RTC's Epoch.
 217 The RTC's Epoch is
 218 initialized to 1900 on most systems but on Alpha and MIPS it might
 219 also be initialized to 1952, 1980, or 2000, depending on the value of
 220 an RTC register for the year.
 221 With some RTCs,
 222 these operations can be used to read or to set the RTC's Epoch,
 223 respectively.
 224 The third
 225 .BR ioctl (2)
 226 argument is an
 227 .I "unsigned long\ *"
 228 or an
 229 .IR "unsigned long" ,
 230 respectively, and the value returned (or assigned) is the Epoch.
 231 To set the RTC's Epoch the process must be privileged (i.e., have the
 232 .B CAP_SYS_TIME
 233 capability).
 234 .TP
 235 .BR RTC_WKALM_RD ", " RTC_WKALM_SET
 236 Some RTCs support a more powerful alarm interface, using these ioctls
 237 to read or write the RTC's alarm time (respectively) with this structure:
 238 .PP
 239 .RS
 240 .in +4n
 241 .EX
 242 struct rtc_wkalrm {
 243     unsigned char enabled;
 244     unsigned char pending;
 245     struct rtc_time time;
 246 };
 247 .EE
 248 .in
 249 .RE
 250 .IP
 251 The
 252 .I enabled
 253 flag is used to enable or disable the alarm interrupt,
 254 or to read its current status; when using these calls,
 255 .BR RTC_AIE_ON " and " RTC_AIE_OFF
 256 are not used.
 257 The
 258 .I pending
 259 flag is used by
 260 .B RTC_WKALM_RD
 261 to report a pending interrupt
 262 (so it's mostly useless on Linux, except when talking
 263 to the RTC managed by EFI firmware).
 264 The
 265 .I time
 266 field is as used with
 267 .B RTC_ALM_READ
 268 and
 269 .B RTC_ALM_SET
 270 except that the
 271 .IR tm_mday ,
 272 .IR tm_mon ,
 273 and
 274 .I tm_year
 275 fields are also valid.
 276 A pointer to this structure should be passed as the third
 277 .BR ioctl (2)
 278 argument.
 279 .SH FILES
 280 .TP
 281 .IR /dev/rtc ", " /dev/rtc0 ", " /dev/rtc1 ", etc."
 282 RTC special character device files.
 283 .TP
 284 .I /proc/driver/rtc
 285 status of the (first) RTC.
 286 .SH NOTES
 287 When the kernel's system time is synchronized with an external
 288 reference using
 289 .BR adjtimex (2)
 290 it will update a designated RTC periodically every 11 minutes.
 291 To do so, the kernel has to briefly turn off periodic interrupts;
 292 this might affect programs using that RTC.
 293 .PP
 294 An RTC's Epoch has nothing to do with the POSIX Epoch which is
 295 used only for the system clock.
 296 .PP
 297 If the year according to the RTC's Epoch and the year register is
 298 less than 1970 it is assumed to be 100 years later, that is, between 2000
 299 and 2069.
 300 .PP
 301 Some RTCs support "wildcard" values in alarm fields, to support
 302 scenarios like periodic alarms at fifteen minutes after every hour,
 303 or on the first day of each month.
 304 Such usage is nonportable;
 305 portable user-space code expects only a single alarm interrupt, and
 306 will either disable or reinitialize the alarm after receiving it.
 307 .PP
 308 Some RTCs support periodic interrupts with periods that are multiples
 309 of a second rather than fractions of a second;
 310 multiple alarms;
 311 programmable output clock signals;
 312 nonvolatile memory;
 313 and other hardware
 314 capabilities that are not currently exposed by this API.
 315 .SH SEE ALSO
 316 .BR date (1),
 317 .BR adjtimex (2),
 318 .BR gettimeofday (2),
 319 .BR settimeofday (2),
 320 .BR stime (2),
 321 .BR time (2),
 322 .BR gmtime (3),
 323 .BR time (7),
 324 .BR hwclock (8)
 325 .PP
 326 .I Documentation/rtc.txt
 327 in the Linux kernel source tree