EPOLL(5)EPOLL(5)NAMEepoll - Linux-compatible I/O event notification facility
SYNOPSIS
#include <sys/epoll.h>
DESCRIPTIONepoll is a facility for efficient event-oriented I/O that has a similar
model to poll(2), but does not necessitate rescanning a set of file
descriptors to wait for an event. epoll is of Linux origins, and this
facility is designed to be binary-compatible with the Linux facility,
including the following interfaces:
o epoll_create(3C) creates an epoll instance, returning a file
descriptor. It contains a size arugment which is meaningful
only in as much as it cannot be 0.
o epoll_create1(3C) also creates an epoll instance, but elimi‐
nates the meaningless size argument -- replacing it instead
with a flags argument.
o epoll_ctl(3C) allows file descriptors to be added (via
EPOLL_CTL_ADD), deleted (via EPOLL_CTL_DEL) or modified (via
EPOLL_CTL_MOD) with respect to the epoll'd set of file
descriptors.
o epoll_wait(3C) fetches pending events for file descriptors
added via epoll_ctl(3C), blocking the caller if no such
events are pending.
o epoll_pwait(3C) opeates in a similar manner to
epoll_wait(3C), but allows the caller to specify a signal
mask to be set atomically with respect to waiting for
events.
NOTES
The epoll facility is implemented for purposes of offering compatibil‐
ity to and portability of Linux-borne applications; native applications
should continue to prefer using event ports via the port_create(3C),
port_associate(3C) and port_getn(3C) interfaces. In particular, use of
epoll in a multithreaded environment is fraught with peril; even when
using EPOLLONESHOT for one-shot events, there are race conditions with
respect to close(2) that are unresolvable. (For more details, see the
aborted effort in Linux to resolve this via the proposed EPOLL_CTL_DIS‐
ABLE operation.) The event port facility -- like the BSD kqueue facil‐
ity that inspired it -- is designed to deal with such issues via
explicit event source dissociation.
While a best effort has been made to mimic the Linux semantics, there
are some semantics that are too peculiar or ill-conceived to merit
accommodation. In particular, the Linux epoll facility will -- by
design -- continue to generate events for closed file descriptors
where/when the underlying file description remains open. For example,
if one were to fork(2) and subsequently close an actively epoll'd file
descriptor in the parent, any events generated in the child on the
implicitly duplicated file descriptor will continue to be delivered to
the parent -- despite the fact that the parent itself no longer has any
notion of the file description! This epoll facility refuses to honor
these semantics; closing the EPOLL_CTL_ADD'd file descriptor will
always result in no further events being generated for that event
description.
SEE ALSOepoll_create(3C), epoll_create1(3C), epoll_ctl(3C), epoll_wait(3C),
epoll_pwait(3C), port_create(3C), port_associate(3C), port_dissoci‐
ate(3C), port_get(3C), pselect(3C)
Apr 17, 2014 EPOLL(5)
