The poll() function provides applications with a
mechanism for multiplexing input/output over a set of file descriptors.

The fds argument is an array of pollfd structures:

struct pollfd {
int fd;
short events;
short revents;
};

The members are:

fd

The file descriptor to be examined.

events

Flags that indicate the type of events to look for.

revents

Returned event flags.

For each member of the array pointed to by fds,
poll() examines the given file descriptor for the
event(s) specified in events.
The number of pollfd structures in the fds array is
specified by nfds. The array's
members are pollfd structures within which fd
specifies an open file descriptor, and events and
revents are bitmasks constructed by ORing a
combination of the following event flags:

POLLERR

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

POLLHUP

The device has been disconnected. This event and POLLOUT are
mutually exclusive; a device can never be writable if a hangup has
occurred. However, this event and POLLIN,
POLLRDNORM, POLLRDBAND, or
POLLPRI are not mutually exclusive. If the remote end of a
socket is closed, poll() indicates a POLLIN event
rather than POLLHUP. This flag is valid only in the
revents bitmask; it's ignored in the events member.

POLLIN

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

POLLNVAL

The specified fd value is invalid. This flag is valid only in
the revents member; it's ignored in the events member.

POLLOUT

Normal data may be written without blocking.

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.

POLLWRNORM

Equivalent to POLLOUT.

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

If the value of fd is less than 0, events is ignored,
and revents is set to 0 in that entry on return from poll().

In each pollfd structure, poll() clears the
revents member, except that where the application requested
a report on a condition by setting one of the bits of events
listed above,
poll() sets the
corresponding bit in revents if the requested condition is true. In
addition, poll() sets the POLLHUP,
POLLERR, and POLLNVAL flag in
revents if the condition is true, even if the application didn't
set the corresponding bit in events.

If none of the defined events occurs on any selected file
descriptor, poll() waits at least timeout milliseconds
for an event to occur on any of the selected file descriptors. If the value of
timeout is 0, poll() returns immediately.
If the value of timeout
is -1, poll() blocks until a requested event occurs or until the
call is interrupted.

A file descriptor for a socket that's listening for connections
indicates that it's ready for reading, once connections are available.
A file descriptor for a socket that connects asynchronously
indicates that it's ready for writing, once a connection has been
established.