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)