9.52 poll ¶

#define POLLIN   0b00000001
#define POLLOUT  0b00000010
#define POLLPRI  0b00000100
#define POLLHUP  0b00001000
#define POLLERR  0b00010000
#define POLLNVAL 0b01000000

struct pollfd {
   uint32_t fd;
   uint16_t events;
   uint16_t revents;
};

int poll(struct pollfd *fds, nfds_t nfds, struct timespec *timeout);

This syscall allows to wait for a series of events to happen to the passed FDs, in a manner similar to POSIX’s select.

fds is an array of nfds length of pollfd structures. Each structure represents one FD, for which events is a list of events to wait for and revents is a bitmap written by the kernel to indicate which events of the waited ones did happen. If the FD of an structure is negative, that is, it has the first bit set, it is ignored, and revents is set to 0.

If passed no FDs to poll, that is, with nfds == 0, poll will block for timeout time. This is used by some software as a means to implement sleep functionality, for those cases, clock_nanosleep.

Both events and revents are bitmaps of the values:

POLLIN

The passed FD has data pending for reading.

POLLOUT

The passed FD will not block when written to.

POLLPRI

The passed FD has prioritary data for processing, this data depends on what is polled, some examples are a change of termios information on a PTY, or Out-Of-Band (OOB) data for a TCP socket.

POLLERR

Only for revents, it is set when encountering an error waiting. This bit is also set for FDs referring to the write end of a pipe when the read end has been closed.

POLLHUP

Only for revents, it is set in the case of the passed FD having lost connection, or the FD being the reader end of a broken pipe.

POLLNVAL

Only for revents, equivalent of EBADFD, that is, the passed FD is not valid.

The call will block until either a file descriptor gets an event, the call is interrupted by a signal handler, or the timeout expires.

The syscall returns the number of FDs to have an event happen on success or -1 on failure, with the following errno:

EFAULT

The passed pointers are not in addressable memory.

EINVAL

The passed values are not valid.