mirror of https://github.com/mkerrisk/man-pages
458 lines
11 KiB
Groff
458 lines
11 KiB
Groff
.\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl)
|
|
.\" and Copyright (C) 2006, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" %%%LICENSE_START(VERBATIM)
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\" %%%LICENSE_END
|
|
.\"
|
|
.\" Additions from Richard Gooch <rgooch@atnf.CSIRO.AU> and aeb, 971207
|
|
.\" 2006-03-13, mtk, Added ppoll() + various other rewordings
|
|
.\" 2006-07-01, mtk, Added POLLRDHUP + various other wording and
|
|
.\" formatting changes.
|
|
.\"
|
|
.TH POLL 2 2019-03-06 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
poll, ppoll \- wait for some event on a file descriptor
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <poll.h>
|
|
.PP
|
|
.BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout );
|
|
|
|
.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
|
|
.B #include <signal.h>
|
|
.B #include <poll.h>
|
|
.PP
|
|
.BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ", "
|
|
.BI " const struct timespec *" tmo_p ", const sigset_t *" sigmask );
|
|
.fi
|
|
.SH DESCRIPTION
|
|
.BR poll ()
|
|
performs a similar task to
|
|
.BR select (2):
|
|
it waits for one of a set of file descriptors to become ready
|
|
to perform I/O.
|
|
.PP
|
|
The set of file descriptors to be monitored is specified in the
|
|
.I fds
|
|
argument, which is an array of structures of the following form:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
struct pollfd {
|
|
int fd; /* file descriptor */
|
|
short events; /* requested events */
|
|
short revents; /* returned events */
|
|
};
|
|
.EE
|
|
.in
|
|
.PP
|
|
The caller should specify the number of items in the
|
|
.I fds
|
|
array in
|
|
.IR nfds .
|
|
.PP
|
|
The field
|
|
.I fd
|
|
contains a file descriptor for an open file.
|
|
If this field is negative, then the corresponding
|
|
.I events
|
|
field is ignored and the
|
|
.I revents
|
|
field returns zero.
|
|
(This provides an easy way of ignoring a
|
|
file descriptor for a single
|
|
.BR poll ()
|
|
call: simply negate the
|
|
.I fd
|
|
field.
|
|
Note, however, that this technique can't be used to ignore file descriptor 0.)
|
|
.PP
|
|
The field
|
|
.I events
|
|
is an input parameter, a bit mask specifying the events the application
|
|
is interested in for the file descriptor
|
|
.IR fd .
|
|
This field may be specified as zero,
|
|
in which case the only events that can be returned in
|
|
.I revents
|
|
are
|
|
.BR POLLHUP ,
|
|
.BR POLLERR ,
|
|
and
|
|
.B POLLNVAL
|
|
(see below).
|
|
.PP
|
|
The field
|
|
.I revents
|
|
is an output parameter, filled by the kernel with the events that
|
|
actually occurred.
|
|
The bits returned in
|
|
.I revents
|
|
can include any of those specified in
|
|
.IR events ,
|
|
or one of the values
|
|
.BR POLLERR ,
|
|
.BR POLLHUP ,
|
|
or
|
|
.BR POLLNVAL .
|
|
(These three bits are meaningless in the
|
|
.I events
|
|
field, and will be set in the
|
|
.I revents
|
|
field whenever the corresponding condition is true.)
|
|
.PP
|
|
If none of the events requested (and no error) has occurred for any
|
|
of the file descriptors, then
|
|
.BR poll ()
|
|
blocks until one of the events occurs.
|
|
.PP
|
|
The
|
|
.I timeout
|
|
argument specifies the number of milliseconds that
|
|
.BR poll ()
|
|
should block waiting for a file descriptor to become ready.
|
|
The call will block until either:
|
|
.IP * 3
|
|
a file descriptor becomes ready;
|
|
.IP *
|
|
the call is interrupted by a signal handler; or
|
|
.IP *
|
|
the timeout expires.
|
|
.PP
|
|
Note that the
|
|
.I timeout
|
|
interval will be rounded up to the system clock granularity,
|
|
and kernel scheduling delays mean that the blocking interval
|
|
may overrun by a small amount.
|
|
Specifying a negative value in
|
|
.I timeout
|
|
means an infinite timeout.
|
|
Specifying a
|
|
.I timeout
|
|
of zero causes
|
|
.BR poll ()
|
|
to return immediately, even if no file descriptors are ready.
|
|
.PP
|
|
The bits that may be set/returned in
|
|
.I events
|
|
and
|
|
.I revents
|
|
are defined in \fI<poll.h>\fP:
|
|
.TP
|
|
.B POLLIN
|
|
There is data to read.
|
|
.TP
|
|
.B POLLPRI
|
|
There is some exceptional condition on the file descriptor.
|
|
Possibilities include:
|
|
.RS
|
|
.IP * 3
|
|
There is out-of-band data on a TCP socket (see
|
|
.BR tcp (7)).
|
|
.IP *
|
|
A pseudoterminal master in packet mode has seen a state change on the slave
|
|
(see
|
|
.BR ioctl_tty (2)).
|
|
.IP *
|
|
A
|
|
.I cgroup.events
|
|
file has been modified (see
|
|
.BR cgroups (7)).
|
|
.RE
|
|
.TP
|
|
.B POLLOUT
|
|
Writing is now possible, though a write larger that the available space
|
|
in a socket or pipe will still block (unless
|
|
.B O_NONBLOCK
|
|
is set).
|
|
.TP
|
|
.BR POLLRDHUP " (since Linux 2.6.17)"
|
|
Stream socket peer closed connection,
|
|
or shut down writing half of connection.
|
|
The
|
|
.B _GNU_SOURCE
|
|
feature test macro must be defined
|
|
(before including
|
|
.I any
|
|
header files)
|
|
in order to obtain this definition.
|
|
.TP
|
|
.B POLLERR
|
|
Error condition (only returned in
|
|
.IR revents ;
|
|
ignored in
|
|
.IR events ).
|
|
This bit is also set for a file descriptor referring
|
|
to the write end of a pipe when the read end has been closed.
|
|
.TP
|
|
.B POLLHUP
|
|
Hang up (only returned in
|
|
.IR revents ;
|
|
ignored in
|
|
.IR events ).
|
|
Note that when reading from a channel such as a pipe or a stream socket,
|
|
this event merely indicates that the peer closed its end of the channel.
|
|
Subsequent reads from the channel will return 0 (end of file)
|
|
only after all outstanding data in the channel has been consumed.
|
|
.TP
|
|
.B POLLNVAL
|
|
Invalid request:
|
|
.I fd
|
|
not open (only returned in
|
|
.IR revents ;
|
|
ignored in
|
|
.IR events ).
|
|
.PP
|
|
When compiling with
|
|
.B _XOPEN_SOURCE
|
|
defined, one also has the following,
|
|
which convey no further information beyond the bits listed above:
|
|
.TP
|
|
.B POLLRDNORM
|
|
Equivalent to
|
|
.BR POLLIN .
|
|
.TP
|
|
.B POLLRDBAND
|
|
Priority band data can be read (generally unused on Linux).
|
|
.\" POLLRDBAND is used in the DECnet protocol.
|
|
.TP
|
|
.B POLLWRNORM
|
|
Equivalent to
|
|
.BR POLLOUT .
|
|
.TP
|
|
.B POLLWRBAND
|
|
Priority data may be written.
|
|
.PP
|
|
Linux also knows about, but does not use
|
|
.BR POLLMSG .
|
|
.SS ppoll()
|
|
The relationship between
|
|
.BR poll ()
|
|
and
|
|
.BR ppoll ()
|
|
is analogous to the relationship between
|
|
.BR select (2)
|
|
and
|
|
.BR pselect (2):
|
|
like
|
|
.BR pselect (2),
|
|
.BR ppoll ()
|
|
allows an application to safely wait until either a file descriptor
|
|
becomes ready or until a signal is caught.
|
|
.PP
|
|
Other than the difference in the precision of the
|
|
.I timeout
|
|
argument, the following
|
|
.BR ppoll ()
|
|
call:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
ready = ppoll(&fds, nfds, tmo_p, &sigmask);
|
|
.EE
|
|
.in
|
|
.PP
|
|
is equivalent to
|
|
.I atomically
|
|
executing the following calls:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
sigset_t origmask;
|
|
int timeout;
|
|
|
|
timeout = (tmo_p == NULL) ? \-1 :
|
|
(tmo_p\->tv_sec * 1000 + tmo_p\->tv_nsec / 1000000);
|
|
pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
|
|
ready = poll(&fds, nfds, timeout);
|
|
pthread_sigmask(SIG_SETMASK, &origmask, NULL);
|
|
.EE
|
|
.in
|
|
.PP
|
|
See the description of
|
|
.BR pselect (2)
|
|
for an explanation of why
|
|
.BR ppoll ()
|
|
is necessary.
|
|
.PP
|
|
If the
|
|
.I sigmask
|
|
argument is specified as NULL, then
|
|
no signal mask manipulation is performed
|
|
(and thus
|
|
.BR ppoll ()
|
|
differs from
|
|
.BR poll ()
|
|
only in the precision of the
|
|
.I timeout
|
|
argument).
|
|
.PP
|
|
The
|
|
.I tmo_p
|
|
argument specifies an upper limit on the amount of time that
|
|
.BR ppoll ()
|
|
will block.
|
|
This argument is a pointer to a structure of the following form:
|
|
.PP
|
|
.in +4n
|
|
.EX
|
|
struct timespec {
|
|
long tv_sec; /* seconds */
|
|
long tv_nsec; /* nanoseconds */
|
|
};
|
|
.EE
|
|
.in
|
|
.PP
|
|
If
|
|
.I tmo_p
|
|
is specified as NULL, then
|
|
.BR ppoll ()
|
|
can block indefinitely.
|
|
.SH RETURN VALUE
|
|
On success, a positive number is returned; this is
|
|
the number of structures which have nonzero
|
|
.I revents
|
|
fields (in other words, those descriptors with events or errors reported).
|
|
A value of 0 indicates that the call timed out and no file
|
|
descriptors were ready.
|
|
On error, \-1 is returned, and
|
|
.I errno
|
|
is set appropriately.
|
|
.SH ERRORS
|
|
.TP
|
|
.B EFAULT
|
|
The array given as argument was not contained in the calling program's
|
|
address space.
|
|
.TP
|
|
.B EINTR
|
|
A signal occurred before any requested event; see
|
|
.BR signal (7).
|
|
.TP
|
|
.B EINVAL
|
|
The
|
|
.I nfds
|
|
value exceeds the
|
|
.B RLIMIT_NOFILE
|
|
value.
|
|
.TP
|
|
.B ENOMEM
|
|
There was no space to allocate file descriptor tables.
|
|
.SH VERSIONS
|
|
The
|
|
.BR poll ()
|
|
system call was introduced in Linux 2.1.23.
|
|
On older kernels that lack this system call,
|
|
.\" library call was introduced in libc 5.4.28
|
|
the glibc (and the old Linux libc)
|
|
.BR poll ()
|
|
wrapper function provides emulation using
|
|
.BR select (2).
|
|
.PP
|
|
The
|
|
.BR ppoll ()
|
|
system call was added to Linux in kernel 2.6.16.
|
|
The
|
|
.BR ppoll ()
|
|
library call was added in glibc 2.4.
|
|
.SH CONFORMING TO
|
|
.BR poll ()
|
|
conforms to POSIX.1-2001 and POSIX.1-2008.
|
|
.BR ppoll ()
|
|
is Linux-specific.
|
|
.\" NetBSD 3.0 has a pollts() which is like Linux ppoll().
|
|
.SH NOTES
|
|
The operation of
|
|
.BR poll ()
|
|
and
|
|
.BR ppoll ()
|
|
is not affected by the
|
|
.BR O_NONBLOCK
|
|
flag.
|
|
.PP
|
|
On some other UNIX systems,
|
|
.\" Darwin, according to a report by Jeremy Sequoia, relayed by Josh Triplett
|
|
.BR poll ()
|
|
can fail with the error
|
|
.B EAGAIN
|
|
if the system fails to allocate kernel-internal resources, rather than
|
|
.B ENOMEM
|
|
as Linux does.
|
|
POSIX permits this behavior.
|
|
Portable programs may wish to check for
|
|
.B EAGAIN
|
|
and loop, just as with
|
|
.BR EINTR .
|
|
.PP
|
|
Some implementations define the nonstandard constant
|
|
.B INFTIM
|
|
with the value \-1 for use as a
|
|
.IR timeout
|
|
for
|
|
.BR poll ().
|
|
This constant is not provided in glibc.
|
|
.PP
|
|
For a discussion of what may happen if a file descriptor being monitored by
|
|
.BR poll ()
|
|
is closed in another thread, see
|
|
.BR select (2).
|
|
.SS C library/kernel differences
|
|
The Linux
|
|
.BR ppoll ()
|
|
system call modifies its
|
|
.I tmo_p
|
|
argument.
|
|
However, the glibc wrapper function hides this behavior
|
|
by using a local variable for the timeout argument that
|
|
is passed to the system call.
|
|
Thus, the glibc
|
|
.BR ppoll ()
|
|
function does not modify its
|
|
.I tmo_p
|
|
argument.
|
|
.PP
|
|
The raw
|
|
.BR ppoll ()
|
|
system call has a fifth argument,
|
|
.IR "size_t sigsetsize" ,
|
|
which specifies the size in bytes of the
|
|
.IR sigmask
|
|
argument.
|
|
The glibc
|
|
.BR ppoll ()
|
|
wrapper function specifies this argument as a fixed value
|
|
(equal to
|
|
.IR sizeof(kernel_sigset_t) ).
|
|
See
|
|
.BR sigprocmask (2)
|
|
for a discussion on the differences between the kernel and the libc
|
|
notion of the sigset.
|
|
.SH BUGS
|
|
See the discussion of spurious readiness notifications under the
|
|
BUGS section of
|
|
.BR select (2).
|
|
.SH SEE ALSO
|
|
.BR restart_syscall (2),
|
|
.BR select (2),
|
|
.BR select_tut (2),
|
|
.BR epoll (7),
|
|
.BR time (7)
|