POLL(2) | System Calls Manual | 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 * restrict timeout, const sigset_t * restrict 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. For example, on OpenBSD, the `POLLPRI` and `POLLRDBAND` flags may be used to detect when out-of-band socket data may be read without blocking.

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.

# IDIOMS

Care must be taken when converting code from select(2) to `poll`() as they have slightly different semantics. The first semantic difference is that, unlike select(2), `poll`() has a way of indicating that one or more file descriptors is invalid by setting a flag in the revents field of corresponding entry of fds, whereas select(2) returns an error (-1) if any of the descriptors with bits set in the fd_set are invalid. The second difference is that on EOF there is no guarantee that `POLLIN` will be set in revents, the caller must also check for `POLLHUP`. This differs from select(2) where EOF is considered as a read event.

Consider the following usage of select(2) that implements a read from the standard input with a 60 second time out:

    struct timeval timeout;
    fd_set readfds;
    char buf[BUFSIZ];
    int nready;

    timeout.tv_sec = 60;
    timeout.tv_usec = 0;
    FD_ZERO(&readfds);
    FD_SET(STDIN_FILENO, &readfds);
    nready = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &timeout);
    if (nready == -1)
    	err(1, "select");
    if (nready == 0)
    	errx(1, "time out");
    if (FD_ISSET(STDIN_FILENO, &readfds)) {
    	if (read(STDIN_FILENO, buf, sizeof(buf)) == -1)
    		err(1, "read");
    }

This can be converted to `poll`() as follows:

    struct pollfd pfd[1];
    char buf[BUFSIZ];
    int nready;

    pfd[0].fd = STDIN_FILENO;
    pfd[0].events = POLLIN;
    nready = poll(pfd, 1, 60 * 1000);
    if (nready == -1)
    	err(1, "poll");
    if (nready == 0)
    	errx(1, "time out");
    if (pfd[0].revents & (POLLERR|POLLNVAL))
    	errx(1, "bad fd %d", pfd[0].fd);
    if (pfd[0].revents & (POLLIN|POLLHUP)) {
    	if (read(STDIN_FILENO, buf, sizeof(buf)) == -1)
    		err(1, "read");
    }

# ERRORS

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

[`EAGAIN`]
  The kernel failed to allocate memory for temporary data structures; a later call may succeed.
[`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

clock_gettime(2), getrlimit(2), read(2), select(2), write(2)

# STANDARDS

The `poll`() and `ppoll`() functions conform to.

# HISTORY

A `poll`() system call appeared in AT&T System V Release 3 UNIX. The `ppoll`() function appeared in OpenBSD 5.4.

# CAVEATS

The `POLLWRBAND` flag is 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. Similarly, the `POLLPRI` and `POLLRDBAND` flags are also equivalent.

August 4, 2024 | Debian