POLL(2) | System Calls Manual | POLL(2) |
poll
, ppoll
—
#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);
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. 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.
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.
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.
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"); }
poll
() and ppoll
() will fail if:
EFAULT
]EINTR
]EINVAL
]EINVAL
]poll
() function is compliant with the
IEEE Std 1003.1-2008 (“POSIX.1”)
specification. The ppoll
() function is a Linux
extension.
poll
() system call appeared in
AT&T System V Release 3 UNIX. The
ppoll
() function appeared in OpenBSD
5.4.
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.
August 18, 2018 | OpenBSD-current |