POLL(2) SysV POLL(2)
NAME
poll - STREAMS input/output multiplexing
SYNOPSIS
#include <stropts.h>
#include <poll.h>
int poll(fds, nfds, timeout)
struct pollfd fds[];
unsigned long nfds; unsigned int nfds;
int timeout;
DESCRIPTION
For applications developed in the Domain/SysV environment, 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 by using
read(2) or getmsg(2) and can send messages by 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.
When used for AES applications, poll provides a general mechanism for
reporting I/O conditions associated with any set of file descriptors and
for waiting until one or more specified conditions becomes true.
Specified conditions include the ability to read or write data without
blocking as well as error conditions.
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 ORing any combination of the following event
flags, depending on the development environment:
The POLLIN and POLLPRI flags are for use in the development of Domain/OS
SysV applications.
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.
This condition is true if and only if at least one byte of data
can be written without blocking, except for regular files,
which always poll true for POLLOUT.
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.
The POLLNORM flag is for use in AES applications.
POLLNORM Data may be read without blocking. This condition is true if
and only if at least one byte of data can be read without
blocking, except for regular files, which always poll true for
POLLNORM.
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 0, 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 of 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 or O_NONBLOCK flag.
ERRORS
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.
In an AES environment, [EINVAL] indicates the timeout argument
is a negative number other than -1.
SEE ALSO
intro(2), read(2), getmsg(2), putmsg(2), write(2).
streamio(7) in Domain/OS System Administration Reference.
Getting Started with SysV STREAMS, Programming with SysV STREAMS.
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
nonzero). 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.