Description

   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.