POLL(2)

NAME
poll, ppoll - synchronous I/O multiplexing

SYNOPSIS
#include <poll.h>
int
poll(struct pollfd *fds, nfds_t nfds, int timeout);
int
ppoll(struct pollfd *fds, nfds_t nfds, const struct timespec *timeout, const sigset_t *mask);

DESCRIPTION
poll() provides a mechanism for multiplexing I/O across a set of file descriptors. It is similar in function to select(2). Unlike select(2), however, it is possible to only pass in data corresponding to the file descriptors for which events are wanted. This makes poll() more efficient than select(2) in most cases.

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. If fd is -1, the pollfd structure is considered unused, and revents will be cleared.

    The events and revents members are bitmasks of conditions to monitor and conditions found, respectively.

nfds
    An unsigned integer specifying the number of pollfd structures in the array.

timeout
    Maximum interval to wait for the poll to complete, in milliseconds. If this value is 0, poll() will return immediately. If this value is INFTIM (-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 may be read without blocking.

POLLRDNORM
    Normal data may be read without blocking.

POLLRDBAND
    Priority data may be read without blocking.

POLLNORM
    Same as POLLRDNORM. This flag is provided for source code compatibility with older programs and should not be used in new code.

POLLPRI
    High-priority data may be read without blocking.

POLLOUT
    Normal data may be written without blocking.

POLLWRNORM
    Same as POLLOUT.

POLLWRBAND
    Priority data may be written.

POLLERR
    An error has occurred on the device or socket. This flag is only valid in the revents bitmask; it is ignored in the events member.

POLLHUP
    The device or socket has been disconnected. This event and POLLOUT are mutually-exclusive; a descriptor 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 revents bitmask; it is ignored in the events member.

POLLNVAL
    The corresponding file descriptor is invalid. This flag is only valid in the revents bitmask; it is ignored in the events member.

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

In addition to I/O multiplexing, poll() can be used to generate simple timeouts. This functionality may be achieved by passing a null pointer for fds.

The ppoll() function is similar to poll() except that it specifies the timeout using a timespec structure, and a null pointer is used to specify an indefinite timeout instead of INFTIM. Also, if mask is a non-null pointer, ppoll() atomically sets the calling thread's signal mask to the signal set pointed to by mask for the duration of the function call. In this case, the original signal mask will be restored before ppoll() returns.

RETURN VALUES
Upon error, poll() and ppoll() return -1 and set the global variable errno to indicate the error. If the timeout interval was reached before any events occurred, they return 0. Otherwise, they return the number of pollfd structures for which revents is non-zero.

EXAMPLES
The following example implements a read from the standard input that times out after 60 seconds:

    #include <err.h>
    #include <poll.h>
    #include <stdio.h>
    #include <unistd.h>
    struct pollfd pfd[1];
    char buf[BUFSIZ];
    int nfds;
    pfd[0].fd = STDIN_FILENO;
    pfd[0].events = POLLIN;
    nfds = poll(pfd, 1, 60 * 1000);
    if (nfds == -1 || (pfd[0].revents & (POLLERR|POLLHUP|POLLNVAL)))
    	errx(1, "poll error");
    if (nfds == 0)
    	errx(1, "time out");
    if (read(STDIN_FILENO, buf, sizeof(buf)) == -1)
    	errx(1, "read");

ERRORS
poll() and ppoll() will fail if:

[EFAULT]
    fds points outside the process's allocated address space.

[EINTR]
    A signal was caught before any polled events occurred and before the timeout elapsed.

[EINVAL]
    nfds was greater than the number of available file descriptors.

[EINVAL]
    The timeout passed was invalid.

SEE ALSO
getrlimit(2), read(2), select(2), write(2)

STANDARDS
The poll() function is compliant with the xpg4.3 specification. The ppoll() function is a Linux extension.

HISTORY
A poll() system call appeared in AT&T UNIX. The ppoll() function appeared in OpenBSD 5.4.

BUGS
The POLLERR and POLLWRBAND flags are accepted but ignored by the kernel.

Because OpenBSD does not implement STREAMS, there is no distinction between some of the fields in the events and revents bitmasks. As a result, the POLLIN, POLLNORM, and POLLRDNORM flags are equivalent.

Internally to the kernel, poll() and ppoll() work poorly if multiple processes wait on the same file descriptor.