The poll function provides users with a mechanism for
    multiplexing input/output over a set of file descriptors that
    reference open streams. For each member of the array pointed
    to by filedes, poll examines the given file descriptor for the
    event(s) specified in events. The poll function identifies those
    streams on which an application can send or receive messages, or
    on which certain events have occurred.

    The filedes parameter specifies the file descriptor to be
    examined and the events of interest for each file descriptor.
    It is a pointer to an array of pollfd structures. The fd member
    of each pollfd structure specifies an open file descriptor. The
    poll function uses the events member to determine what conditions
    to report for this file descriptor. If one or more of these
    conditions is true, the poll function sets the associated revents
    member.

    The events and revents members of each pollfd structure are
    bitmasks. The calling process sets the events bitmask, and poll
    sets the revents bitmasks. These bitmasks contain inclusive
    ORed combinations of condition options. The following condition
    options are defined:

       POLLERR - An error has occurred on the file descriptor. This
       option is only valid in the revents bitmask; it is not used in
       the events member.

       For STREAMS devices, if an error occurs on the file descriptor
       and the device is also disconnected, poll returns POLLERR;
       POLLERR takes precedence over POLLHUP.

       POLLHUP - The device has been disconnected. This event
       is mutually exclusive with POLLOUT; a stream can never be
       writable if a hangup occurred. However, this event and POLLIN,
       POLLRDNORM, POLLRDBAND or POLLPRI are not mutually exclusive.
       This option is only valid in the revents bitmask; it is
       ignored in the events member.

       POLLIN - Data other than high-priority data may be read
       without blocking. This option is set in revents even if the
       message is of zero length. In revents, this option is mutually
       exclusive with POLLPRI.

       POLLNVAL - The value specified for fd is invalid. This option
       is only valid in the revents member; it is ignored in the
       events member.

       POLLOUT - Normal (priority band equals 0) data may be written
       without blocking.

       POLLPRI - High-priority data may be received without blocking.
       This option is set in revents even if the message is of zero
       length. In revents, this option is mutually exclusive with
       POLLIN.

       POLLRDBAND - Data from a nonzero priority band may be read
       without blocking. This option is set in revents even if the
       message is of zero length.

       POLLRDNORM - Normal data (priority band equals 0) may be read
       without blocking. This option is set in revents even if the
       message is of zero length.

       POLLWRBAND - Priority data (priority band greater than 0)
       may be written. This event only examines bands that have been
       written to at least once.

       POLLWRNORM - Same as POLLOUT.

    The poll function ignores any pollfd structure whose fd member
    is less than 0 (zero). If the fd member of all pollfd structures
    is less than 0, the poll function will return 0 and have no other
    results.

    The conditions indicated by POLLNORM and POLLOUT are true if and
    only if at least one byte of data can be read or written without
    blocking. There are two exceptions: regular files, which always
    poll true for POLLNORM and POLLOUT, and pipes, when the rules
    for the operation specify to return zero in order to indicate
    end-of-file.

    The condition options POLLERR, POLLHUP, and POLLNVAL are always
    set in revents if the conditions they indicate are true for the
    specified file descriptor, whether or not these options are set
    in events.

    For each call to the poll function, the set of reportable
    conditions for each file descriptor consists of those conditions
    that are always reported, together with any further conditions
    for which options are set in events. If any reportable condition
    is true for any file descriptor, the poll function will return
    with options set in revents for each true condition for that file
    descriptor.

    If no reportable condition is true for any of the file
    descriptors, the poll function waits up to timeout milliseconds
    for a reportable condition to become true. If, in that time
    interval, a reportable condition becomes true for any of the file
    descriptors, poll reports the condition in the file descriptor's
    associated revents member and returns. If no reportable condition
    becomes true, poll returns without setting any revents bitmasks.

    If the timeout parameter is a value of -1, the poll function does
    not return until at least one specified event has occurred. If
    the value of the timeout parameter is 0 (zero), the poll function
    does not wait for an event to occur but returns immediately, even
    if no specified event has occurred.

    The behavior of the poll function is not affected by whether
    the O_NONBLOCK option is set on any of the specified file
    descriptors.

    The poll function supports regular files, terminal and pseudo-
    terminal devices, STREAMS-based files, FIFOs, and pipes. The
    behavior of poll on elements of file descriptors that refer to
    other types of files is unspecified.

    For sockets, a file descriptor for a socket that is listening for
    connections indicates it is ready for reading after connections
    are available. A file descriptor for a socket that is connecting
    asynchronously indicates it is ready for writing after a
    connection is established.