EPOLL(7)                  (2019-03-06)                   EPOLL(7)

     NAME
          epoll - I/O event notification facility

     SYNOPSIS
          #include <sys/epoll.h>

     DESCRIPTION
          The epoll API performs a similar task to poll(2): monitoring
          multiple file descriptors to see if I/O is possible on any
          of them.  The epoll API can be used either as an edge-
          triggered or a level-triggered interface and scales well to
          large numbers of watched file descriptors.

          The central concept of the epoll API is the epoll instance,
          an in-kernel data structure which, from a user-space per-
          spective, can be considered as a container for two lists:

          +o The interest list (sometimes also called the epoll set):
            the set of file descriptors that the process has regis-
            tered an interest in monitoring.

          +o The ready list: the set of file descriptors that are
            "ready" for I/O.  The ready list is a subset of (or, more
            precisely, a set of references to) the file descriptors in
            the interest list.  The ready list is dynamically popu-
            lated by the kernel as a result of I/O activity on those
            file descriptors.

          The following system calls are provided to create and manage
          an epoll instance:

          +o epoll_create(2) creates a new epoll instance and returns a
            file descriptor referring to that instance.  (The more
            recent epoll_create1(2) extends the functionality of
            epoll_create(2).)

          +o Interest in particular file descriptors is then registered
            via epoll_ctl(2), which adds items to the interest list of
            the epoll instance.

          +o epoll_wait(2) waits for I/O events, blocking the calling
            thread if no events are currently available.  (This system
            call can be thought of as fetching items from the ready
            list of the epoll instance.)

        Level-triggered and edge-triggered
          The epoll event 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 happens:

     Page 1                        Linux             (printed 5/24/22)

     EPOLL(7)                  (2019-03-06)                   EPOLL(7)

          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 delivers events only 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 write done in
          2 and the event is consumed in 3.  Since the read operation
          done in 4 does not consume the whole buffer data, the call
          to epoll_wait(2) done in step 5 might block indefinitely.

          An application that employs the EPOLLET flag should use non-
          blocking file descriptors to avoid having a blocking read or
          write starve a task that is handling multiple file descrip-
          tors.  The suggested way to use epoll as an edge-triggered
          (EPOLLET) interface is as follows:

          a) with nonblocking file descriptors; and

          b) by waiting for an event only after read(2) or write(2)
             return EAGAIN.

          By contrast, when used as a level-triggered interface (the
          default, when EPOLLET is not specified), epoll is simply a
          faster poll(2), and can be used wherever the latter is used
          since it shares the same semantics.

          Since even with edge-triggered epoll, multiple events can be
          generated upon receipt of multiple chunks of data, the
          caller has the option to specify the EPOLLONESHOT flag, to
          tell epoll to disable the associated file descriptor after
          the receipt of an event with epoll_wait(2).  When the
          EPOLLONESHOT flag is specified, it is the caller's responsi-
          bility to rearm the file descriptor using epoll_ctl(2) with
          EPOLL_CTL_MOD.

     Page 2                        Linux             (printed 5/24/22)

     EPOLL(7)                  (2019-03-06)                   EPOLL(7)

          If multiple threads (or processes, if child processes have
          inherited the epoll file descriptor across fork(2)) are
          blocked in epoll_wait(2) waiting on the same epoll file
          descriptor and a file descriptor in the interest list that
          is marked for edge-triggered (EPOLLET) notification becomes
          ready, just one of the threads (or processes) is awoken from
          epoll_wait(2).  This provides a useful optimization for
          avoiding "thundering herd" wake-ups in some scenarios.

        Interaction with autosleep
          If the system is in autosleep mode via /sys/power/autosleep
          and an event happens which wakes the device from sleep, the
          device driver will keep the device awake only until that
          event is queued.  To keep the device awake until the event
          has been processed, it is necessary to use the epoll_ctl(2)
          EPOLLWAKEUP flag.

          When the EPOLLWAKEUP flag is set in the events field for a
          struct epoll_event, the system will be kept awake from the
          moment the event is queued, through the epoll_wait(2) call
          which returns the event until the subsequent epoll_wait(2)
          call.  If the event should keep the system awake beyond that
          time, then a separate wake_lock should be taken before the
          second epoll_wait(2) call.

        /proc interfaces
          The following interfaces can be used to limit the amount of
          kernel memory consumed by epoll:

               htmlmanrefend/proc/sys/fs/epoll/max_user_watch

        html<H4>    html</H4>

        html<H4>    html</H4>

        html<H4>    html</H4>

     html<H4>    html</H4>

     html<H4>    html</H4>

                htmlmanrefstartkqueue,htmlmanrefendkqueue,
            htmlmanrefstart/dev/poll.htmlmanrefend/dev/poll.

     html<H4>    html</H4>

                htmlmanrefstart/proc/[pid]/fdinfohtmlmanrefend/proc/[pid]/fdinfo

     html<H4>    html</H4>

     html<H4>    html</H4>