NAME
poll, pollts —
synchronous I/O
multiplexing
LIBRARY
Standard C Library (libc, -lc)
SYNOPSIS
#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);
DESCRIPTION
poll() and
pollts() examine a set of file
descriptors to see if some of them are ready for I/O. The
fds argument is a pointer to an array of pollfd
structures as defined in
<poll.h>
(shown below). The
nfds argument determines the size of
the
fds array.
struct pollfd {
int fd; /* file descriptor */
short events; /* events to look for */
short revents; /* events returned */
};
The fields of
struct pollfd are as follows:
-
-
- fd
- File descriptor to poll. If the value in
fd is negative, the file descriptor is ignored and
revents is set to 0.
-
-
- events
- Events to poll for. (See below.)
-
-
- revents
- Events which may occur. (See below.)
The event bitmasks in
events and
revents have the following bits:
-
-
- POLLIN
- Data other than high priority data may be read without
blocking.
-
-
- POLLRDNORM
- Normal data may be read without blocking.
-
-
- POLLRDBAND
- Data with a non-zero priority may be read without
blocking.
-
-
- POLLPRI
- High priority data may be read without blocking.
-
-
- POLLOUT
- Normal data may be written without blocking.
-
-
- POLLWRNORM
- Equivalent to POLLOUT.
-
-
- POLLWRBAND
- Data with a non-zero priority may be written without
blocking.
-
-
- POLLERR
- An exceptional condition has occurred on the device or
socket. This flag is always checked, even if not present in the
events bitmask.
-
-
- POLLHUP
- The device or socket has been disconnected. This flag is
always checked, even if not present in the events
bitmask. Note that POLLHUP and POLLOUT should never be present in the
revents bitmask at the same time. If the remote end
of a socket is closed, poll() returns a POLLIN event,
rather than a POLLHUP.
-
-
- POLLNVAL
- The file descriptor is not open. This flag is always
checked, even if not present in the events
bitmask.
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), the poll blocks
indefinitely. If
timeout is zero, then
poll() will return without blocking.
If
ts is a non-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() blocks indefinitely. If
ts is
a non-null pointer, referencing a zero-valued timespec structure, then
pollts() will return without blocking.
If
sigmask is a non-null pointer, then the
pollts() function shall replace the signal mask of the
caller by the set of signals pointed to by
sigmask
before examining the descriptors, and shall restore the signal mask of the
caller before returning.
RETURN VALUES
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.
COMPATIBILITY
This implementation differs from the historical one in that a given file
descriptor may not cause
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 behaviour is believed to be more useful.
ERRORS
An error return from
poll() indicates:
-
-
- [
EFAULT
]
- fds points outside the process's
allocated address space.
-
-
- [
EINTR
]
- A signal was delivered before the time limit expired and
before any of the selected events occurred.
-
-
- [
EINVAL
]
- The specified time limit is negative.
SEE ALSO
accept(2),
connect(2),
read(2),
recv(2),
select(2),
send(2),
write(2)
HISTORY
The
poll() function appeared in
AT&T
System V Release 3 UNIX. The
pollts()
function first appeared in
NetBSD 3.0.
BUGS
The distinction between some of the fields in the
events
and
revents bitmasks is really not useful without
STREAMS. The fields are defined for compatibility with existing
software.