]>
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), | |
80 | or directly with the ioctl requests listed below. | |
5b539973 | 81 | .PP |
92aebf8f | 82 | Besides tracking the date and time, many RTCs can also generate |
9c2360f8 | 83 | interrupts |
a6e2f128 | 84 | .IP * 3 |
75b94dc3 | 85 | on every clock update (i.e., once per second); |
9c2360f8 MK |
86 | .IP * |
87 | at periodic intervals with a frequency that can be set to | |
88 | any power-of-2 multiple in the range 2 Hz to 8192 Hz; | |
89 | .IP * | |
90 | on reaching a previously specified alarm time. | |
91 | .PP | |
92aebf8f MK |
92 | Each of those interrupt sources can be enabled or disabled separately. |
93 | On many systems, the alarm interrupt can be configured as a system wakeup | |
94 | event, which can resume the system from a low power state such as | |
95 | Suspend-to-RAM (STR, called S3 in ACPI systems), | |
96 | Hibernation (called S4 in ACPI systems), | |
97 | or even "off" (called S5 in ACPI systems). | |
98 | On some systems, the battery backed RTC can't issue | |
99 | interrupts, but another one can. | |
5b539973 | 100 | .PP |
9c2360f8 | 101 | The |
83b78642 | 102 | .I /dev/rtc |
92aebf8f | 103 | (or |
83b78642 MK |
104 | .IR /dev/rtc0 , |
105 | .IR /dev/rtc1 , | |
0967c11f | 106 | etc.) |
92aebf8f MK |
107 | device can be opened only once (until it is closed) and it is read-only. |
108 | On | |
9c2360f8 MK |
109 | .BR read (2) |
110 | and | |
111 | .BR select (2) | |
92aebf8f | 112 | the calling process is blocked until the next interrupt from that RTC |
9c2360f8 MK |
113 | is received. |
114 | Following the interrupt, the process can read a long integer, of which | |
92aebf8f MK |
115 | the least significant byte contains a bit mask encoding |
116 | the types of interrupt that occurred, | |
9c2360f8 MK |
117 | while the remaining 3 bytes contain the number of interrupts since the |
118 | last | |
119 | .BR read (2). | |
5e21af3a | 120 | .SS ioctl(2) interface |
c13182ef | 121 | The following |
9c2360f8 | 122 | .BR ioctl (2) |
92aebf8f | 123 | requests are defined on file descriptors connected to RTC devices: |
9c2360f8 MK |
124 | .TP |
125 | .B RTC_RD_TIME | |
92aebf8f | 126 | Returns this RTC's time in the following structure: |
a6e2f128 | 127 | .IP |
088a639b | 128 | .in +4n |
b8302363 | 129 | .EX |
9c2360f8 MK |
130 | struct rtc_time { |
131 | int tm_sec; | |
132 | int tm_min; | |
133 | int tm_hour; | |
134 | int tm_mday; | |
135 | int tm_mon; | |
136 | int tm_year; | |
137 | int tm_wday; /* unused */ | |
138 | int tm_yday; /* unused */ | |
139 | int tm_isdst; /* unused */ | |
140 | }; | |
b8302363 | 141 | .EE |
a08ea57c | 142 | .in |
9c2360f8 MK |
143 | .IP |
144 | The fields in this structure have the same meaning and ranges as for the | |
145 | .I tm | |
146 | structure described in | |
147 | .BR gmtime (3). | |
148 | A pointer to this structure should be passed as the third | |
5e21af3a | 149 | .BR ioctl (2) |
9c2360f8 MK |
150 | argument. |
151 | .TP | |
152 | .B RTC_SET_TIME | |
c13182ef | 153 | Sets this RTC's time to the time specified by the |
9c2360f8 | 154 | .I rtc_time |
c13182ef | 155 | structure pointed to by the third |
5e21af3a | 156 | .BR ioctl (2) |
9c2360f8 MK |
157 | argument. |
158 | To set the | |
92aebf8f | 159 | RTC's time the process must be privileged (i.e., have the |
9c2360f8 MK |
160 | .B CAP_SYS_TIME |
161 | capability). | |
162 | .TP | |
163 | .BR RTC_ALM_READ ", " RTC_ALM_SET | |
92aebf8f MK |
164 | Read and set the alarm time, for RTCs that support alarms. |
165 | The alarm interrupt must be separately enabled or disabled using the | |
166 | .BR RTC_AIE_ON ", " RTC_AIE_OFF | |
167 | requests. | |
60a90ecd MK |
168 | The third |
169 | .BR ioctl (2) | |
170 | argument is a pointer to an | |
c13182ef MK |
171 | .I rtc_time |
172 | structure. | |
173 | Only the | |
9c2360f8 MK |
174 | .IR tm_sec , |
175 | .IR tm_min , | |
176 | and | |
0daa9e92 | 177 | .I tm_hour |
9c2360f8 MK |
178 | fields of this structure are used. |
179 | .TP | |
180 | .BR RTC_IRQP_READ ", " RTC_IRQP_SET | |
92aebf8f MK |
181 | Read and set the frequency for periodic interrupts, |
182 | for RTCs that support periodic interrupts. | |
183 | The periodic interrupt must be separately enabled or disabled using the | |
184 | .BR RTC_PIE_ON ", " RTC_PIE_OFF | |
185 | requests. | |
60a90ecd MK |
186 | The third |
187 | .BR ioctl (2) | |
3c5e62b6 | 188 | argument is an |
92aebf8f | 189 | .I "unsigned long\ *" |
3c5e62b6 | 190 | or an |
c13182ef | 191 | .IR "unsigned long" , |
9c2360f8 | 192 | respectively. |
c13182ef MK |
193 | The value is the frequency in interrupts per second. |
194 | The set of allowable frequencies is the multiples of two | |
9c2360f8 MK |
195 | in the range 2 to 8192. |
196 | Only a privileged process (i.e., one having the | |
197 | .B CAP_SYS_RESOURCE | |
198 | capability) can set frequencies above the value specified in | |
199 | .IR /proc/sys/dev/rtc/max-user-freq . | |
200 | (This file contains the value 64 by default.) | |
201 | .TP | |
202 | .BR RTC_AIE_ON ", " RTC_AIE_OFF | |
92aebf8f | 203 | Enable or disable the alarm interrupt, for RTCs that support alarms. |
60a90ecd MK |
204 | The third |
205 | .BR ioctl (2) | |
206 | argument is ignored. | |
9c2360f8 MK |
207 | .TP |
208 | .BR RTC_UIE_ON ", " RTC_UIE_OFF | |
92aebf8f MK |
209 | Enable or disable the interrupt on every clock update, |
210 | for RTCs that support this once-per-second interrupt. | |
60a90ecd MK |
211 | The third |
212 | .BR ioctl (2) | |
213 | argument is ignored. | |
9c2360f8 MK |
214 | .TP |
215 | .BR RTC_PIE_ON ", " RTC_PIE_OFF | |
92aebf8f MK |
216 | Enable or disable the periodic interrupt, |
217 | for RTCs that support these periodic interrupts. | |
60a90ecd MK |
218 | The third |
219 | .BR ioctl (2) | |
220 | argument is ignored. | |
9c2360f8 MK |
221 | Only a privileged process (i.e., one having the |
222 | .B CAP_SYS_RESOURCE | |
c13182ef | 223 | capability) can enable the periodic interrupt if the frequency is |
9c2360f8 MK |
224 | currently set above the value specified in |
225 | .IR /proc/sys/dev/rtc/max-user-freq . | |
226 | .TP | |
227 | .BR RTC_EPOCH_READ ", " RTC_EPOCH_SET | |
92aebf8f | 228 | Many RTCs encode the year in an 8-bit register which is either |
c13182ef | 229 | interpreted as an 8-bit binary number or as a BCD number. |
9c2360f8 | 230 | In both cases, |
c13182ef | 231 | the number is interpreted relative to this RTC's Epoch. |
92aebf8f MK |
232 | The RTC's Epoch is |
233 | initialized to 1900 on most systems but on Alpha and MIPS it might | |
9c2360f8 | 234 | also be initialized to 1952, 1980, or 2000, depending on the value of |
c13182ef | 235 | an RTC register for the year. |
92aebf8f MK |
236 | With some RTCs, |
237 | these operations can be used to read or to set the RTC's Epoch, | |
238 | respectively. | |
60a90ecd MK |
239 | The third |
240 | .BR ioctl (2) | |
076d4cd9 | 241 | argument is an |
92aebf8f | 242 | .I "unsigned long\ *" |
076d4cd9 | 243 | or an |
c13182ef | 244 | .IR "unsigned long" , |
be9634cf | 245 | respectively, and the value returned (or assigned) is the Epoch. |
92aebf8f | 246 | To set the RTC's Epoch the process must be privileged (i.e., have the |
9c2360f8 MK |
247 | .B CAP_SYS_TIME |
248 | capability). | |
92aebf8f MK |
249 | .TP |
250 | .BR RTC_WKALM_RD ", " RTC_WKALM_SET | |
251 | Some RTCs support a more powerful alarm interface, using these ioctls | |
252 | to read or write the RTC's alarm time (respectively) with this structure: | |
253 | .PP | |
254 | .RS | |
088a639b | 255 | .in +4n |
b8302363 | 256 | .EX |
92aebf8f MK |
257 | struct rtc_wkalrm { |
258 | unsigned char enabled; | |
259 | unsigned char pending; | |
260 | struct rtc_time time; | |
261 | }; | |
b8302363 | 262 | .EE |
a08ea57c | 263 | .in |
92aebf8f MK |
264 | .RE |
265 | .IP | |
266 | The | |
267 | .I enabled | |
268 | flag is used to enable or disable the alarm interrupt, | |
269 | or to read its current status; when using these calls, | |
270 | .BR RTC_AIE_ON " and " RTC_AIE_OFF | |
c13182ef MK |
271 | are not used. |
272 | The | |
92aebf8f | 273 | .I pending |
231846a6 MK |
274 | flag is used by |
275 | .B RTC_WKALM_RD | |
276 | to report a pending interrupt | |
92aebf8f MK |
277 | (so it's mostly useless on Linux, except when talking |
278 | to the RTC managed by EFI firmware). | |
279 | The | |
280 | .I time | |
281 | field is as used with | |
282 | .B RTC_ALM_READ | |
283 | and | |
284 | .B RTC_ALM_SET | |
285 | except that the | |
286 | .IR tm_mday , | |
287 | .IR tm_mon , | |
288 | and | |
0daa9e92 | 289 | .I tm_year |
92aebf8f MK |
290 | fields are also valid. |
291 | A pointer to this structure should be passed as the third | |
5e21af3a | 292 | .BR ioctl (2) |
92aebf8f | 293 | argument. |
9c2360f8 | 294 | .SH FILES |
e15b73c0 MK |
295 | .TP |
296 | .IR /dev/rtc ", " /dev/rtc0 ", " /dev/rtc1 ", etc." | |
297 | RTC special character device files. | |
298 | .TP | |
299 | .IR /proc/driver/rtc | |
92aebf8f | 300 | status of the (first) RTC. |
9c2360f8 MK |
301 | .SH NOTES |
302 | When the kernel's system time is synchronized with an external | |
303 | reference using | |
304 | .BR adjtimex (2) | |
c13182ef | 305 | it will update a designated RTC periodically every 11 minutes. |
92aebf8f MK |
306 | To do so, the kernel has to briefly turn off periodic interrupts; |
307 | this might affect programs using that RTC. | |
5b539973 | 308 | .PP |
33a0ccb2 MK |
309 | An RTC's Epoch has nothing to do with the POSIX Epoch which is |
310 | used only for the system clock. | |
5b539973 | 311 | .PP |
92aebf8f | 312 | If the year according to the RTC's Epoch and the year register is |
75b94dc3 | 313 | less than 1970 it is assumed to be 100 years later, that is, between 2000 |
9c2360f8 | 314 | and 2069. |
5b539973 | 315 | .PP |
92aebf8f MK |
316 | Some RTCs support "wildcard" values in alarm fields, to support |
317 | scenarios like periodic alarms at fifteen minutes after every hour, | |
c13182ef | 318 | or on the first day of each month. |
d603cc27 | 319 | Such usage is nonportable; |
fdf5ab38 | 320 | portable user-space code expects only a single alarm interrupt, and |
92aebf8f | 321 | will either disable or reinitialize the alarm after receiving it. |
5b539973 | 322 | .PP |
92aebf8f MK |
323 | Some RTCs support periodic interrupts with periods that are multiples |
324 | of a second rather than fractions of a second; | |
325 | multiple alarms; | |
326 | programmable output clock signals; | |
24b74457 | 327 | nonvolatile memory; |
92aebf8f MK |
328 | and other hardware |
329 | capabilities that are not currently exposed by this API. | |
47297adb | 330 | .SH SEE ALSO |
9c2360f8 | 331 | .BR date (1), |
f0c34053 | 332 | .BR adjtimex (2), |
9c2360f8 MK |
333 | .BR gettimeofday (2), |
334 | .BR settimeofday (2), | |
f0c34053 MK |
335 | .BR stime (2), |
336 | .BR time (2), | |
9c2360f8 | 337 | .BR gmtime (3), |
eafd5ce1 | 338 | .BR time (7), |
173fe7e7 | 339 | .BR hwclock (8) |
5b539973 | 340 | .PP |
173fe7e7 DP |
341 | .I Documentation/rtc.txt |
342 | in the Linux kernel source tree |