POLL(2-SVR3) RISC/os Reference Manual POLL(2-SVR3)
NAME
poll - STREAMS input/output multiplexing
SYNOPSIS
#include <stropts.h>
#include <poll.h>
int poll(fds, nfds, timeout)
struct pollfd fds[];
unsigned long nfds;
int timeout;
DESCRIPTION
poll provides users with a mechanism for multiplexing
input/output over a set of file descriptors that reference
open streams [see intro(2)]. poll 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(2) or getmsg(2) and can send messages using
write(2) and putmsg(2). Certain ioctl(2) calls, such as
I_RECVFD and I_SENDFD [see streamio(7)], 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.
Printed 11/19/92 Page 1
POLL(2-SVR3) RISC/os Reference Manual POLL(2-SVR3)
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 exam-
ines 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 avail-
able, 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
Page 2 Printed 11/19/92
POLL(2-SVR3) RISC/os Reference Manual POLL(2-SVR3)
interrupted. poll is not affected by the O_NDELAY flag.
ERRORS
poll fails if one or more of the following are true:
[EAGAIN] Allocation of internal data struc-
tures 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
intro(2), read(2), getmsg(2), putmsg(2), write(2).
streamio(7) in the System Administrator's Reference Manual.
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 (i.e., file descrip-
tors 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.
Printed 11/19/92 Page 3