poll(2)poll(2)NAMEpoll - monitor I/O conditions on multiple file descriptors
SYNOPSISDESCRIPTION
provides a general mechanism for reporting I/O conditions associated
with a set of file descriptors and for waiting until one or more speci‐
fied conditions becomes true. Specified conditions include the ability
to read or write data without blocking, and error conditions.
Arguments
fds Points to an array of structures, one for each
file descriptor of interest.
nfds Specifies the number of structures in the fds
array.
timeout Specifies the maximum length of time (in mil‐
liseconds) to wait for at least one of the speci‐
fied conditions to occur.
Each structure includes the following members:
File descriptor
Requested conditions
Reported conditions
The member of each structure specifies an open file descriptor. The
function uses the member to determine what conditions to report for
this file descriptor. If one or more of these conditions is true, sets
the associated member.
ignores any structure whose member is negative. If the member of all
structures is negative, returns 0 and has no other results.
The and members of the structure are bit masks. The calling process
sets the bit mask, and sets the bit masks. These bit masks contain
ORed combinations of condition flags. The following condition flags
are defined:
Data can be read without blocking.
For streams, this flag means that a message
that is not high priority is at the front of
the stream head read queue. This message
can be of zero length.
Synonym for
A high priority message is available.
For streams, this message can be of zero
length.
Data can be written without blocking.
For streams, this flag specifies that normal
data (not high priority or priority band >
0) can be written without being blocked by
flow control. This flag is not used for
high priority data, because it can be writ‐
ten even if the stream is flow controlled.
An error has occurred on the file descriptor.
The device has been disconnected.
For streams, this flag in is mutually exclu‐
sive with since a stream cannot be written
to after a hangup occurs. This flag and and
are not mutually exclusive.
is not a valid file descriptor.
A non-priority message is available.
For streams, this flag means that a normal
message (not high priority or priority band
> 0) is at the front of the stream head read
queue. This message can be of zero length.
A priority message (priority band > 0)
is at the front of the stream head read
queue. This message can be read without
blocking. The message can be of zero
length.
Same as
Priority data (priority band > 0)
can be written without being blocked by flow
control. Only previously written bands are
checked.
A or message specifying has reached the front
of the stream head read queue.
The conditions indicated by and are true if and only if at least one
byte of data can be read or written without blocking. The exception is
regular files, which always poll true for and Also, streams return in
even if the available message is of zero length.
The condition flags and are always set in if the conditions they indi‐
cate are true for the specified file descriptor, whether or not these
flags are set in
For each call to 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 If any
reportable condition is true for any file descriptor, returns with
flags set in for each true condition for that file descriptor.
If no reportable condition is true for any of the file descriptors,
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, reports the condition in the file
descriptor's associated member and returns. If no reportable condition
becomes true, returns without setting any bit masks.
If the timeout parameter is a value of −1, does not return until at
least one specified event has occurred. If the value of the timeout
parameter is 0, does not wait for an event to occur but returns immedi‐
ately, even if no specified event has occurred. The behavior of is not
affected by whether the flag is set on any of the specified file
descriptors.
RETURN VALUE
Upon successful completion, returns a nonnegative value. If the call
returns 0, has timed out and has not set any of the bit masks. A posi‐
tive value indicates the number of file descriptors for which has set
the bit mask. If fails, it returns −1 and sets to indicate the error.
ERRORS
fails if any of the following conditions are encountered:
Allocation of internal data structures failed.
A later call to may complete successfully.
A signal was delivered
before any of the selected for conditions
occurred or before the time limit expired.
One of the following conditions is true:
· timeout is a negative number other than −1.
· The nfds argument is less than 0, greater than
or greater than or equal to The kernel parame‐
ter specifies the maximum number of file
descriptors per process (see maxfiles(5)).
specifies the maximum number of files a
process can have open at one time; it has a
value of 2048 if the resource limit for a
process is less than or equal to 2048.
· One of the specified file descriptor refers to
a stream or mux that is linked downstream from
a mux.
The fds parameter in conjunction with the nfds param‐
eter addresses a location outside of the allo‐
cated address space of the process. Reliable
detection of this error is implementation-depen‐
dent.
EXAMPLES
Wait for input on file descriptor 0:
Wait for input on and output on giving up after 10 seconds:
Check for input or output on file descriptor 5 without waiting:
Wait 3.5 seconds:
Wait for a high priority, priority, or normal message on streams file
descriptor 0:
SEE ALSOread(2), write(2), select(2), getmsg(2), putmsg(2), streamio(7).
STANDARDS CONFORMANCEpoll(2)