poll(S)                        6 January 1993                        poll(S)


 Name

    poll - STREAMS input/output multiplexing

 Syntax


    cc  . . .  -lc


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

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


 Description

    The poll system call provides users with a mechanism for multiplexing
    input/output over a set of file descriptors that reference open STREAMS
    or any driver that supports the select(S) system call.  The poll system
    call identifies those STREAMS on which a user can send or receive mes-
    sages, or on which certain events have occurred.  A user can receive mes-
    sages using read(S) or getmsg(S) and can send messages using write(S) and
    putmsg(S).  Certain ioctl(S) calls, such as IRECVFD and ISENDFD, 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 or-ing any combination of the following event
    flags:

    POLLIN      A non-priority or file descriptor passing message (see
                IRECVFD) 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(S)), poll fails.

    If the value fd is less than zero, 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 speci-
    fied bits is set in revents when the poll call returns.  The event flags
    POLLHUP, POLLERR, and POLLNVAL are always set in revents if the condi-
    tions 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 descrip-
    tor, poll waits at least timeout msec for an event to occur on any of the
    selected file descriptors.  On a computer where millisecond timing accu-
    racy is not available, timeout is rounded up to the nearest legal value
    available on that system.  If the value 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.  The poll system
    call is not affected by the ONONBLOCK flag.

    The poll system call fails if one or more of the following is 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.

 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 non-
    zero).  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.

 Note

    The poll system call also works on devices that support the select system
    call, such as the event driver and the console driver.

 See also

    getmsg(S), Intro(S), putmsg(S), read(S), write(S), select(S),

 Standards conformance

    poll is conformant with:
    AT&T SVID Issue 2.