last
.BR read (2).
.SS ioctl() interface
-The following
+The following
.BR ioctl (2)
requests are defined on file descriptors connected to RTC devices:
.TP
argument.
.TP
.B RTC_SET_TIME
-Sets this RTC's time to the time specified by the
+Sets this RTC's time to the time specified by the
.I rtc_time
-structure pointed to by the third
+structure pointed to by the third
.BR ioctl ()
argument.
To set the
.BR RTC_AIE_ON ", " RTC_AIE_OFF
requests.
The third \fBioctl\fP() argument is a pointer to an
-.I rtc_time
-structure.
-Only the
+.I rtc_time
+structure.
+Only the
.IR tm_sec ,
.IR tm_min ,
and
requests.
The third \fBioctl\fP() argument is a
.I "unsigned long\ *"
-or a
-.IR "unsigned long" ,
+or a
+.IR "unsigned long" ,
respectively.
-The value is the frequency in interrupts per second.
-The set of allowable frequencies is the multiples of two
+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
The third \fBioctl\fP() 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
+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
.BR RTC_EPOCH_READ ", " 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.
+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 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.
+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 \fBioctl\fP() argument is a
.I "unsigned long\ *"
-or a
-.IR "unsigned long" ,
+or a
+.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
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
+are not used.
+The
.I pending
flag is used by RTC_WKALM_RD to report a pending interrupt
(so it's mostly useless on Linux, except when talking
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.
+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.
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 non portable;
+or on the first day of each month.
+Such usage is non portable;
portable user space code only expects a single alarm interrupt, and
will either disable or reinitialize the alarm after receiving it.