---
name: "poll"
section: "2"
platform: "macos"
package: "xnu"
version: "12377.121.6"
release: "macOS 26.5"
platforms: ["linux", "freebsd", "macos"]
url: "https://new.carta.tech/poll"
---

# poll(2)

synchronous I/O multiplexing

## NAME

**poll** – synchronous I/O multiplexing

## SYNOPSIS

**#include \<poll.h\>**

*int*\

**poll**(*struct pollfd fds\[\]*, *nfds\_t nfds*, *int timeout*);

## DESCRIPTION

**poll**() examines a set of file descriptors to see if some of them are ready for I/O or if certain events have occurred on them. The *fds* argument is a pointer to an array of pollfd structures, as defined in ⟨*poll.h*⟩ (shown below).  The *nfds* argument specifies the size of the *fds* array.

```
struct pollfd {
    int    fd;       /* file descriptor */
    short  events;   /* events to look for */
    short  revents;  /* events returned */
};
```

The fields of *struct*, *pollfd* are as follows:

- fd

  File descriptor to poll.

- events

  Events to poll for.  (See below.)

- revents

  Events which may occur or have occurred.  (See below.)

The event bitmasks in *events* and *revents* have the following bits:

- POLLERR

  An exceptional condition has occurred on the device or socket. This flag is output only, and ignored if present in the input *events* bitmask.

- POLLHUP

  The device or socket has been disconnected. This flag is output only, and ignored if present in the input *events* bitmask. Note that POLLHUP and POLLOUT are mutually exclusive and should never be present in the *revents* bitmask at the same time.

- POLLIN

  Data other than high priority data may be read without blocking. This is equivalent to ( POLLRDNORM \| POLLRDBAND ).

- POLLNVAL

  The file descriptor is not open. This flag is output only, and ignored if present in the input *events* bitmask.

- POLLOUT

  Normal data may be written without blocking. This is equivalent to POLLWRNORM.

- POLLPRI

  High priority data may be read without blocking.

- POLLRDBAND

  Priority data may be read without blocking.

- POLLRDNORM

  Normal data may be read without blocking.

- POLLWRBAND

  Priority data may be written without blocking.

- POLLWRNORM

  Normal data may be written without blocking.

The distinction between normal, priority, and high-priority data is specific to particular file types or devices.

If *timeout* is greater than zero, it specifies a maximum interval (in milliseconds) to wait for any file descriptor to become ready. If *timeout* is zero, then **poll**() will return without blocking. If the value of *timeout* is -1, the poll blocks indefinitely.

## RETURN VALUES

**poll**() 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 and the global variable *errno* will be set to indicate the error.

## ERRORS

**poll**() will fail if:

- \[EAGAIN\]

  Allocation of internal data structures fails. A subsequent request may succeed.

- \[EFAULT\]

  *Fds* points outside the process's allocated address space.

- \[EINTR\]

  A signal is delivered before the time limit expires and before any of the selected events occurs.

- \[EINVAL\]

  The *nfds* argument is greater than OPEN\_MAX or the *timeout* argument is less than -1.

## BUGS

The **poll**() system call currently does not support devices.

## SEE ALSO

[accept(2)](/accept/2.md), [connect(2)](/connect/2.md), [connectx(2)](/connectx/2.md), [kevent(2)](/kevent/2.md), [read(2)](/read/2.md), [recv(2)](/recv/2.md), [select(2)](/select/2.md), [send(2)](/send/2.md), [write(2)](/write/2.md)

## HISTORY

The **poll**() function call appeared in AT&T System V UNIX.