POLL(S) UNIX System V POLL(S)
Name
poll - STREAMS input/output multiplexing
Syntax
#include <stropts.h>
#include <poll.h>
int poll(fds, nfds, timeout)
struct pollfd fds[];
unsigned long nfds;
int timeout;
Description
The poll system call provides users with a mechanism for
multiplexing input/output over a set of file descriptors
that reference open streams (see Intro(S)) or any driver
that supports the select(S) system call. The poll system
call identifies those streams on which a user can send or
receive messages, or on which certain events have occurred.
A user can receive messages using read(S) or getmsg(S) and
can send messages using write(S) and putmsg(S). Certain
ioctl(S) calls, such as I_RECVFD and I_SENDFD, can also be
used to receive and send messages.
fds specifies the file descriptors to be examined and the
events of interest for each file descriptor. It is a
pointer to an array with one element for each open file
descriptor of interest. The array's elements are pollfd
structures which contain the following members:
int fd; /* file descriptor */
short events; /* requested events */
short revents; /* returned events */
where fd specifies an open file descriptor and events and
revents are bitmasks constructed by or-ing any combination
of the following event flags:
POLLIN A non-priority or file descriptor passing
message (see I_RECVFD) is present on the stream
head read queue. This flag is set even if the
message is of zero length. In revents, this
flag is mutually exclusive with POLLPRI.
POLLPRI A priority message is present on the stream head
read queue. This flag is set even if the
message is of zero length. In revents, this
flag is mutually exclusive with POLLIN.
POLLOUT The first downstream write queue in the stream
is not full. Priority control messages can be
sent (see putmsg) at any time.
POLLERR An error message has arrived at the stream head.
This flag is only valid in the revents bitmask;
it is not used in the events field.
POLLHUP A hangup has occurred on the stream. This event
and POLLOUT are mutually exclusive; a stream can
never be writable if a hangup has occurred.
However, this event and POLLIN or POLLPRI are
not mutually exclusive. This flag is only valid
in the revents bitmask; it is not used in the
events field.
POLLNVAL The specified fd value does not belong to an
open stream. This flag is only valid in the
revents field; it is not used in the events
field.
For each element of the array pointed to by fds, poll
examines the given file descriptor for the event(s)
specified in events. The number of file descriptors to be
examined is specified by nfds. If nfds exceeds NOFiles, the
system limit of open files (see ulimit(S)), poll will fail.
If the value fd is less than zero, events is ignored and
revents is set to 0 in that entry on return from poll.
The results of the poll query are stored in the revents
field in the pollfd structure. Bits are set in the revents
bitmask to indicate which of the requested events are true.
If none are true, none of the specified bits is set in
revents when the poll call returns. The event flags
POLLHUP, POLLERR, and POLLNVAL are always set in revents if
the conditions they indicate are true; this occurs even
though these flags were not present in events.
If none of the defined events have occurred on any selected
file descriptor, poll waits at least timeout msec for an
event to occur on any of the selected file descriptors. On
a computer where millisecond timing accuracy is not
available, timeout is rounded up to the nearest legal value
available on that system. If the value timeout is 0, poll
returns immediately. If the value of timeout is -1, poll
blocks until a requested event occurs or until the call is
interrupted. The poll system call is not affected by the
O_NDELAY flag.
The poll system call fails if one or more of the following
is true:
[EAGAIN] Allocation of internal data structures failed
but request should be attempted again.
[EFAULT] Some argument points outside the allocated
address space.
[EINTR] A signal was caught during the poll system
call.
[EINVAL] The argument nfds is less than zero, or nfds is
greater than NOFiles.
See Also
getmsg(S), intro(S), putmsg(S), read(S), write(S),
select(S),
STREAMS Primer,
STREAMS Programmer's Guide
Diagnostics
Upon successful completion, a non-negative value is
returned. A positive value indicates the total number of
file descriptors that has been selected (that is, file
descriptors for which the revents field is non-zero). A
value of 0 indicates that the call timed out and no file
descriptors have been selected. Upon failure, a value of -1
is returned, and errno is set to indicate the error.
Note
The poll system call also works on devices that support the
select system call, such as the event driver and the console
driver.
Standards Conformance
poll is conformant with:
AT&T SVID Issue 2, Select Code 307-127.
(printed 6/20/89)