poll - Monitor conditions on multiple file descriptors
#include <poll.h>
int poll(
struct pollfd filedes [],
nfds_t nfds,
int timeout );
Interfaces documented on this reference page conform to
industry standards as follows:
poll(): XSH4.0, XSH4.2, XSH5.0, XNS4.0, XNS5.0
Refer to the standards(5) reference page for more information
about industry standards and associated tags.
Points to an array of pollfd structures, one for each file
descriptor of interest. Each pollfd structure includes
the following members: The file descriptor The requested
conditions The reported conditions Specifies the number of
pollfd structures in the filedes array. Specifies the
maximum length of time (in milliseconds) to wait for at
least one of the specified events to occur.
The poll() function provides users with a mechanism for
multiplexing input/output over a set of file descriptors
that reference open streams. For each member of the array
pointed to by filedes, poll() examines the given file
descriptor for the event(s) specified in events. The
poll() function identifies those streams on which an
application can send or receive messages, or on which certain
events have occurred.
The filedes parameter specifies the file descriptor to be
examined and the events of interest for each file descriptor.
It is a pointer to an array of pollfd structures. The
fd member of each pollfd structure specifies an open file
descriptor. The poll() function uses the events member to
determine what conditions to report for this file descriptor.
If one or more of these conditions is true, the
poll() function sets the associated revents member.
The events and revents members of each pollfd structure
are bitmasks. The calling process sets the events bitmask,
and poll() sets the revents bitmasks. These bitmasks contain
inclusive ORed combinations of condition options. The
following condition options are defined:
An error has occurred on the file descriptor. This option
is only valid in the revents bitmask; it is not used in
the events member.
For STREAMS devices, if an error occurs on the file
descriptor and the device is also disconnected,
poll() returns POLLERR; POLLERR takes precedence
over POLLHUP. The device has been disconnected.
This event is mutually exclusive with POLLOUT; a
stream can never be writable if a hangup occurred.
However, this event and POLLIN, POLLRDNORM, POLLRDBAND
or POLLPRI are not mutually exclusive. This
option is only valid in the revents bitmask; it is
ignored in the events member. Data other than
high-priority data may be read without blocking.
This option is set in revents even if the message
is of zero length. In revents, this option is mutually
exclusive with POLLPRI. [Tru64 UNIX] Data
may be read without blocking. The value specified
for fd is invalid. This option is only valid in the
revents member; it is ignored in the events member.
Normal (priority band equals 0) data may be written
without blocking. High-priority data may be
received without blocking. This option is set in
revents even if the message is of zero length. In
revents, this option is mutually exclusive with
POLLIN. Data from a non-zero priority band may be
read without blocking. This option is set in
revents even if the message is of zero length.
Normal data (priority band equals 0) may be read
without blocking. This option is set in revents
even if the message is of zero length. Priority
data (priority band greater than 0) may be written.
This event only examines bands that have been written
to at least once. Same as POLLOUT.
The poll() function ignores any pollfd structure whose fd
member is less than 0 (zero). If the fd member of all
pollfd structures is less than 0, the poll() function will
return 0 and have no other results.
The conditions indicated by POLLNORM and POLLOUT are true
if and only if at least one byte of data can be read or
written without blocking. There are two exceptions: regular
files, which always poll true for POLLNORM and POLLOUT,
and pipes, when the rules for the operation specify
to return zero in order to indicate end-of-file.
The condition options POLLERR, POLLHUP, and POLLNVAL are
always set in revents if the conditions they indicate are
true for the specified file descriptor, whether or not
these options are set in events.
For each call to the poll() function, the set of
reportable conditions for each file descriptor consists of
those conditions that are always reported, together with
any further conditions for which options are set in
events. If any reportable condition is true for any file
descriptor, the poll() function will return with options
set in revents for each true condition for that file
descriptor.
If no reportable condition is true for any of the file
descriptors, the poll() function waits up to timeout milliseconds
for a reportable condition to become true. If,
in that time interval, a reportable condition becomes true
for any of the file descriptors, poll() reports the condition
in the file descriptor's associated revents member
and returns. If no reportable condition becomes true,
poll() returns without setting any revents bitmasks.
If the timeout parameter is a value of -1, the poll()
function does not return until at least one specified
event has occurred. If the value of the timeout parameter
is 0 (zero), the poll() function does not wait for an
event to occur but returns immediately, even if no specified
event has occurred.
The behavior of the poll() function is not affected by
whether the O_NONBLOCK option is set on any of the specified
file descriptors.
The poll() function supports regular files, terminal and
pseudo-terminal devices, STREAMS-based files, FIFOs, and
pipes. The behavior of poll() function on elements of file
descriptors that refer to other types of files is unspecified.
For sockets, a file descriptor for a socket that is listening
for connections indicates it is ready for reading
after connections are available. A file descriptor for a
socket that is connecting asynchronously indicates it is
ready for writing after a connection is established.
[Tru64 UNIX] For compatibility with BSD systems, the
select() function is also supported.
[Tru64 UNIX] This function supports up to 64K open file
descriptors per process if that capability is enabled.
Upon successful completion, the poll() function returns a
nonnegative value. If the call returns 0 (zero), poll()
has timed out and has not set any of the revents bitmasks.
A positive value indicates the number of file descriptors
for which poll() has set the revents bitmask. If the
poll() function fails, -1 is returned and errno is set to
indicate the error.
If the poll() function fails, errno may be set to one of
the following values: Allocation of internal data structures
failed. A later call to the poll() function may complete
successfully. A signal was caught during the poll()
function and the signal handler was installed with an
indication that functions are not to be restarted. [Tru64
UNIX] The timeout parameter is a negative number other
than -1.
[Tru64 UNIX] The nfds parameter is greater than
the process's soft file descriptor limit.
The nfds parameter 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. [Tru64 UNIX] The filedes
parameter in conjunction with the nfds parameter
addresses a location outside of the allocated
address space of the process.
Functions: getmsg(2), putmsg(2), read(2), write(2), setsysinfo(2), streamio(7)
Standards: standards(5)
Network Programmer's Guide
poll(2)
[ Back ] |
