NAME
poll
, ppoll
— synchronous I/O
multiplexing
SYNOPSIS
#include
<poll.h>
int
poll
(struct
pollfd *fds, nfds_t
nfds, int
timeout);
int
ppoll
(struct
pollfd *fds, nfds_t
nfds, const struct
timespec *timeout, const
sigset_t *mask);
DESCRIPTION
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:
- 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 isINFTIM
(-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 andPOLLIN
,POLLRDNORM
,POLLRDBAND
, orPOLLPRI
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. For example, on
OpenBSD, the POLLPRI
and
POLLRDBAND
flags may be used to detect when
out-of-band socket data may be read without blocking.
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.
The
ppoll
()
function is similar to poll
() except that it
specifies the timeout using a timespec structure, and a null pointer is used
to specify an indefinite timeout instead of INFTIM
.
Also, if mask is a non-null pointer,
ppoll
() atomically sets the calling thread's signal
mask to the signal set pointed to by mask for the
duration of the function call. In this case, the original signal mask will
be restored before ppoll
() returns.
RETURN VALUES
Upon error, poll
() and
ppoll
() return -1 and set the global variable
errno to indicate the error. If the timeout interval
was reached before any events occurred, they return 0. Otherwise, they
return the number of pollfd structures for which
revents is non-zero.
IDIOMS
Care must be taken when converting code from
select(2) to poll
() as they have slightly
different semantics. The first semantic difference is that, unlike
select(2), poll
() has a way of indicating
that one or more file descriptors is invalid by setting a flag in the
revents field of corresponding entry of
fds, whereas
select(2) returns an error (-1) if any of the descriptors with bits
set in the fd_set are invalid. The second difference
is that on EOF there is no guarantee that POLLIN
will be set in revents, the caller must also check for
POLLHUP
. This differs from
select(2) where EOF is considered as a read event.
Consider the following usage of select(2) that implements a read from the standard input with a 60 second time out:
struct timeval timeout; fd_set readfds; char buf[BUFSIZ]; int nready; timeout.tv_sec = 60; timeout.tv_usec = 0; FD_ZERO(&readfds); FD_SET(STDIN_FILENO, &readfds); nready = select(STDIN_FILENO + 1, &readfds, NULL, NULL, &timeout); if (nready == -1) err(1, "select"); if (nready == 0) errx(1, "time out"); if (FD_ISSET(STDIN_FILENO, &readfds)) { if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) err(1, "read"); }
This can be converted to
poll
() as
follows:
struct pollfd pfd[1]; char buf[BUFSIZ]; int nready; pfd[0].fd = STDIN_FILENO; pfd[0].events = POLLIN; nready = poll(pfd, 1, 60 * 1000); if (nready == -1) err(1, "poll"); if (nready == 0) errx(1, "time out"); if ((pfd[0].revents & (POLLERR|POLLNVAL))) errx(1, "bad fd %d", pfd[0].fd); if ((pfd[0].revents & (POLLIN|POLLHUP))) if (read(STDIN_FILENO, buf, sizeof(buf)) == -1) err(1, "read"); }
ERRORS
poll
() and ppoll
()
will fail if:
- [
EFAULT
] - fds points outside the process's allocated address space.
- [
EINTR
] - A signal was caught before any polled events occurred and before the timeout elapsed.
- [
EINVAL
] - nfds was greater than the number of available file descriptors.
- [
EINVAL
] - The timeout passed was invalid.
SEE ALSO
clock_gettime(2), getrlimit(2), read(2), select(2), write(2)
STANDARDS
The poll
() function is compliant with the
IEEE Std 1003.1-2008 (“POSIX.1”)
specification. The ppoll
() function is a Linux
extension.
HISTORY
A poll
() system call appeared in
AT&T System V Release 3 UNIX. The
ppoll
() function appeared in
OpenBSD 5.4.
BUGS
The POLLWRBAND
flag is 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. Similarly, the POLLPRI
and
POLLRDBAND
flags are also equivalent.
Internally to the kernel, poll
() and
ppoll
() work poorly if multiple processes wait on
the same file descriptor.