diff options
Diffstat (limited to 'man7/epoll.7')
| -rw-r--r-- | man7/epoll.7 | 117 |
1 files changed, 59 insertions, 58 deletions
diff --git a/man7/epoll.7 b/man7/epoll.7 index e7892922e..be9b3b404 100644 --- a/man7/epoll.7 +++ b/man7/epoll.7 @@ -15,7 +15,7 @@ epoll \- I/O event notification facility The .B epoll API performs a similar task to -.BR poll (2): +.MR poll 2 : monitoring multiple file descriptors to see if I/O is possible on any of them. The .B epoll @@ -51,22 +51,22 @@ create and manage an .B epoll instance: .IP \[bu] 3 -.BR epoll_create (2) +.MR epoll_create 2 creates a new .B epoll instance and returns a file descriptor referring to that instance. (The more recent -.BR epoll_create1 (2) +.MR epoll_create1 2 extends the functionality of -.BR epoll_create (2).) +.MR epoll_create 2 .) .IP \[bu] Interest in particular file descriptors is then registered via -.BR epoll_ctl (2), +.MR epoll_ctl 2 , which adds items to the interest list of the .B epoll instance. .IP \[bu] -.BR epoll_wait (2) +.MR epoll_wait 2 waits for I/O events, blocking the calling thread if no events are currently available. (This system call can be thought of as fetching items from @@ -93,7 +93,7 @@ instance. A pipe writer writes 2\ kB of data on the write side of the pipe. .IP (3) A call to -.BR epoll_wait (2) +.MR epoll_wait 2 is done that will return .I rfd as a ready file descriptor. @@ -102,7 +102,7 @@ The pipe reader reads 1\ kB of data from .IR rfd . .IP (5) A call to -.BR epoll_wait (2) +.MR epoll_wait 2 is done. .P If the @@ -113,7 +113,7 @@ interface using the .B EPOLLET (edge-triggered) flag, the call to -.BR epoll_wait (2) +.MR epoll_wait 2 done in step .B 5 will probably hang despite the available data still present in the file @@ -135,7 +135,7 @@ and the event is consumed in Since the read operation done in .B 4 does not consume the whole buffer data, the call to -.BR epoll_wait (2) +.MR epoll_wait 2 done in step .B 5 might block indefinitely. @@ -153,9 +153,9 @@ interface is as follows: with nonblocking file descriptors; and .IP (2) by waiting for an event only after -.BR read (2) +.MR read 2 or -.BR write (2) +.MR write 2 return .BR EAGAIN . .P @@ -165,7 +165,7 @@ By contrast, when used as a level-triggered interface is not specified), .B epoll is simply a faster -.BR poll (2), +.MR poll 2 , and can be used wherever the latter is used since it shares the same semantics. .P @@ -177,12 +177,12 @@ the caller has the option to specify the flag, to tell .B epoll to disable the associated file descriptor after the receipt of an event with -.BR epoll_wait (2). +.MR epoll_wait 2 . When the .B EPOLLONESHOT flag is specified, it is the caller's responsibility to rearm the file descriptor using -.BR epoll_ctl (2) +.MR epoll_ctl 2 with .BR EPOLL_CTL_MOD . .P @@ -190,15 +190,15 @@ If multiple threads (or processes, if child processes have inherited the .B epoll file descriptor across -.BR fork (2)) +.MR fork 2 ) are blocked in -.BR epoll_wait (2) +.MR epoll_wait 2 waiting on the same epoll file descriptor and a file descriptor in the interest list that is marked for edge-triggered .RB ( EPOLLET ) notification becomes ready, just one of the threads (or processes) is awoken from -.BR epoll_wait (2). +.MR epoll_wait 2 . This provides a useful optimization for avoiding "thundering herd" wake-ups in some scenarios. .\" @@ -211,7 +211,7 @@ and an event happens which wakes the device from sleep, the device driver will keep the device awake only until that event is queued. To keep the device awake until the event has been processed, it is necessary to use the -.BR epoll_ctl (2) +.MR epoll_ctl 2 .B EPOLLWAKEUP flag. .P @@ -223,15 +223,15 @@ field for a .IR "struct epoll_event" , the system will be kept awake from the moment the event is queued, through the -.BR epoll_wait (2) +.MR epoll_wait 2 call which returns the event until the subsequent -.BR epoll_wait (2) +.MR epoll_wait 2 call. If the event should keep the system awake beyond that time, then a separate .I wake_lock should be taken before the second -.BR epoll_wait (2) +.MR epoll_wait 2 call. .SS /proc interfaces The following interfaces can be used to limit the amount of @@ -260,29 +260,29 @@ While the usage of .B epoll when employed as a level-triggered interface does have the same semantics as -.BR poll (2), +.MR poll 2 , the edge-triggered usage requires more clarification to avoid stalls in the application event loop. In this example, listener is a nonblocking socket on which -.BR listen (2) +.MR listen 2 has been called. The function .I do_use_fd() uses the new ready file descriptor until .B EAGAIN is returned by either -.BR read (2) +.MR read 2 or -.BR write (2). +.MR write 2 . An event-driven state machine application should, after having received .BR EAGAIN , record its current state so that at the next call to .I do_use_fd() it will continue to -.BR read (2) +.MR read 2 or -.BR write (2) +.MR write 2 from where it stopped before. .P .in +4n @@ -351,7 +351,7 @@ continuously switching between and .B EPOLLOUT calling -.BR epoll_ctl (2) +.MR epoll_ctl 2 with .BR EPOLL_CTL_MOD . .SS Questions and answers @@ -371,9 +371,10 @@ instance twice? You will probably get .BR EEXIST . However, it is possible to add a duplicate -.RB ( dup (2), -.BR dup2 (2), -.BR fcntl (2) +\%(\c +.MR dup 2 , +.MR dup2 2 , +.MR fcntl 2 .BR F_DUPFD ) file descriptor to the same .B epoll @@ -423,7 +424,7 @@ What happens if one attempts to put an file descriptor into its own file descriptor set? .IP The -.BR epoll_ctl (2) +.MR epoll_ctl 2 call fails .RB ( EINVAL ). However, you can add an @@ -445,14 +446,14 @@ interest lists? .IP Yes, but be aware of the following point. A file descriptor is a reference to an open file description (see -.BR open (2)). +.MR open 2 ). Whenever a file descriptor is duplicated via -.BR dup (2), -.BR dup2 (2), -.BR fcntl (2) +.MR dup 2 , +.MR dup2 2 , +.MR fcntl 2 .BR F_DUPFD , or -.BR fork (2), +.MR fork 2 , a new file descriptor referring to the same open file description is created. An open file description continues to exist until all @@ -467,19 +468,19 @@ events may be reported for that file descriptor if other file descriptors referring to the same underlying file description remain open. To prevent this happening, the file descriptor must be explicitly removed from the interest list (using -.BR epoll_ctl (2) +.MR epoll_ctl 2 .BR EPOLL_CTL_DEL ) before it is duplicated. Alternatively, the application must ensure that all file descriptors are closed (which may be difficult if file descriptors were duplicated behind the scenes by library functions that used -.BR dup (2) +.MR dup 2 or -.BR fork (2)). +.MR fork 2 ). .IP \[bu] If more than one event occurs between -.BR epoll_wait (2) +.MR epoll_wait 2 calls, are they combined or reported separately? .IP They will be combined. @@ -500,7 +501,7 @@ when using the flag (edge-triggered behavior)? .IP Receiving an event from -.BR epoll_wait (2) +.MR epoll_wait 2 should suggest to you that such file descriptor is ready for the requested I/O operation. You must consider it ready until the next (nonblocking) @@ -519,14 +520,14 @@ condition that the read/write I/O space is exhausted can also be detected by checking the amount of data read from / written to the target file descriptor. For example, if you call -.BR read (2) +.MR read 2 by asking to read a certain amount of data and -.BR read (2) +.MR read 2 returns a lower number of bytes, you can be sure of having exhausted the read I/O space for the file descriptor. The same is true when writing using -.BR write (2). +.MR write 2 . (Avoid this latter technique if you cannot guarantee that the monitored file descriptor always refers to a stream-oriented file.) .SS Possible pitfalls and ways to avoid them @@ -550,15 +551,15 @@ receive for file descriptors that are already ready. .B If using an event cache... .IP If you use an event cache or store all the file descriptors returned from -.BR epoll_wait (2), +.MR epoll_wait 2 , then make sure to provide a way to mark its closure dynamically (i.e., caused by a previous event's processing). Suppose you receive 100 events from -.BR epoll_wait (2), +.MR epoll_wait 2 , and in event #47 a condition causes event #13 to be closed. If you remove the structure and -.BR close (2) +.MR close 2 the file descriptor for event #13, then your event cache might still say there are events waiting for that file descriptor causing confusion. @@ -566,7 +567,7 @@ file descriptor causing confusion. One solution for this is to call, during the processing of event 47, .BR epoll_ctl ( EPOLL_CTL_DEL ) to delete file descriptor 13 and -.BR close (2), +.MR close 2 , then mark its associated data structure as removed and link it to a cleanup list. If you find another @@ -593,18 +594,18 @@ the epoll file descriptor in the process's .IR /proc/ pid /fdinfo directory. See -.BR proc (5) +.MR proc 5 for further details. .P The -.BR kcmp (2) +.MR kcmp 2 .B KCMP_EPOLL_TFD operation can be used to test whether a file descriptor is present in an epoll instance. .SH SEE ALSO -.BR epoll_create (2), -.BR epoll_create1 (2), -.BR epoll_ctl (2), -.BR epoll_wait (2), -.BR poll (2), -.BR select (2) +.MR epoll_create 2 , +.MR epoll_create1 2 , +.MR epoll_ctl 2 , +.MR epoll_wait 2 , +.MR poll 2 , +.MR select 2 |