poll(2)poll(2)NAMEpoll - Monitor conditions on multiple file descriptors
SYNOPSIS
#include <poll.h>
int poll(
struct pollfd filedes [],
nfds_t nfds,
int timeout );
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards 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.
PARAMETERS
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 Speci‐
fies 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.
DESCRIPTION
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 appli‐
cation 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 dis‐
connected. 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 mem‐
ber; 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 spec‐
ify 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 con‐
dition to become true. If, in that time interval, a reportable condi‐
tion 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 with‐
out 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-termi‐
nal 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 con‐
nections indicates it is ready for reading after connections are avail‐
able. A file descriptor for a socket that is connecting asynchronously
indicates it is ready for writing after a connection is established.
NOTES
[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.
[Tru64 UNIX] For compliance with the revised UNIX98 standards, the
std_unix98 tunable attribute in the generic subsystem must be set to a
value of 2. See sys_attrs_generic(5) for more information.
RETURN VALUES
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.
ERRORS
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 param‐
eter addresses a location outside of the allocated address space
of the process.
SEE ALSO
Functions: getmsg(2), putmsg(2), read(2), write(2), setsysinfo(2),
streamio(7)
Standards: standards(5)
Network Programmer's Guide
poll(2)
