diff options
Diffstat (limited to 'man2/eventfd.2')
| -rw-r--r-- | man2/eventfd.2 | 108 |
1 files changed, 54 insertions, 54 deletions
diff --git a/man2/eventfd.2 b/man2/eventfd.2 index 3b67239ac..3562d4bee 100644 --- a/man2/eventfd.2 +++ b/man2/eventfd.2 @@ -46,17 +46,17 @@ 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. .TP .BR EFD_NONBLOCK " (since Linux 2.6.27)" 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 .BR EFD_SEMAPHORE " (since Linux 2.6.30)" @@ -70,23 +70,23 @@ argument is unused, and must be specified as zero. The following operations can be performed on the file descriptor returned by .BR eventfd (): .TP -.BR read (2) +.MR read 2 Each successful -.BR read (2) +.MR read 2 returns an 8-byte integer. 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. .IP The value returned by -.BR read (2) +.MR read 2 is in host byte order\[em]that is, the native byte order for integers on the host machine. .IP The semantics of -.BR read (2) +.MR read 2 depend on whether the eventfd counter currently has a nonzero value and whether the .B EFD_SEMAPHORE @@ -96,102 +96,102 @@ flag was specified when creating the eventfd file descriptor: If .B EFD_SEMAPHORE was not specified and the eventfd counter has a nonzero value, then a -.BR read (2) +.MR read 2 returns 8 bytes containing that value, and the counter's value is reset to zero. .IP \[bu] If .B EFD_SEMAPHORE was specified and the eventfd counter has a nonzero value, then a -.BR read (2) +.MR read 2 returns 8 bytes containing the value 1, and the counter's value is decremented by 1. .IP \[bu] If the eventfd counter is zero at the time of the call to -.BR read (2), +.MR read 2 , then the call either blocks until the counter becomes nonzero (at which time, the -.BR read (2) +.MR read 2 proceeds as described above) or fails with the error .B EAGAIN if the file descriptor has been made nonblocking. .RE .TP -.BR write (2) +.MR write 2 A -.BR write (2) +.MR write 2 call adds the 8-byte integer value supplied in its buffer to the counter. The maximum value that may be stored in the counter is the largest unsigned 64-bit value minus 1 (i.e., 0xfffffffffffffffe). If the addition would cause the counter's value to exceed the maximum, then the -.BR write (2) +.MR write 2 either blocks until a -.BR read (2) +.MR read 2 is performed on the file descriptor, or fails with the error .B EAGAIN if the file descriptor has been made nonblocking. .IP A -.BR write (2) +.MR write 2 fails with the error .B EINVAL if the size of the supplied buffer is less than 8 bytes, or if an attempt is made to write the value 0xffffffffffffffff. .TP -.BR poll (2) +.MR poll 2 .TQ -.BR select (2) +.MR select 2 .TQ (and similar) The returned file descriptor supports -.BR poll (2) +.MR poll 2 (and analogously -.BR epoll (7)) +.MR epoll 7 ) and -.BR select (2), +.MR select 2 , as follows: .RS .IP \[bu] 3 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 the counter has a value greater than 0. .IP \[bu] The file descriptor is writable (the -.BR select (2) +.MR select 2 .I writefds argument; the -.BR poll (2) +.MR poll 2 .B POLLOUT flag) if it is possible to write a value of at least "1" without blocking. .IP \[bu] If an overflow of the counter value was detected, then -.BR select (2) +.MR select 2 indicates the file descriptor as being both readable and writable, and -.BR poll (2) +.MR poll 2 returns a .B POLLERR event. As noted above, -.BR write (2) +.MR write 2 can never overflow the counter. However an overflow can occur if 2\[ha]64 eventfd "signal posts" were performed by the KAIO subsystem (theoretically possible, but practically unlikely). If an overflow has occurred, then -.BR read (2) +.MR read 2 will return that maximum .I uint64_t value (i.e., 0xffffffffffffffff). @@ -199,11 +199,11 @@ value (i.e., 0xffffffffffffffff). .IP The eventfd file descriptor also supports the other file-descriptor multiplexing APIs: -.BR pselect (2) +.MR pselect 2 and -.BR ppoll (2). +.MR ppoll 2 . .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 eventfd object have been closed, the resources for object are freed by the kernel. @@ -211,13 +211,13 @@ have been closed, the resources for object are freed by the kernel. A copy of the file descriptor created by .BR eventfd () is inherited by the child produced by -.BR fork (2). +.MR fork 2 . The duplicate file descriptor is associated with the same eventfd object. File descriptors created by .BR eventfd () are preserved across -.BR execve (2), +.MR execve 2 , unless the close-on-exec flag has been set. .SH RETURN VALUE On success, @@ -252,7 +252,7 @@ There was insufficient memory to create a new eventfd file descriptor. .SH ATTRIBUTES For an explanation of the terms used in this section, see -.BR attributes (7). +.MR attributes 7 . .TS allbox; lbx lb lb @@ -315,7 +315,7 @@ wrapper will employ the system call, if it is supported by the kernel. .SH NOTES Applications can use an eventfd file descriptor instead of a pipe (see -.BR pipe (2)) +.MR pipe 2 ) in all cases where a pipe is used simply to signal events. The kernel overhead of an eventfd file descriptor is much lower than that of a pipe, @@ -330,27 +330,27 @@ to signal to a file descriptor that some operation is complete. .P A key point about an eventfd file descriptor is that it can be monitored just like any other file descriptor using -.BR select (2), -.BR poll (2), +.MR select 2 , +.MR poll 2 , or -.BR epoll (7). +.MR epoll 7 . This means that an application can simultaneously monitor the readiness of "traditional" files and the readiness of other kernel mechanisms that support the eventfd interface. (Without the .BR eventfd () interface, these mechanisms could not be multiplexed via -.BR select (2), -.BR poll (2), +.MR select 2 , +.MR poll 2 , or -.BR epoll (7).) +.MR epoll 7 .) .P The current value of an eventfd counter can be viewed via the entry for the corresponding file descriptor in the process's .IR /proc/ pid /fdinfo directory. See -.BR proc (5) +.MR proc 5 for further details. .SH EXAMPLES The following program creates an eventfd file descriptor @@ -434,13 +434,13 @@ main(int argc, char *argv[]) .EE .\" SRC END .SH SEE ALSO -.BR futex (2), -.BR pipe (2), -.BR poll (2), -.BR read (2), -.BR select (2), -.BR signalfd (2), -.BR timerfd_create (2), -.BR write (2), -.BR epoll (7), -.BR sem_overview (7) +.MR futex 2 , +.MR pipe 2 , +.MR poll 2 , +.MR read 2 , +.MR select 2 , +.MR signalfd 2 , +.MR timerfd_create 2 , +.MR write 2 , +.MR epoll 7 , +.MR sem_overview 7 |