poll(S-osr5)
poll --
STREAMS input/output multiplexing
Syntax
cc . . . -lc
#include <stropts.h>
#include <poll.h>
int poll(fds, nfds, timeout)
struct pollfd fds[];
unsigned long nfds;
int timeout;
Description
The
poll
system call
provides users with a mechanism for multiplexing input/output
over a set of file descriptors that reference open
STREAMS or any driver that
supports the
select(S-osr5)
system call.
The poll system call 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(S-osr5)
or
getmsg(S-osr5)
and can send messages using
write(S-osr5)
and
putmsg(S-osr5).
Certain
ioctl(S-osr5)
calls, such as I_RECVFD
and I_SENDFD,
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.
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 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(S-osr5)),
poll fails.
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 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 system call is not affected by the O_NONBLOCK
flag.
The
poll
system call
fails if one or more of the following is 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.
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
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.
Note
The
poll
system call also works on devices that support the
select
system call, such as the event driver and the console
driver.
See also
getmsg(S-osr5),
Intro(S-osr5),
putmsg(S-osr5),
read(S-osr5),
write(S-osr5),
select(S-osr5),
Standards conformance
poll is not part of any
currently supported standard;
it was developed by UNIX System Laboratories, Inc. and
is maintained by The SCO Group.
© 2005 The SCO Group, Inc. All rights reserved.
SCO OpenServer Release 6.0.0 -- 02 June 2005