Linux Programmer’s Manual
epoll − I/O event notification facility
epoll is a variant of poll(2) that can be used either as an edge-triggered or a level-triggered interface and
scales well to large numbers of watched file descriptors. The following system calls are provided to create
and manage an epoll instance:
* An epoll instance created by epoll_create(2), which returns a file descriptor referring to the epoll
instance. (The more recent epoll_create1(2) extends the functionality of epoll_create(2).)
Interest in particular file descriptors is then registered via epoll_ctl(2). The set of file descriptors cur-
rently registered on an epoll instance is sometimes called an epoll set.
* Finally, the actual wait is started by epoll_wait(2).
Level-Triggered and Edge-Triggered
The epoll ev ent distribution interface is able to behave both as edge-triggered (ET) and as level-triggered
(LT). The difference between the two mechanisms can be described as follows. Suppose that this scenario
1. The file descriptor that represents the read side of a pipe (rfd) is registered on the epoll instance.
2. A pipe writer writes 2 kB of data on the write side of the pipe.
3. A call to epoll_wait(2) is done that will return rfd as a ready file descriptor.
4. The pipe reader reads 1 kB of data from rfd .
5. A call to epoll_wait(2) is done.
If the rfd file descriptor has been added to the epoll interface using the EPOLLET (edge-triggered) flag,
the call to epoll_wait(2) done in step 5 will probably hang despite the available data still present in the file
input buffer; meanwhile the remote peer might be expecting a response based on the data it already sent.
The reason for this is that edge-triggered mode only delivers events when changes occur on the monitored
file descriptor. So, in step 5 the caller might end up waiting for some data that is already present inside the
input buffer. In the above example, an event on rfd will be generated because of the writ