# poll

## 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.
    


* * *