diff options
Diffstat (limited to 'man2/timerfd_create.2')
-rw-r--r-- | man2/timerfd_create.2 | 113 |
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 |