poll(2) CLIX poll(2)
NAME
poll - STREAMS input/output multiplexing
LIBRARY
Standard C Library (libc.a)
SYNOPSIS
#include <stropts.h>
#include <poll.h>
int poll(
struct pollfd fds[] ,
unsigned long nfds ,
int timeout );
PARAMETERS
fds Points to an array of file descriptors.
nfds Specifies the number of file descriptors to be examined.
timeout Specifies the length of time to wait for an event to occur on a
given file descriptor.
DESCRIPTION
The poll() function provides users with a mechanism for multiplexing
input/output over a set of file descriptors that reference open streams.
(See the intro() function.) The poll() function 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 the read() or getmsg()
function and can send messages using the write() and putmsg() functions.
Certain ioctl() calls, such as I_RECVFD and I_SENDFD (see the streamio
file), can also be used to receive and send messages.
The fds parameter 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
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 a logical OR of any combination of the following
event flags:
2/94 - Intergraph Corporation 1
poll(2) CLIX poll(2)
POLLNVAL 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.
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
member.
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 member.
POLLNVAL The specified fd value does not belong to an open stream. This
flag is only valid in the revents member; it is not used in the
events member.
For each element of the array pointed to by fds, poll() examines the given
file descriptor for the events 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 the ulimit() function), poll() fails.
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 member 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() function 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. The poll()
function is not affected by the O_NDELAY flag.
2 Intergraph Corporation - 2/94
poll(2) CLIX poll(2)
EXAMPLES
To wait indefinitely for input on file descriptor fd:
fds[0].fd = fd;
fds[0].events = POLLIN;
if (poll(fds, NPOLL, -1) == -1)
perror("Poll failed");
RETURN VALUES
Upon successful completion, a non-negative value is returned. A positive
value indicates the total number of file descriptors that has been
selected. (For example, file descriptors for which the revents member 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.
ERRORS
The poll() function fails if one or more of the following are true:
[EAGAIN] Allocation of internal data structures failed, but the request
should be attempted again.
[EFAULT] Some parameter points outside the allocated address space.
[EINTR] A signal was caught during the poll() function.
[EINVAL] The nfds parameter is less than 0, or nfds is greater than
NOFILES.
RELATED INFORMATION
Functions: intro(2), read(2), getmsg(2), putmsg(2), write(2)
Files: streamio(7)
AT&T UNIX System V STREAMS Primer, AT&T UNIX System V STREAMS Programmer's
Guide
2/94 - Intergraph Corporation 3