Provided by: manpages-posix-dev_2017a-2_all bug

PROLOG

       This  manual  page  is part of the POSIX Programmer's Manual.  The Linux implementation of
       this interface may differ (consult the corresponding Linux  manual  page  for  details  of
       Linux behavior), or the interface may not be implemented on Linux.

NAME

       poll — input/output multiplexing

SYNOPSIS

       #include <poll.h>

       int poll(struct pollfd fds[], nfds_t nfds, int timeout);

DESCRIPTION

       The  poll()  function provides applications with a mechanism for multiplexing input/output
       over a set of file descriptors. For each member of the array pointed  to  by  fds,  poll()
       shall  examine the given file descriptor for the event(s) specified in events.  The number
       of pollfd structures in the fds array is specified by nfds.   The  poll()  function  shall
       identify  those  file  descriptors  on  which an application can read or write data, or on
       which certain events have occurred.

       The fds argument specifies the file descriptors to be examined and the events of  interest
       for  each  file descriptor. It is a pointer to an array with one member for each open file
       descriptor of interest.  The  array's  members  are  pollfd  structures  within  which  fd
       specifies  an  open  file  descriptor  and  events and revents are bitmasks constructed by
       OR'ing a combination of the following event flags:

       POLLIN      Data other than high-priority data may be read without blocking.

                   For STREAMS, this flag is set in revents  even  if  the  message  is  of  zero
                   length. This flag shall be equivalent to POLLRDNORM | POLLRDBAND.

       POLLRDNORM  Normal data may be read without blocking.

                   For  STREAMS,  data on priority band 0 may be read without blocking. This flag
                   is set in revents even if the message is of zero length.

       POLLRDBAND  Priority data may be read without blocking.

                   For STREAMS, data on priority  bands  greater  than  0  may  be  read  without
                   blocking. This flag is set in revents even if the message is of zero length.

       POLLPRI     High-priority data may be read without blocking.

                   For  STREAMS,  this  flag  is  set  in  revents even if the message is of zero
                   length.

       POLLOUT     Normal data may be written without blocking.

                   For STREAMS, data on priority band 0 may be written without blocking.

       POLLWRNORM  Equivalent to POLLOUT.

       POLLWRBAND  Priority data may be written.

                   For STREAMS, data on priority bands greater than  0  may  be  written  without
                   blocking.  If any priority band has been written to on this STREAM, this event
                   only examines bands that have been written to at least once.

       POLLERR     An error has occurred on the device or stream. This flag is only valid in  the
                   revents bitmask; it shall be ignored in the events member.

       POLLHUP     A  device has been disconnected, or a pipe or FIFO has been closed by the last
                   process that had it open for writing. Once set, the hangup  state  of  a  FIFO
                   shall persist until some process opens the FIFO for writing or until all read-
                   only file descriptors for the FIFO are closed.  This  event  and  POLLOUT  are
                   mutually-exclusive;  a  stream can never be writable if a hangup has occurred.
                   However, this event and POLLIN, POLLRDNORM, POLLRDBAND,  or  POLLPRI  are  not
                   mutually-exclusive.  This  flag is only valid in the revents bitmask; it shall
                   be ignored in the events member.

       POLLNVAL    The specified fd value is invalid. This flag is  only  valid  in  the  revents
                   member; it shall ignored in the events member.

       The  significance  and  semantics of normal, priority, and high-priority data are file and
       device-specific.

       If the value of fd is less than 0, events shall be ignored, and revents shall be set to  0
       in that entry on return from poll().

       In  each  pollfd  structure,  poll() shall clear the revents member, except that where the
       application requested a report on a condition by setting one of the bits of events  listed
       above,  poll()  shall  set  the corresponding bit in revents if the requested condition is
       true. In addition, poll() shall set the POLLHUP, POLLERR, and POLLNVAL flag in revents  if
       the  condition  is  true,  even  if  the  application did not set the corresponding bit in
       events.

       If none of the defined events have occurred on any selected file descriptor, poll()  shall
       wait  at  least  timeout  milliseconds  for  an event to occur on any of the selected file
       descriptors. If the value of timeout is 0, poll() shall return immediately. If  the  value
       of  timeout  is -1, poll() shall block until a requested event occurs or until the call is
       interrupted.

       Implementations may place limitations on the granularity  of  timeout  intervals.  If  the
       requested  timeout interval requires a finer granularity than the implementation supports,
       the actual timeout interval shall be rounded up to the next supported value.

       The poll() function shall not be affected by the O_NONBLOCK flag.

       The poll() function shall support regular files,  terminal  and  pseudo-terminal  devices,
       FIFOs,  pipes, sockets and STREAMS-based files.  The behavior of poll() on elements of fds
       that refer to other types of file is unspecified.

       Regular files shall always poll TRUE for reading and writing.

       A file descriptor for a socket that is listening for connections shall indicate that it is
       ready for reading, once connections are available.  A file descriptor for a socket that is
       connecting asynchronously shall indicate that it is ready for writing, once  a  connection
       has been established.

       Provided  the  application  does  not  perform  any  action that results in unspecified or
       undefined behavior, the value of the fd and events members of each element  of  fds  shall
       not be modified by poll().

