POLL(2) | System Calls Manual | POLL(2) |
poll, pollts, ppoll
—
#include <poll.h>
int
poll
(struct
pollfd *fds, nfds_t
nfds, int
timeout);
#include <poll.h>
#include <signal.h>
#include <time.h>
int
pollts
(struct
pollfd * restrict fds,
nfds_t nfds,
const struct timespec *
restrict ts, const
sigset_t * restrict sigmask);
#include <poll.h>
#include <signal.h>
#include <time.h>
int
ppoll
(struct
pollfd * restrict fds,
nfds_t nfds,
const struct timespec *
restrict ts, const
sigset_t * restrict sigmask);
poll
(), pollts
() and
ppoll
() examine a set of file descriptors to see if
some of them are ready for I/O. For each object inspected, the caller provides
a list of conditions (called ``events'') to check for, and the kernel returns
a list of conditions that are true. The intent, as with
select(2), is to check for
whether I/O is possible before performing any, so as to permit a top-level
event loop to process input from many sources (and output to many
destinations) without blocking on any of them and thus becoming stuck.
<poll.h>
(shown below). The
nfds argument gives the size of the
fds array.
If timeout is neither zero nor INFTIM (-1),
it specifies a maximum interval to wait for any file descriptor to become
ready, in milliseconds. If timeout is INFTIM (-1),
then poll
() blocks indefinitely. If
timeout is zero, then poll
()
will return without blocking.
Similarly, if ts is not a null pointer, it
references a timespec structure which specifies a maximum interval to wait
for any file descriptor to become ready. If ts is a
null pointer, pollts
() and
ppoll
() block indefinitely. If
ts is not a null pointer, referencing a zero-valued
timespec structure, then pollts
() and
ppoll
() will return without blocking.
If sigmask is not a null pointer, then the
pollts
() and ppoll
()
functions replace the signal mask of the caller by the set of signals
pointed to by sigmask while the call is in progress,
and restore the caller's original signal mask before returning.
The pollfd structure:
struct pollfd { int fd; /* file descriptor */ short events; /* events to look for */ short revents; /* events returned */ };
The fields of struct pollfd are as follows:
There are three more conditions that are always checked for regardless of events and thus may always be reported in revents:
The following additional flags are defined:
No file descriptor will ever produce POLLHUP at the same time as POLLWRNORM.
Sockets produce POLLIN rather than POLLHUP when the remote end is closed.
poll
() returns the number of descriptors that are ready
for I/O, or -1 if an error occurred. If the time limit expires,
poll
() returns 0. If poll
()
returns with an error, including one due to an interrupted call, the
fds array will be unmodified.
poll
() to return with an error.
In cases where this would have happened in the historical implementation (e.g.
trying to poll a revoke(2)d
descriptor), this implementation instead copies the
events bitmask to the revents
bitmask. Attempting to perform I/O on this descriptor will then return an
error. This behavior is believed to be more useful.
The ppoll
() function is a wrapper for
pollts
() to provide compatibility with the Linux
implementation.
poll
() indicates:
EFAULT
]EINTR
]EINVAL
]poll
() function appeared in
AT&T System V Release 3 UNIX, and
was added to NetBSD in NetBSD
1.3. The pollts
() function first appeared in
NetBSD 3.0. The ppoll
()
function first appeared in NetBSD 10.0.
The detailed behavior of specific flags is not very portable from one OS to another.
February 8, 2021 | NetBSD 10.0 |