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