poll(2) poll(2)
NAME
poll - multiplex STREAMS input/output
SYNOPSIS
#include <stropts.h>
#include <poll.h>
int poll(struct pollfd *fds, nfdst nfds, int timeout);
DESCRIPTION
poll() provides users with a mechanism for multiplexing input/output
over a set of file descriptors that reference open files. poll() iden-
tifies those files 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 */
fd specifies an open file descriptor and events and revents are bit-
masks constructed by an OR of any combination of the following event
flags:
POLLIN Data other than high priority data may be read without
blocking. For STREAMS, this flag is set even if the mes-
sage is of zero length.
POLLRDNORM Normal data (priority band = 0) may be read without
blocking. For STREAMS, this flag is set in revents even
if the message is of zero length.
POLLRDBAND Data from a non-zero priority band may be read without
blocking. For STREAMS, this flag is set in revents even
if the message is of zero length.
POLLPRI High priority data may be received without blocking. For
STREAMS, this flag is set in revents 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 Reliant UNIX 5.44 Printed 11/98
poll(2) poll(2)
POLLMSG An MSIG or MPCSIG message containing the ASIGPOLL sig-
nal has reached the front of the stream head read queue.
POLLERR An error has occurred on the device or stream. 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, POLLRDNORM, POLLRDBAND, 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 file.
This flag is only valid in the revents field; it is not
used in the events field.
If the value of fd is less than 0, events is ignored and revents is
set to 0 in that entry on return from poll().
In each pollfd structure, poll() clears the revents member except that
where the application requested a report on a condition by setting one
of the bits of events listed above, poll() sets the corresponding bit
in revents if the requested condition is true. In addition, poll()
sets the POLLHUP, POLLERR, and POLLNVAL flag in revents if the condi-
tion is true, even if the application did not set the corresponding
bit in events.
If none of the defined events have occurred on any selected file
descriptor, poll() waits at least timeout milliseconds for an event to
occur on any of the selected file descriptors. 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.
Implementations may place limitations on the granularity of timeout
intervals. If the requested timeout interval requires a finer granu-
larity than the implementation supports, the actual timeout interval
will be rounded up to the next supported value.
The poll() function is not affected by the ONONBLOCK flag.
The poll() function supports regular files, terminal and pseudo-ter-
minal devices, STREAMS-based files, FIFOs and pipes. The behavior of
poll() on elements of fds that refer to other types of file is
unspecified.
Regular files always poll TRUE for reading and writing.
Page 2 Reliant UNIX 5.44 Printed 11/98
poll(2) poll(2)
ERRORS
The following error code descriptions are function-specific. You will
find a general description in introprm2(2) or in errno(5).
poll() fails if one or more of the following apply:
EAGAIN Allocation of internal data structures failed, but the
request may be attempted again.
EFAULT Some argument points to a memory area outside the allocated
address space.
EINTR A signal was caught during the poll() system call.
EINVAL The nfds argument is greater than OPENMAX, or one of the fd
members refers to a STREAM or multiplexer that is linked
(directly or indirectly) downstream from a multiplexer.
RESULT
Upon successful completion, a non-negative value is returned. A posi-
tive 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.
SEE ALSO
getmsg(2), getrlimit(2), putmsg(2), read(2), write(2), pollbunch(3C),
poll(5), stropts(5).
Programmer's Guide: STREAMS.
Page 3 Reliant UNIX 5.44 Printed 11/98