POLL(2)                              SysV                              POLL(2)



NAME
     poll - STREAMS input/output multiplexing

SYNOPSIS
     #include <stropts.h>
     #include <poll.h>

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

DESCRIPTION
     poll provides users with a mechanism for multiplexing input/output over a
     set of file descriptors that reference open Streams (see intro(2)).  poll
     identifies those Streams on which a user can send or receive messages, or
     on which certain events have occurred.  A user can receive messages by
     using read(2) or getmsg(2) and can send messages by using write(2) and
     putmsg(2).  Certain ioctl(2) calls, such as I_RECVFD and I_SENDFD (see
     streamio(7)), can also be used to receive and send messages.

     fds 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
     element for each open file descriptor of interest.  The array's elements
     are pollfd structures which contain the following members:

          int fd;         /* file descriptor */
          short events;   /* requested events */
          short revents;  /* returned events */

     where fd specifies an open file descriptor and events and revents are
     bitmasks constructed by ORing any combination of the following event
     flags:

     POLLIN    A non-priority or file descriptor passing message (see
               I_RECVFD) is present on the Stream head read queue.  This flag
               is set even if the message is of zero length.  In revents, this
               flag is mutually exclusive with POLLPRI.

     POLLPRI   A priority message is present on the Stream head read queue.
               This flag is set even if the message is of zero length.  In
               revents, this flag is mutually exclusive with POLLIN.

     POLLOUT   The first downstream write queue in the Stream is not full.
               Priority control messages can be sent (see putmsg) at any time.

     POLLERR   An error message has arrived at the Stream head.  This flag is
               only valid in the revents bitmask; it is not used in the events
               field.

     POLLHUP   A hangup has occurred on the Stream.  This event and POLLOUT
               are mutually exclusive; a Stream can never be writable if a
               hangup has occurred.  However, this event and POLLIN or POLLPRI
               are not mutually exclusive.  This flag is only valid in the
               revents bitmask; it is not used in the events field.

     POLLNVAL  The specified fd value does not belong to an open Stream.  This
               flag is only valid in the revents field; it is not used in the
               events field.

     For each element of the array pointed to by fds, poll examines the given

     file descriptor for the event(s) specified in events.  The number of file
     descriptors to be examined is specified by nfds.  If nfds exceeds
     NOFILES, the system limit of open files (see ulimit(2)), poll will fail.

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

     The results of the poll query are stored in the revents field in the
     pollfd structure.  Bits are set in the revents bitmask to indicate which
     of the requested events are true.  If none are true, none of the
     specified bits is set in revents when the poll call returns.  The event
     flags POLLHUP, POLLERR and POLLNVAL are always set in revents if the
     conditions they indicate are true; this occurs even though these flags
     were not present in events.

     If none of the defined events have occurred on any selected file
     descriptor, poll waits at least timeout msec for an event to occur on any
     of the selected file descriptors.  On a computer where millisecond timing
     accuracy is not available, timeout is rounded up to the nearest legal
     value available on that system.  If the value of timeout is 0, poll
     returns immediately.  If the value of timeout is -1, poll blocks until a
     requested event occurs or until the call is interrupted.  poll is not
     affected by the O_NDELAY flag.

ERRORS
     poll fails if one or more of the following are true:

     [EAGAIN]   Allocation of internal data structures failed but request
                should be attempted again.

     [EFAULT]   Some argument points outside the allocated address space.

     [EINTR]    A signal was caught during the poll system call.

     [EINVAL]   The argument nfds is less than zero, or nfds is greater than
                NOFILES.

SEE ALSO
     intro(2), read(2), getmsg(2), putmsg(2), write(2).
     streamio(7) in Managing SysV System Software.
     Getting Started with SysV STREAMS, Programming with SysV STREAMS.

DIAGNOSTICS
     Upon successful completion, a non-negative value is returned.  A positive
     value indicates the total number of file descriptors that has been
     selected (that is, file descriptors for which the revents field is
     nonzero).  A value of 0 indicates that the call timed out and no file
     descriptors have been selected.  Upon failure, a value of -1 is returned
     and errno is set to indicate the error.