POLL(2)                   NetBSD Programmer's Manual                   POLL(2)

NNAAMMEE
     ppoollll - synchronous I/O multiplexing

SSYYNNOOPPSSIISS
     ##iinncclluuddee <<ssyyss//ttyyppeess..hh>>
     ##iinncclluuddee <<ppoollll..hh>>

     _i_n_t
     ppoollll(_s_t_r_u_c_t _p_o_l_l_f_d _*_f_d_s, _u_n_s_i_g_n_e_d _i_n_t _n_f_d_s, _i_n_t _t_i_m_e_o_u_t);

DDEESSCCRRIIPPTTIIOONN
     PPoollll() examines a set of file descriptors to see if some of them are
     ready for I/O.  The _f_d_s argument is a pointer to an array of pollfd
     structures as defined in <_p_o_l_l_._h> (shown below).  The _n_f_d_s argument de-
     termines the size of the _f_d_s array.

     struct pollfd {
         int    fd;       /* file descriptor */
         short  events;   /* events to look for */
         short  revents;  /* events returned */
     };

     The fields of _s_t_r_u_c_t _p_o_l_l_f_d are as follows:

     fd          File descriptor to poll.

     events      Events to poll for.  (See below.)

     revents     Events which may occur.  (See below.)

     The event bitmasks in _e_v_e_n_t_s and _r_e_v_e_n_t_s have the following bits:

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

     POLLRDNORM     Normal data may be read without blocking.

     POLLRDBAND     Data with a non-zero priority may be read without block-
                    ing.

     POLLPRI        High priority data may be read without blocking.

     POLLOUT

     POLLWRNORM     Normal data may be written without blocking.

     POLLWRBAND     Data with a non-zero priority may be written without
                    blocking.

     POLLERR        An exceptional condition has occured on the device or
                    socket.  This flag is always checked, even if not present
                    in the _e_v_e_n_t_s bitmask.

     POLLHUP        The device or socket has been disconnected.  This flag is
                    always checked, even if not present in the _e_v_e_n_t_s bitmask.
                    Note that POLLHUP and POLLOUT should never be present in
                    the _r_e_v_e_n_t_s bitmask at the same time.

     POLLNVAL       The file descriptor is not open.  This flag is always
                    checked, even if not present in the _e_v_e_n_t_s bitmask.

     If _t_i_m_e_o_u_t is neither zero nor INFTIM (-1), it specifies a maximum inter-
     val to wait for any file descriptor to become ready, in milliseconds.  If
     _t_i_m_e_o_u_t is INFTIM (-1), the poll blocks indefinitely.  If _t_i_m_e_o_u_t is ze-
     ro, then ppoollll() will return without blocking.

RREETTUURRNN VVAALLUUEESS
     PPoollll() returns the number of descriptors that are ready for I/O, or -1 if
     an error occured.  If the time limit expires, ppoollll() returns 0.  If
     ppoollll() returns with an error, including one due to an interrupted call,
     the _f_d_s array will be unmodified.

CCOOMMPPAATTIIBBIILLIITTYY
     This implementation differs from the historical one in that a given file
     descriptor may not cause ppoollll() to return with an error.  In cases where
     this would have happened in the historical implementation (e.g. trying to
     poll a revoke(2)ed  descriptor), this implementation instead copies the
     _e_v_e_n_t_s bitmask to the _r_e_v_e_n_t_s bitmask.  Attempting to perform I/O on this
     descriptor will then return an error.  This behaviour is believed to be
     more useful.

EERRRROORRSS
     An error return from ppoollll() indicates:

     [EFAULT]      _F_d_s points outside the process's allocated address space.

     [EINTR]       A signal was delivered before the time limit expired and
                   before any of the selected events occurred.

     [EINVAL]      The specified time limit is negative.

SSEEEE AALLSSOO
     accept(2),  connect(2),  read(2),  recv(2),  select(2),  send(2),
     write(2)

BBUUGGSS
     The distinction between some of the fields in the _e_v_e_n_t_s and _r_e_v_e_n_t_s bit-
     masks is really not useful without STREAMS.  The fields are defined for
     compatibility with existing software.

HHIISSTTOORRYY
     The ppoollll() function call appeared in AT&T System V.3 UNIX.

NetBSD 1.3                     September 7, 1996                             2
