summaryrefslogtreecommitdiffstats
path: root/man2/timerfd_create.2
diff options
context:
space:
mode:
Diffstat (limited to 'man2/timerfd_create.2')
-rw-r--r--man2/timerfd_create.2113
1 files changed, 57 insertions, 56 deletions
diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2
index 23c399c7d..28b5a7338 100644
--- a/man2/timerfd_create.2
+++ b/man2/timerfd_create.2
@@ -24,24 +24,24 @@ Standard C library
These system calls create and operate on a timer
that delivers timer expiration notifications via a file descriptor.
They provide an alternative to the use of
-.BR setitimer (2)
+.MR setitimer 2
or
-.BR timer_create (2),
+.MR timer_create 2 ,
with the advantage that the file descriptor may be monitored by
-.BR select (2),
-.BR poll (2),
+.MR select 2 ,
+.MR poll 2 ,
and
-.BR epoll (7).
+.MR epoll 7 .
.P
The use of these three system calls is analogous to the use of
-.BR timer_create (2),
-.BR timer_settime (2),
+.MR timer_create 2 ,
+.MR timer_settime 2 ,
and
-.BR timer_gettime (2).
+.MR timer_gettime 2 .
(There is no analog of
-.BR timer_getoverrun (2),
+.MR timer_getoverrun 2 ,
since that functionality is provided by
-.BR read (2),
+.MR read 2 ,
as described below.)
.\"
.SS timerfd_create()
@@ -95,11 +95,11 @@ The caller must have the
capability in order to set a timer against this clock.
.P
See
-.BR clock_getres (2)
+.MR clock_getres 2
for some further details on the above clocks.
.P
The current value of each of these clocks can be retrieved using
-.BR clock_gettime (2).
+.MR clock_gettime 2 .
.P
Starting with Linux 2.6.27, the following values may be bitwise ORed in
.I flags
@@ -110,10 +110,10 @@ to change the behavior of
Set the
.B O_NONBLOCK
file status flag on the open file description (see
-.BR open (2))
+.MR open 2 )
referred to by the new file descriptor.
Using this flag saves extra calls to
-.BR fcntl (2)
+.MR fcntl 2
to achieve the same result.
.TP
.B TFD_CLOEXEC
@@ -123,7 +123,7 @@ flag on the new file descriptor.
See the description of the
.B O_CLOEXEC
flag in
-.BR open (2)
+.MR open 2
for reasons why this may be useful.
.P
In Linux versions up to and including 2.6.26,
@@ -141,7 +141,7 @@ argument specifies the initial expiration and interval for the timer.
The
.I itimerspec
structure used for this argument is described in
-.BR itimerspec (3type).
+.MR itimerspec 3type .
.P
.I new_value.it_value
specifies the initial expiration of the timer,
@@ -195,11 +195,12 @@ or
.BR CLOCK_REALTIME_ALARM ,
then mark this timer as cancelable if the real-time clock
undergoes a discontinuous change
-.RB ( settimeofday (2),
-.BR clock_settime (2),
+\%(\c
+.MR settimeofday 2 ,
+.MR clock_settime 2 ,
or similar).
When such changes occur, a current or future
-.BR read (2)
+.MR read 2
from the file descriptor will fail with the error
.BR ECANCELED .
.P
@@ -244,14 +245,14 @@ The file descriptor returned by
.BR timerfd_create ()
supports the following additional operations:
.TP
-.BR read (2)
+.MR read 2
If the timer has already expired one or more times since
its settings were last modified using
.BR timerfd_settime (),
or since the last successful
-.BR read (2),
+.MR read 2 ,
then the buffer given to
-.BR read (2)
+.MR read 2
returns an unsigned 8-byte integer
.RI ( uint64_t )
containing the number of expirations that have occurred.
@@ -259,20 +260,20 @@ containing the number of expirations that have occurred.
the native byte order for integers on the host machine.)
.IP
If no timer expirations have occurred at the time of the
-.BR read (2),
+.MR read 2 ,
then the call either blocks until the next timer expiration,
or fails with the error
.B EAGAIN
if the file descriptor has been made nonblocking
(via the use of the
-.BR fcntl (2)
+.MR fcntl 2
.B F_SETFL
operation to set the
.B O_NONBLOCK
flag).
.IP
A
-.BR read (2)
+.MR read 2
fails with the error
.B EINVAL
if the size of the supplied buffer is less than 8 bytes.
@@ -288,7 +289,7 @@ and the flag
was specified when calling
.BR timerfd_settime (),
then
-.BR read (2)
+.MR read 2
fails with the error
.B ECANCELED
if the real-time clock undergoes a discontinuous change.
@@ -308,38 +309,38 @@ was
specified when calling
.BR timerfd_settime (),
then a discontinuous negative change to the clock (e.g.,
-.BR clock_settime (2))
+.MR clock_settime 2 )
may cause
-.BR read (2)
+.MR read 2
to unblock, but return a value of 0 (i.e., no bytes read),
if the clock change occurs after the time expired,
but before the
-.BR read (2)
+.MR read 2
on the file descriptor.
.TP
-.BR poll (2)
+.MR poll 2
.TQ
-.BR select (2)
+.MR select 2
.TQ
(and similar)
The file descriptor is readable
(the
-.BR select (2)
+.MR select 2
.I readfds
argument; the
-.BR poll (2)
+.MR poll 2
.B POLLIN
flag)
if one or more timer expirations have occurred.
.IP
The file descriptor also supports the other file-descriptor
multiplexing APIs:
-.BR pselect (2),
-.BR ppoll (2),
+.MR pselect 2 ,
+.MR ppoll 2 ,
and
-.BR epoll (7).
+.MR epoll 7 .
.TP
-.BR ioctl (2)
+.MR ioctl 2
The following timerfd-specific command is supported:
.RS
.TP
@@ -357,7 +358,7 @@ This operation is available only if the kernel was configured with the
option.
.RE
.TP
-.BR close (2)
+.MR close 2
When the file descriptor is no longer required it should be closed.
When all file descriptors associated with the same timer object
have been closed,
@@ -365,13 +366,13 @@ the timer is disarmed and its resources are freed by the kernel.
.\"
.SS fork(2) semantics
After a
-.BR fork (2),
+.MR fork 2 ,
the child inherits a copy of the file descriptor created by
.BR timerfd_create ().
The file descriptor refers to the same underlying
timer object as the corresponding file descriptor in the parent,
and
-.BR read (2)s
+.MR read 2 s
in the child will return information about
expirations of the timer.
.\"
@@ -379,7 +380,7 @@ expirations of the timer.
A file descriptor created by
.BR timerfd_create ()
is preserved across
-.BR execve (2),
+.MR execve 2 ,
and continues to generate timer expirations if the timer was armed.
.SH RETURN VALUE
On success,
@@ -494,7 +495,7 @@ and
flags;
.IP (2)
A discontinuous change (e.g.,
-.BR settimeofday (2))
+.MR settimeofday 2 )
is subsequently made to the
.B CLOCK_REALTIME
clock; and
@@ -502,7 +503,7 @@ clock; and
the caller once more calls
.BR timerfd_settime ()
to rearm the timer (without first doing a
-.BR read (2)
+.MR read 2
on the file descriptor).
.P
In this case the following occurs:
@@ -528,7 +529,7 @@ Currently,
.\" 2.6.29
.BR timerfd_create ()
supports fewer types of clock IDs than
-.BR timer_create (2).
+.MR timer_create 2 .
.SH EXAMPLES
The following program creates a timer and then monitors its progress.
The program accepts up to three command-line arguments.
@@ -690,15 +691,15 @@ main(int argc, char *argv[])
.EE
.\" SRC END
.SH SEE ALSO
-.BR eventfd (2),
-.BR poll (2),
-.BR read (2),
-.BR select (2),
-.BR setitimer (2),
-.BR signalfd (2),
-.BR timer_create (2),
-.BR timer_gettime (2),
-.BR timer_settime (2),
-.BR timespec (3),
-.BR epoll (7),
-.BR time (7)
+.MR eventfd 2 ,
+.MR poll 2 ,
+.MR read 2 ,
+.MR select 2 ,
+.MR setitimer 2 ,
+.MR signalfd 2 ,
+.MR timer_create 2 ,
+.MR timer_gettime 2 ,
+.MR timer_settime 2 ,
+.MR timespec 3 ,
+.MR epoll 7 ,
+.MR time 7