te Copyright (c) 2014, Joyent, Inc. All Rights Reserved. This file and its contents are supplied under the terms of the Common Development and Distribution License ("CDDL"), version 1.0. You may only use this file in accordance with the terms of version 1.0 of the CDDL. A full copy of the text of the CDDL should have accompanied this source. A copy of the CDDL is also available via the Internet at http://www.illumos.org/license/CDDL. EPOLL 7 "May 16, 2020"
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:
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.
epoll_create1(3C) also creates an epoll instance, but eliminates
the meaningless size argument -- replacing it instead with a flags
argument.
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.
epoll_wait(3C) fetches pending events for file descriptors added
via epoll_ctl(3C), blocking the caller if no such events are pending.
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)