POLL(2) System Calls POLL(2)

NAME

poll - input/output multiplexing

SYNOPSIS

#include <poll.h>

int poll(struct pollfd fds[], nfds_t nfds, int timeout);

int ppoll(struct pollfd *restrict fds, nfds_t nfds,
const struct timespec *restrict tsp, const sigset_t *restrict sigmask);

DESCRIPTION

The poll() and ppoll() functions provides applications with a
mechanism for multiplexing input/output over a set of file
descriptors. For each member of the array pointed to by fds, poll()
and ppoll() examine 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 poll() and ppoll() functions identify
those file descriptors on which an application can read or write
data, or on which certain events have occurred.


The ppoll() function behaves identically to poll(), except as
follows:

o For the ppoll function, the timeout period is given in
seconds and nanoseconds in an argument of type struct
timespec, where as poll() takes a timeout in milliseconds
in the form of an integer argument.

o The ppoll() function takes an optional sigmask argument.
When a non-NULL pointer is passed, the calling threads
signal mask is replaced by the one specified in sigset
before examining file descriptors, and restored before
returning.


The fds argument 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 member for each open file descriptor of interest.
The array's members are pollfd structures, which contain the
following members:

int fd; /* file descriptor */
short events; /* requested events */
short revents; /* returned events */


The fd member specifies an open file descriptor and the events and
revents members are bitmasks constructed by a logical OR operation of
any combination of the following event flags:

POLLIN
Data other than high priority data may be read without
blocking. For streams, this flag is set in revents even
if the message is of zero length.


POLLRDNORM
Normal data (priority band equals 0) may be read
without blocking. For streams, this flag is set in
revents even if the message is of zero length.


POLLRDBAND
Data from a non-zero priority band may be read without
blocking. For streams, this flag is set in revents even
if the message is of zero length.


POLLPRI
High priority data may be received without blocking.
For streams, this flag is set in revents even if the
message is of zero length.


POLLOUT
Normal data (priority band equals 0) may be written
without blocking.


POLLWRNORM
The same as POLLOUT.


POLLWRBAND
Priority data (priority band > 0) may be written. This
event only examines bands that have been written to at
least once.


POLLERR
An error has occurred on the device or stream. This
flag is only valid in the revents bitmask; it is not
used in the events member.


POLLHUP
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, POLLRDNORM, POLLRDBAND, or POLLPRI are not
mutually exclusive. This flag is only valid in the
revents bitmask; it is not used in the events member.


POLLNVAL
The specified fd value does not belong to an open file.
This flag is only valid in the revents member; it is
not used in the events member.


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


The results of the poll() or ppoll() query are stored in the revents
member 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 are set in revents when either the poll()
or ppoll() 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() and ppoll() wait 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. If the value of tsp is NULL, then ppoll()
blocks until a requested event occurs or until the call is
interrupted. The poll() and ppoll() functions are not affected by the
O_NDELAY and O_NONBLOCK flags.


The poll() and ppoll() functions support regular files, terminal and
pseudo-terminal devices, streams-based files, FIFOs, pipes, and
sockets. The behavior of poll() and ppoll() on elements of fds that
refer to other types of file is unspecified.


A file descriptor for a socket that is listening for connections will
indicate that it is ready for reading, once connections are
available. A file descriptor for a socket that is connecting
asynchronously will indicate that it is ready for writing, once a
connection has been established.


Regular files always poll() and ppoll() TRUE for reading and writing.

RETURN VALUES

Upon successful completion, a non-negative value is returned. A
positive value indicates the total number of file descriptors that
has been selected (that is, file descriptors for which the revents
member is non-zero). A value of 0 indicates that the call timed out
and no file descriptors have been selected. Upon failure, -1 is
returned and errno is set to indicate the error.

ERRORS

The poll() and ppoll() functions will fail if:

EAGAIN
Allocation of internal data structures failed, but the
request may be attempted again.


EFAULT
Some argument points to an illegal address.


EINTR
A signal was caught during the poll() or ppoll() function.


EINVAL
The argument nfds is greater than {OPEN_MAX}, or one of the
fd members refers to a stream or multiplexer that is linked
(directly or indirectly) downstream from a multiplexer.

ATTRIBUTES

See attributes(7) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Standard |
+--------------------+-----------------+

SEE ALSO

Intro(2), getmsg(2), getrlimit(2), putmsg(2), read(2), write(2),
select(3C), attributes(7), standards(7), chpoll(9E)


STREAMS Programming Guide

NOTES

Non-STREAMS drivers use chpoll(9E) to implement poll() on these
devices.

August 23, 2001 POLL(2)