1 EPOLL(5)              Standards, Environments, and Macros             EPOLL(5)
   2 
   3 
   4 
   5 NAME
   6        epoll - Linux-compatible I/O event notification facility
   7 
   8 SYNOPSIS
   9        #include <sys/epoll.h>
  10 
  11 
  12 DESCRIPTION
  13        epoll is a facility for efficient event-oriented I/O that has a similar
  14        model to poll(2), but does not necessitate rescanning a set of file
  15        descriptors to wait for an event.  epoll is of Linux origins, and this
  16        facility is designed to be binary-compatible with the Linux facility,
  17        including the following interfaces:
  18 
  19 
  20            o      epoll_create(3C) creates an epoll instance, returning a file
  21                   descriptor. It contains a size argument which is meaningful
  22                   only in as much as it cannot be 0.
  23 
  24            o      epoll_create1(3C) also creates an epoll instance, but
  25                   eliminates the meaningless size argument -- replacing it
  26                   instead with a flags argument.
  27 
  28            o      epoll_ctl(3C) allows file descriptors to be added (via
  29                   EPOLL_CTL_ADD), deleted (via EPOLL_CTL_DEL) or modified (via
  30                   EPOLL_CTL_MOD) with respect to the epoll'd set of file
  31                   descriptors.
  32 
  33            o      epoll_wait(3C) fetches pending events for file descriptors
  34                   added via epoll_ctl(3C), blocking the caller if no such
  35                   events are pending.
  36 
  37            o      epoll_pwait(3C) operates in a similar manner to
  38                   epoll_wait(3C), but allows the caller to specify a signal
  39                   mask to be set atomically with respect to waiting for
  40                   events.
  41 
  42 
  43 
  44 NOTES
  45        The epoll facility is implemented for purposes of offering
  46        compatibility to and portability of Linux-borne applications; native
  47        applications should continue to prefer using event ports via the
  48        port_create(3C), port_associate(3C) and port_getn(3C) interfaces.  In
  49        particular, use of epoll in a multithreaded environment is fraught with
  50        peril; even when using EPOLLONESHOT for one-shot events, there are race
  51        conditions with respect to close(2) that are unresolvable.  (For more
  52        details, see the aborted effort in Linux to resolve this via the
  53        proposed EPOLL_CTL_DISABLE operation.)  The event port facility -- like
  54        the BSD kqueue facility that inspired it -- is designed to deal with
  55        such issues via explicit event source dissociation.
  56 
  57        While a best effort has been made to mimic the Linux semantics, there
  58        are some semantics that are too peculiar or ill-conceived to merit
  59        accommodation.  In particular, the Linux epoll facility will -- by
  60        design -- continue to generate events for closed file descriptors
  61        where/when the underlying file description remains open.  For example,
  62        if one were to fork(2) and subsequently close an actively epoll'd file
  63        descriptor in the parent, any events generated in the child on the
  64        implicitly duplicated file descriptor will continue to be delivered to
  65        the parent -- despite the fact that the parent itself no longer has any
  66        notion of the file description!  This epoll facility refuses to honor
  67        these semantics; closing the EPOLL_CTL_ADD'd file descriptor will
  68        always result in no further events being generated for that event
  69        description.
  70 
  71 
  72 SEE ALSO
  73        epoll_create(3C), epoll_create1(3C), epoll_ctl(3C), epoll_wait(3C),
  74        epoll_pwait(3C), port_create(3C), port_associate(3C),
  75        port_dissociate(3C), port_get(3C), pselect(3C)
  76 
  77 
  78 
  79                                  May 16, 2020                         EPOLL(5)