Provides users with a mechanism for multiplexing input/output
over a set of file descriptors that reference open streams.
This function is supported on OpenVMS Integrity servers and
Alpha only.
Format
#include <poll.h>
int poll (struct pollfd filedes [], nfds_t nfds, int timeout);
1 – Argument
filedes
Points to an array of pollfd structures, one for each file
descriptor of interest. Each pollfd structure includes the
following members:
int fd - The file descriptor
int events - The requested conditions
int revents - The reported conditions
nfds
The number of pollfd structures in the filedes array.
timeout
The maximum length of time (in milliseconds) to wait for at least
one of the specified events to occur.
2 – 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 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:
POLLERR - 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.
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.
POLLIN - 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.
POLLNVAL - The value specified for fd is invalid. This option
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 blocking.
POLLPRI - 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.
POLLRDBAND - Data from a nonzero priority band may be read
without blocking. This option is set in revents even if the
message is of zero length.
POLLRDNORM - 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.
POLLWRBAND - Priority data (priority band greater than 0)
may be written. This event only examines bands that have been
written to at least once.
POLLWRNORM - 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 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.
3 – Return Values
n Upon successful completion, a nonnegative
value is returned, indicating the number of
file descriptors for which poll has set the
revents bitmask.
0 poll has timed out and has not set any of the
revents bitmasks.
-1 An error occurred. errno is set to indicate
the error:
o EAGAIN - Allocation of internal data
structures failed. A later call to the
poll function might complete successfully.
o EINTR - A signal was intercepted during the
poll function, and the signal handler was
installed with an indication that functions
are not to be restarted.
o EINVAL - 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.