POLL(2) System Calls Manual POLL(2)
poll - I/O multiplexing
int poll(fds, nfds, timeout)
struct pollfd *fds;
unsigned long nfds;
poll() provides users with a mechanism for multiplexing input/output
over a set of file descriptors (see intro(2)). poll() identifies those
file descriptors on which a user can send or receive messages, or on
which certain events have occurred. A user can receive messages using
read(2V) or getmsg(2) and can send messages using write(2V) and
putmsg(2). Certain ioctl(2) calls, such as I_RECVFD and I_SENDFD (see
streamio(4)), can also be used to receive and send messages on streams.
fds specifies the file descriptors to be examined and the events of
interest for each file descriptor. It is a pointer to an array with
one element for each open file descriptor of interest. The array's
elements are pollfd structures which contain the following members:
int fd; /* file descriptor */
short events; /* requested events */
short revents; /* returned events */
where fd specifies an open file descriptor and events and revents are
bitmasks constructed by ORing any combination of the following event
POLLIN If the file descriptor refers to a stream, a non-prior-
ity or file descriptor passing message (see I_RECVFD) is
present on the stream head read queue. This flag is set
even if the message is of zero length. If the file
descriptor is not a stream, the file descriptor is read-
able. In revents, this flag is mutually exclusive with
POLLPRI If the file descriptor is a stream, a priority message
is present on the stream head read queue. This flag is
set even if the message is of zero length. If the file
descriptor is not a stream, some exceptional condition
has occurred. In revents, this flag is mutually exclu-
sive with POLLIN.
POLLOUT If the file descriptor is a stream, the first downstream
write queue in the stream is not full. Priority control
messages can be sent (see putmsg(2)) at any time. If
the file descriptor is not a stream, it is writable.
POLLERR If the file descriptor is a stream, an error message has
arrived at the stream head. This flag is only valid in
the revents bitmask; it is not used in the events field.
POLLHUP If the file descriptor is a stream, a hangup has
occurred on the stream. This event and POLLOUT are
mutually exclusive; a stream can never be writable if a
hangup has occurred. However, this event and POLLIN or
POLLPRI are not mutually exclusive. This flag is only
valid in the revents bitmask; it is not used in the
POLLNVAL The specified fd value does not specify an open file
descriptor. This flag is only valid in the revents
field; it is not used in the events field.
For each element of the array pointed to by fds, poll() examines the
given file descriptor for the event(s) specified in events. The number
of file descriptors to be examined is specified by nfds. If nfds
exceeds the system limit of open files (see getdtablesize(2)), poll()
If the value fd is less than zero, events is ignored and revents is set
to 0 in that entry on return from poll().
The results of the poll() query are stored in the revents field in the
pollfd structure. Bits are set in the revents bitmask to indicate
which of the requested events are true. If none are true, none of the
specified bits is set in revents when the poll() call returns. The
event flags POLLHUP, POLLERR, and POLLNVAL are always set in revents if
the conditions they indicate are true; this occurs even though these
flags were not present in events.
If none of the defined events have occurred on any selected file
descriptor, poll() waits at least timeout milliseconds for an event to
occur on any of the selected file descriptors. On a computer where
millisecond timing accuracy is not available, timeout is rounded up to
the nearest legal value available on that system. If the value 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. poll() is not affected by the O_NDELAY flag.
poll() returns a non-negative value on success. A positive value indi-
cates the total number of file descriptors that has been selected (for
instance, file descriptors for which the revents field is non-zero). 0
indicates the call timed out and no file descriptors have been
selected. On failure, poll() returns -1 and sets errno to indicate the
EAGAIN Allocation of internal data structures failed, but the
request should be attempted again.
EFAULT Some argument points outside the allocated address
EINTR A signal was caught during the poll() system call.
EINVAL The argument nfds is less than zero.
nfds is greater than the system limit of open files.
getdtablesize(2), getmsg(2), intro(2), ioctl(2), putmsg(2), read(2V),
select(2), write(2V), streamio(4)
21 January 1990 POLL(2)