poll - Monitors conditions on multiple file descriptors
struct pollfd filedes[ ],
int timeout );
Interfaces documented on this reference page conform to industry standards
poll(): XSH5.0, XNS5.0
Refer to the standards(5) reference page for more information about indus-
try standards and associated tags.
filedes Points to an array of pollfd structures, one for each file
descriptor of interest. Each pollfd structure includes the fol-
int fd The file descriptor
The requested conditions
The reported conditions
nfds Specifies the number of pollfd structures in the filedes array.
timeout 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 deter-
mine what conditions to report for this file descriptor. If one or more of
these conditions is true, the poll() function sets the associated revents
The events and revents members of each pollfd structure are bitmasks. The
calling process sets the events bitmask, and poll() sets the revents bit-
masks. These bitmasks contain inclusive ORed combinations of condition
flags. The following condition flags are defined:
POLLERR An error has occurred on the file descriptor. This flag is only
valid in the revents bitmask; it is not used in the events
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.
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 flag is
only valid in the revents bitmask; it is ignored in the events
POLLIN Data other than high-priority data may be read without blocking.
This flag is set in revents even if the message is of zero
length. In revents, this flag is mutually exclusive with
POLLNORM [Tru64 UNIX] Data may be read without blocking.
POLLNVAL The value specified for fd is invalid. This flag is only valid
in the revents member; it is ignored in the events member.
POLLOUT Normal (priority band equals 0) data may be written without
POLLPRI High-priority data may be received without blocking. This flag
is set in revents even if the message is of zero length. In
revents, this flag is mutually exclusive with POLLIN.
Data from a non-zero priority band may be read without blocking.
This flag is set in revents even if the message is of zero
Normal data (priority band equals 0) may be read without block-
ing. This flag is set in revents even if the message is of zero
Priority data (priority band greater than 0) may be written.
This event only examines bands that have been written to at least
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 flags 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 flags 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 flags are set in events. If
any reportable condition is true for any file descriptor, the poll() func-
tion will return with flags set in revents for each true condition for that
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 bit-
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
The behavior of the poll() function is not affected by whether the
O_NONBLOCK flag 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
For sockets, a file descriptor for a socket that is listening for connec-
tions 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
[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
[EAGAIN] Allocation of internal data structures failed. A later call to
the poll() function may complete successfully.
[EINTR] A signal was caught during the poll() function and the signal
handler was installed with an indication that functions are not
to be restarted.
[EINVAL] [Tru64 UNIX] The timeout parameter is a negative number other
[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.
[EFAULT] [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),