POLL(3)                    POSIX Programmer's Manual                   POLL(3)



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


NNAAMMEE
       poll -- input/output multiplexing

SSYYNNOOPPSSIISS
       #include <poll.h>

       int poll(struct pollfd _f_d_s[], nfds_t _n_f_d_s, int _t_i_m_e_o_u_t);

DDEESSCCRRIIPPTTIIOONN
       The _p_o_l_l() 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 _f_d_s, _p_o_l_l() shall examine the given
       file descriptor for the event(s) specified in _e_v_e_n_t_s.  The number of
       ppoollllffdd structures in the _f_d_s array is specified by _n_f_d_s.  The _p_o_l_l()
       function shall identify those file descriptors on which an application
       can read or write data, or on which certain events have occurred.

       The _f_d_s 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 ppoollllffdd structures within which _f_d specifies an open
       file descriptor and _e_v_e_n_t_s and _r_e_v_e_n_t_s 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 _r_e_v_e_n_t_s 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 _r_e_v_e_n_t_s 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 _r_e_v_e_n_t_s even if
                   the message is of zero length.

       POLLPRI     High-priority data may be read without blocking.

                   For STREAMS, this flag is set in _r_e_v_e_n_t_s 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 _r_e_v_e_n_t_s bitmask; it shall be ignored in
                   the _e_v_e_n_t_s 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 _r_e_v_e_n_t_s
                   bitmask; it shall be ignored in the _e_v_e_n_t_s member.

       POLLNVAL    The specified _f_d value is invalid. This flag is only valid
                   in the _r_e_v_e_n_t_s member; it shall ignored in the _e_v_e_n_t_s
                   member.

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

       If the value of _f_d is less than 0, _e_v_e_n_t_s shall be ignored, and _r_e_v_e_n_t_s
       shall be set to 0 in that entry on return from _p_o_l_l().

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

       If none of the defined events have occurred on any selected file
       descriptor, _p_o_l_l() shall wait at least _t_i_m_e_o_u_t milliseconds for an
       event to occur on any of the selected file descriptors. If the value of
       _t_i_m_e_o_u_t is 0, _p_o_l_l() shall return immediately. If the value of _t_i_m_e_o_u_t
       is -1, _p_o_l_l() 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 _p_o_l_l() function shall not be affected by the O_NONBLOCK flag.

       The _p_o_l_l() function shall support regular files, terminal and pseudo-
       terminal devices, FIFOs, pipes, sockets and STREAMS-based files.  The
       behavior of _p_o_l_l() on elements of _f_d_s 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.

RREETTUURRNN VVAALLUUEE
       Upon successful completion, _p_o_l_l() shall return a non-negative value. A
       positive value indicates the total number of file descriptors that have
       been selected (that is, file descriptors for which the _r_e_v_e_n_t_s member
       is non-zero). A value of 0 indicates that the call timed out and no
       file descriptors have been selected. Upon failure, _p_o_l_l() shall return
       -1 and set _e_r_r_n_o to indicate the error.

EERRRROORRSS
       The _p_o_l_l() function shall fail if:

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

       EEIINNTTRR  A signal was caught during _p_o_l_l().

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

       _T_h_e _f_o_l_l_o_w_i_n_g _s_e_c_t_i_o_n_s _a_r_e _i_n_f_o_r_m_a_t_i_v_e_.

EEXXAAMMPPLLEESS
   CChheecckkiinngg ffoorr EEvveennttss oonn aa SSttrreeaamm
       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 _t_i_m_e_o_u_t parameter to 500 milliseconds.

        2. Opens the STREAMS devices //ddeevv//ddeevv00 and //ddeevv//ddeevv11, and then polls
           them, specifying POLLOUT and POLLWRBAND as the events of interest.

           The STREAMS device names //ddeevv//ddeevv00 and //ddeevv//ddeevv11 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 _r_e_t variable to determine whether an event has occurred on
           either of the two STREAMS. The _p_o_l_l() function is given 500
           milliseconds to wait for an event to occur (if it has not occurred
           prior to the _p_o_l_l() call).

        4. Checks the returned value of _r_e_t.  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 (_f_d_s[0] or _f_d_s[1]).

            b. Data can be written to the open STREAM on priority-band 0,
               because the POLLOUT event occurred on the open STREAM (_f_d_s[0]
               or _f_d_s[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 (_f_d_s[0] or _f_d_s[1]),
           the device on the open STREAM has disconnected.

           ##iinncclluuddee <<ssttrrooppttss..hh>>
           ##iinncclluuddee <<ppoollll..hh>>
           ......
           ssttrruucctt ppoollllffdd ffddss[[22]];;
           iinntt ttiimmeeoouutt__mmsseeccss == 550000;;
           iinntt rreett;;
               iinntt ii;;

           /* 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. */
           ...
                   }
               }
           }

AAPPPPLLIICCAATTIIOONN UUSSAAGGEE
       None.

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

FFUUTTUURREE DDIIRREECCTTIIOONNSS
       None.

SSEEEE AALLSSOO
       _S_e_c_t_i_o_n _2_._6, _S_T_R_E_A_M_S, _g_e_t_m_s_g(), _p_s_e_l_e_c_t(), _p_u_t_m_s_g(), _r_e_a_d(), _w_r_i_t_e()

       The Base Definitions volume of POSIX.1-2008, <<ppoollll..hh>>, <<ssttrrooppttss..hh>>

CCOOPPYYRRIIGGHHTT
       Portions of this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX), The Open Group Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of
       Electrical and Electronics Engineers, Inc and The Open Group.  (This is
       POSIX.1-2008 with the 2013 Technical Corrigendum 1 applied.) 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.unix.org/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 .



IEEE/The Open Group                  2013                              POLL(3)
