200 lines
6.1 KiB
Groff
200 lines
6.1 KiB
Groff
'\"macro stdmacro
|
|
.if n .pH g2.poll @(#)poll 30.9 of 3/24/86
|
|
.TH POLL 2
|
|
.SH NAME
|
|
poll \- input/output multiplexing
|
|
.SH SYNOPSIS
|
|
.B #include <stropts.h>
|
|
.br
|
|
.B #include <poll.h>
|
|
.sp
|
|
.B "int poll(struct pollfd *fds, unsigned long nfds, int timeout);"
|
|
.SH DESCRIPTION
|
|
The IRIX version of
|
|
.I 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 \s-1STREAMS\s0 devices [see \f2select\f1(2)].
|
|
\f2Poll\f1 identifies those descriptors on which a user can send or
|
|
receive messages, or on which certain events have occurred.
|
|
.P
|
|
\f2Fds\f1 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 \f2pollfd\f1 structures which contain
|
|
the following members:
|
|
.PP
|
|
.if n int fd; /* file descriptor */
|
|
.if t int fd; /* file descriptor */
|
|
.br
|
|
short events; /* requested events */
|
|
.br
|
|
.if n short revents; /* returned events */
|
|
.if t short revents; /* returned events */
|
|
.PP
|
|
where \f2fd\f1 specifies an open file descriptor and
|
|
\f2events\f1 and \f2revents\f1 are bitmasks constructed by or-ing
|
|
any combination of the following event flags:
|
|
.TP 15
|
|
.SM
|
|
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.
|
|
.TP
|
|
.SM
|
|
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.
|
|
.TP
|
|
.SM
|
|
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.
|
|
.TP
|
|
.SM
|
|
POLLPRI
|
|
High priority data may be received without blocking.
|
|
For STREAMS, this flag is set even if the message is of zero length.
|
|
.TP
|
|
.SM
|
|
POLLOUT
|
|
Normal data may be written without blocking.
|
|
.TP
|
|
.SM
|
|
POLLWRNORM
|
|
The same as \s-1POLLOUT\s+1.
|
|
.TP
|
|
.SM
|
|
POLLWRBAND
|
|
Priority data (priority band > 0) may be written. This event only
|
|
examines bands that have been written to at least once.
|
|
.TP
|
|
.SM
|
|
POLLERR
|
|
An error message has arrived at the \f2stream head\f1.
|
|
This flag is only valid in the \f2revents\f1 bitmask;
|
|
it is not used in the \f2events\f1 field.
|
|
.TP
|
|
.SM
|
|
POLLHUP
|
|
A hangup has occurred on the \f2stream\f1.
|
|
This event and \s-1POLLOUT\s+1 are mutually exclusive;
|
|
a \f2stream\f1 can never be writable if a hangup has occurred.
|
|
However, this event and \s-1POLLIN, POLLRDNORM, POLLRDBAND,\s+1
|
|
or \s-1POLLPRI\s+1 are not mutually exclusive.
|
|
This flag is only valid in the \f2revents\f1 bitmask;
|
|
it is not used in the \f2events\f1 field.
|
|
.br
|
|
.ne 5
|
|
.TP
|
|
.SM
|
|
POLLNVAL
|
|
The specified \f2fd\f1 value does not belong to an open \f2stream\f1.
|
|
This flag is only valid in the \f2revents\f1 field;
|
|
it is not used in the \f2events\f1 field.
|
|
.PP
|
|
For each element of the array pointed to by \f2fds\f1,
|
|
\f2poll\f1 examines the given file descriptor for the
|
|
event(s) specified in \f2events\f1.
|
|
The number of file descriptors to be examined is specified by \f2nfds\f1.
|
|
If \f2nfds\f1 exceeds \s-1NOFILES\s0, the system limit of open files [see \f2ulimit\f1(2)],
|
|
\f2poll\f1 will fail.
|
|
.PP
|
|
If the value
|
|
.I fd
|
|
is less than zero,
|
|
.I events
|
|
is ignored and
|
|
.I revents
|
|
is set to 0 in that entry on return from
|
|
.IR poll .
|
|
.P
|
|
The results of the \f2poll\f1 query are stored in the
|
|
\f2revents\f1 field in the \f2pollfd\f1 structure.
|
|
Bits are set in the \f2revents\f1 bitmask to indicate
|
|
which of the requested events are true.
|
|
If none are true, none of the specified bits is
|
|
set in \f2revents\f1 when the \f2poll\f1 call returns.
|
|
The event flags \s-1POLLHUP\s+1, \s-1POLLERR\s+1 and \s-1POLLNVAL\s+1 are always set in
|
|
\f2revents\f1 if the conditions they indicate are true; this
|
|
occurs even though these flags were not present in \f2events\f1.
|
|
.P
|
|
If none of the defined events have occurred on any selected file descriptor,
|
|
\f2poll\f1 waits at least \f2timeout\f1 msec for an event to occur
|
|
on any of the selected file descriptors.
|
|
On a computer where millisecond timing accuracy is not available,
|
|
\f2timeout\f1 is rounded up to the nearest legal value available
|
|
on that system.
|
|
If the value \f2timeout\f1 is 0, \f2poll\f1 returns immediately.
|
|
If the value of \f2timeout\f1 is -1,
|
|
\f2poll\f1 blocks until a requested event occurs or
|
|
until the call is interrupted.
|
|
\f2poll\f1 is not affected by the \s-1O_NDELAY\s+1 and
|
|
\s-1O_NONBLOCK\s+1 flag.
|
|
.P
|
|
.I poll
|
|
fails if one or more of the following are true:
|
|
.TP 13
|
|
.SM
|
|
\%[EAGAIN]
|
|
Allocation of internal data structures failed but request should
|
|
be attempted again.
|
|
.TP
|
|
.SM
|
|
\%[EFAULT]
|
|
Some argument points outside the allocated address space.
|
|
.TP
|
|
.SM
|
|
\%[EINTR]
|
|
A signal was caught during the \f2poll\f1 system call.
|
|
.TP
|
|
.SM
|
|
\%[EINVAL]
|
|
The argument \f2nfds\f1 is less than zero, or \f2nfds\f1 is greater
|
|
than \s-1NOFILES\s0.
|
|
.SH "SEE ALSO"
|
|
intro(2), select(2), read(2), write(2), getmsg(2), putmsg(2),
|
|
streamio(7)
|
|
.SH 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 \f2revents\f1 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
|
|
.I errno
|
|
is set to indicate the error.
|
|
.Ee
|
|
.* '\".so /pubs/tools/origin.att
|
|
.SH NOTES
|
|
Some devices do not support polling via the
|
|
.IR select (2)
|
|
and
|
|
.IR poll (2)
|
|
system calls. Doing a
|
|
.I select
|
|
or
|
|
.I poll
|
|
on a file descriptor associated with an "un-pollable" device will cause the
|
|
.I select
|
|
or
|
|
.I 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
|
|
.I select
|
|
or
|
|
.I 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
|
|
.IR 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.
|