poll(3)                                                         poll(3)

  poll()

  NAME

    poll() - synchronous I/O multiplexing

  SYNOPSIS

    #include 

    int poll(struct pollfd *fds, int nfds, int timeout)

  DESCRIPTION

    The poll(3) function provides a mechanism for reporting I/O conditions
    across a set of file descriptors.

    The arguments are as follows:

    fds
        Points to an array of pollfd structures, which are defined as:
        struct pollfd {
                int fd;
                short events;
                short revents;
        };
        The fd member is an open file descriptor that refers to the file /
        proc/procID/ctl, where procID is the process ID of a process running
        on the system. (The poll function is not supported for use with other
        files.) The events and revents members are bitmasks of conditions to
        monitor and conditions found, respectively.

    nfds
        The number of pollfd structures in the fds array.

    timeout
        Maximum interval to wait for the poll to complete, in milliseconds. If
        this value is 0, the poll() will return immediately. If this value is
        -1, poll() will block indefinitely until a condition is found.

    The calling process sets the events bitmask and poll() sets the revents
    bitmask. Each call to poll() resets the revents bitmask for accuracy. The
    condition flags in the bitmasks are defined as:

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

    POLLRDNORM
        Normal data can be read without blocking.

    POLLRDBAND
        Data with a nonzero priority can be read without blocking.

    POLLPRI
        High priority data can be read without blocking.

    POLLOUT
        Data other than high priority data can be written without blocking.

    POLLWRNORM
        Normal data can be written without blocking.

    POLLWRBAND
        Data with a nonzero priority can be written without blocking.

    POLLERR
        An exceptional condition has occurred on the device or socket. This
        flag is always checked, even if not present in the events bitmask.

    POLLHUP
        The device or socket has been disconnected. This flag is always
        checked, even if not present in the events bitmask. NOte that POLLHUP
        and POLLOUT should never be present in the revents bitmask at the same
        time.

    POLLNVAL
        The file descriptor is not open. This flag is always checked, even if
        it is not present in the events bitmask.

    If timeout is neither zero nor -1, it specifies a maximum interval to wait
    for any file descriptor to become ready, in milliseconds. If timeout is -
    1, the poll blocks indefinitely. If timeout is zero, the poll() returns
    without blocking.

  RETURN VALUES

    The poll() function returns the number of descriptors that are ready for
    I/O, or -1 if an error occurred. If the time limit expires, poll() returns
    0. If poll() returns with an error, including one due to an interrupted
    call, the fds array will be unmodified.

  ERRORS

    [EFAULT]
        The fds argument points outside the allocated address space of the
        process.

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

  NOTE

    On Interix, poll() is supported only for use with ctl files (located in /
    proc/procID). No other file types are allowed.

  SEE ALSO

    accept(2)

    connect(2)

    read(2)

    recv(2)

    select(2)

    send(2)

  USAGE NOTES

    The poll function is thread safe.

    The poll function is async-signal safe.