POLL(2)POLL(2)NAMEpoll - input/output multiplexing
SYNOPSIS
#include <stropts.h>
#include <poll.h>
int poll(struct pollfd *fds, unsigned long nfds, int timeout);
DESCRIPTION
The IRIX version of poll provides users with a mechanism for multiplexing
input and output over a set of any type of file descriptors, rather than
the traditional limitation to only descriptors of STREAMS devices [see
select(2)]. Poll identifies those descriptors on which a user can send
or receive messages, or on which certain events have occurred.
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 Data other than high priority data may be read without
blocking. For STREAMS, the flag is set even if the
message is of zero length.
POLLRDNORM Normal data (priority band = 0) may be read without
blocking. For STREAMS, the flag is set even if the
message is of zero length.
POLLRDBAND Data from a non-zero priority band may be read without
blocking. For STREAMS, the flag is set even if the
message is of zero length.
POLLPRI High priority data may be received without blocking. For
STREAMS, this flag is set even if the message is of zero
length.
POLLOUT Normal data may be written without blocking.
POLLWRNORM The same as POLLOUT.
POLLWRBAND Priority data (priority band > 0) may be written. This
event only examines bands that have been written to at
least once.
Page 1
POLL(2)POLL(2)
POLLERR An error message has arrived at the stream head.
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, POLLRDNORM, POLLRDBAND, or POLLPRI are not
mutually exclusive.
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(2)], 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. poll is not
affected by the O_NDELAY and O_NONBLOCK flag.
poll fails if one or more of the following are 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.
Page 2
POLL(2)POLL(2)SEE ALSOintro(2), select(2), read(2), write(2), getmsg(2), putmsg(2), streamio(7)DIAGNOSTICS
Upon successful completion, a non-negative value is returned. A positive
value indicates the total number of file descriptors that has been
selected (i.e., 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.
NOTES
Some devices do not support polling via the select(2) and poll(2) system
calls. Doing a select or poll on a file descriptor associated with an
"un-pollable" device will cause the select or poll to return immediately
with a success value of 0 and the with the corresponding file descriptor
events of queried set true. For instance, if a select or poll is
performed on a read file descriptor associated with an un-pollable
device, the call would return immediately, even though there may be
nothing to read on the device. A subsequent read(2) in this situation
might return with a "bytes-read" count of 0 or might block if the device
supports read blocking. Devices which exhibit this behavior (especially
those from third-party vendors) should be suspected as not supporting
polling.
Some devices support the POLLERR and POLLHUP flags in the events field
for intentionally polling for device errors. This is an SGI IRIX
specific option and may not be portable.
Page 3
