POLL(2) | System Calls Manual | POLL(2) |
poll
— synchronous
I/O multiplexing
#include
<poll.h>
int
poll
(struct
pollfd *fds, nfds_t
nfds, int
timeout);
poll
()
provides a mechanism for multiplexing I/O across a set of file descriptors.
It is similar in function to
select(2). Unlike
select(2), however, it is
possible to only pass in data corresponding to the file descriptors for
which events are wanted. This makes poll
() more
efficient than select(2) in
most cases.
The arguments are as follows:
struct pollfd { int fd; short events; short revents; };
The fd member is an open file descriptor. If fd is -1, the pollfd structure is considered unused, and revents will be cleared.
The events and revents members are bitmasks of conditions to monitor and conditions found, respectively.
poll
()
will return immediately. If this value is INFTIM (-1),
poll
() will block indefinitely until a condition
is found.The calling process sets the
events bitmask and
poll
() sets
the revents bitmask. Each call to
poll
() resets the revents
bitmask for accuracy. The condition flags in the bitmasks are defined
as:
POLLIN
POLLRDNORM
POLLRDBAND
POLLNORM
POLLRDNORM
. This flag is provided for
source code compatibility with older programs and should not be used in
new code.POLLPRI
POLLOUT
POLLWRNORM
POLLOUT
.POLLWRBAND
POLLERR
POLLHUP
POLLOUT
are mutually-exclusive; a descriptor 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 ignored in the
events member.POLLNVAL
The significance and semantics of normal, priority, and high-priority data are device-specific.
In addition to I/O multiplexing,
poll
() can
be used to generate simple timeouts. This functionality may be achieved by
passing a null pointer for fds.
Upon error, poll
() returns -1 and sets the
global variable errno to indicate the error. If the
timeout interval was reached before any events occurred,
poll
() returns 0. Otherwise,
poll
() returns the number of file descriptors for
which revents is non-zero.
The following example implements a read from the standard input that times out after 60 seconds:
#include <err.h> #include <poll.h> #include <stdio.h> #include <unistd.h> struct pollfd pfd[1]; char buf[BUFSIZ]; int nfds; pfd[0].fd = STDIN_FILENO; pfd[0].events = POLLIN; nfds = poll(pfd, 1, 60 * 1000); if (nfds == -1 || (pfd[0].revents & (POLLERR|POLLHUP|POLLNVAL))) errx(1, "poll error"); if (nfds == 0) errx(1, "time out"); if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) errx(1, "read");
poll
() will fail if:
The poll
() function is compliant with the
specification.
A poll
() system call appeared in
AT&T System V Release 3 UNIX.
The POLLERR
and
POLLWRBAND
flags are accepted but ignored by the
kernel.
Because OpenBSD does not implement
STREAMS, there is no distinction between some of the fields in the
events and revents bitmasks. As
a result, the POLLIN
,
POLLNORM
, and POLLRDNORM
flags are equivalent.
Internally to the kernel, poll
() works
poorly if multiple processes wait on the same file descriptor.
July 11, 2007 | OpenBSD-5.1 |