RETURN VALUE

       Upon  successful  completion,  poll()  shall return a non-negative value. A positive value
       indicates the total number of pollfd structures that have selected events (that is,  those
       for  which the revents member is non-zero). A value of 0 indicates that the call timed out
       and no file descriptors have been selected. Upon failure, poll() shall return -1  and  set
       errno to indicate the error.

ERRORS

       The poll() function shall fail if:

       EAGAIN The  allocation  of  internal  data  structures failed but a subsequent request may
              succeed.

       EINTR  A signal was caught during poll().

       EINVAL The nfds argument is greater than {OPEN_MAX}, or one of the fd members refers to  a
              STREAM  or  multiplexer  that  is linked (directly or indirectly) downstream from a
              multiplexer.

       The following sections are informative.

EXAMPLES

   Checking for Events on a Stream
       The following example opens a pair of STREAMS devices and then waits  for  either  one  to
       become writable. This example proceeds as follows:

        1. Sets the timeout parameter to 500 milliseconds.

        2. Opens  the  STREAMS  devices  /dev/dev0 and /dev/dev1, and then polls them, specifying
           POLLOUT and POLLWRBAND as the events of interest.

           The STREAMS device names /dev/dev0 and /dev/dev1 are  only  examples  of  how  STREAMS
           devices  can be named; STREAMS naming conventions may vary among systems conforming to
           the POSIX.1‐2008.

        3. Uses the ret variable to determine whether an event has occurred on either of the  two
           STREAMS.  The  poll() function is given 500 milliseconds to wait for an event to occur
           (if it has not occurred prior to the poll() call).

        4. Checks the returned value of ret.  If  a  positive  value  is  returned,  one  of  the
           following can be done:

            a. Priority  data can be written to the open STREAM on priority bands greater than 0,
               because the POLLWRBAND event occurred on the open STREAM (fds[0] or fds[1]).

            b. Data can be written to the open STREAM on priority-band  0,  because  the  POLLOUT
               event occurred on the open STREAM (fds[0] or fds[1]).

        5. If  the  returned  value is not a positive value, permission to write data to the open
           STREAM (on any priority band) is denied.

        6. If the POLLHUP event occurs on the open STREAM (fds[0] or fds[1]), the device  on  the
           open STREAM has disconnected.

           #include <stropts.h>
           #include <poll.h>
           ...
           struct pollfd fds[2];
           int timeout_msecs = 500;
           int ret;
               int i;

           /* Open STREAMS device. */
           fds[0].fd = open("/dev/dev0", ...);
           fds[1].fd = open("/dev/dev1", ...);
           fds[0].events = POLLOUT | POLLWRBAND;
           fds[1].events = POLLOUT | POLLWRBAND;

           ret = poll(fds, 2, timeout_msecs);

           if (ret > 0) {
               /* An event on one of the fds has occurred. */
               for (i=0; i<2; i++) {
                   if (fds[i].revents & POLLWRBAND) {
                   /* Priority data may be written on device number i. */
           ...
                   }
                   if (fds[i].revents & POLLOUT) {
                   /* Data may be written on device number i. */
           ...
                   }
                   if (fds[i].revents & POLLHUP) {
                   /* A hangup has occurred on device number i. */
           ...
                   }
               }
           }

APPLICATION USAGE

       None.

RATIONALE

       The  POLLHUP event does not occur for FIFOs just because the FIFO is not open for writing.
       It only occurs when the FIFO is closed by the last writer and persists until some  process
       opens  the  FIFO  for  writing  or  until  all read-only file descriptors for the FIFO are
       closed.

FUTURE DIRECTIONS

       None.

SEE ALSO

       Section 2.6, STREAMS, getmsg(), pselect(), putmsg(), read(), write()

       The Base Definitions volume of POSIX.1‐2017, <poll.h>, <stropts.h>

COPYRIGHT

       Portions of this text are reprinted and  reproduced  in  electronic  form  from  IEEE  Std
       1003.1-2017,  Standard  for  Information Technology -- Portable Operating System Interface
       (POSIX), The Open Group Base Specifications Issue 7, 2018 Edition, Copyright (C)  2018  by
       the  Institute  of  Electrical  and Electronics Engineers, Inc and The Open Group.  In the
       event of any discrepancy between this version and the original IEEE  and  The  Open  Group
       Standard,  the  original  IEEE  and  The  Open Group Standard is the referee document. The
       original Standard can be obtained online at http://www.opengroup.org/unix/online.html .

       Any typographical or formatting errors that appear in this page are most  likely  to  have
       been  introduced  during  the conversion of the source files to man page format. To report
       such errors, see https://www.kernel.org/doc/man-pages/reporting_bugs.html .