POLL(2) OpenBSD Programmer's Manual POLL(2)NAMEpoll - synchronous I/O multiplexing
SYNOPSIS
#include <poll.h>
int
poll(struct pollfd *fds, nfds_t nfds, int timeout);
DESCRIPTIONpoll() 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:
fds Points to an array of pollfd structures, which are defined as:
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.
nfds An unsigned integer specifying the number of pollfd structures
in the array.
timeout Maximum interval to wait for the poll to complete, in
milliseconds. If this value is 0, 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 Data other than high-priority data may be read without
blocking.
POLLRDNORM Normal data may be read without blocking.
POLLRDBAND Priority data may be read without blocking.
POLLNORM Same as POLLRDNORM. This flag is provided for source code
compatibility with older programs and should not be used in
new code.
POLLPRI High-priority data may be read without blocking.
POLLOUT Normal data may be written without blocking.
POLLWRNORM Same as POLLOUT.
POLLWRBAND Priority data may be written.
POLLERR An error has occurred on the device or socket. This flag is
only valid in the revents bitmask; it is ignored in the
events member.
POLLHUP The device or socket has been disconnected. This event and
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 corresponding file descriptor is invalid. This flag is
only valid in the revents bitmask; it is ignored in the
events member.
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.
RETURN VALUES
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.
EXAMPLES
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");
ERRORSpoll() will fail if:
[EFAULT] fds points outside the process's allocated address space.
[EINTR] poll() caught a signal during the polling process.
[EINVAL] nfds was greater than the number of available file
descriptors.
[EINVAL] The timeout passed to poll() was too large.
SEE ALSOgetrlimit(2), read(2), select(2), write(2)STANDARDS
The poll() function is compliant with the X/Open Portability Guide Issue
4.3 (``XPG4.3'') specification.
HISTORY
A poll() system call appeared in AT&T System V.3 UNIX.
BUGS
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.
OpenBSD 4.9 July 11, 2007 OpenBSD 4.9