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:

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.

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.

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.

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.

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:

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.

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