EPOLL(7) Standards, Environments, and Macros EPOLL(7)

NAME

epoll - Linux-compatible I/O event notification facility

SYNOPSIS

#include <sys/epoll.h>

DESCRIPTION

epoll 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 argument which is
meaningful only in as much as it cannot be 0.

o epoll_create1(3C) also creates an epoll instance, but
eliminates 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) operates 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
compatibility 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_DISABLE operation.) The event port
facility -- like the BSD kqueue facility 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 ALSO

epoll_create(3C), epoll_create1(3C), epoll_ctl(3C), epoll_pwait(3C),
epoll_wait(3C), port_associate(3C), port_create(3C),
port_dissociate(3C), port_get(3C), pselect(3C)

May 16, 2020 EPOLL(7)