poll(2) System Calls Manual poll(2)
NAME
poll - monitor I/O conditions on multiple file descriptors
SYNOPSIS
DESCRIPTION
provides a general mechanism for reporting I/O conditions associated with a set of file descriptors and for waiting until one or more spec-
ified 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 milliseconds) to wait for at least one of the specified 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 with-
out being blocked by flow control. This flag is not used for high priority data, because it can be written 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 exclusive 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 indicate 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 immediately, 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
positive 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:
o timeout is a negative number other than -1.
o The nfds argument is less than 0, greater than or greater than or equal to The kernel parameter specifies the max-
imum 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.
o 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 parameter addresses a location outside of the allocated address space of
the process. Reliable detection of this error is implementation-dependent.
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 ALSO
read(2), write(2), select(2), getmsg(2), putmsg(2), streamio(7).
STANDARDS CONFORMANCE
poll(2)