691 lines
14 KiB
HTML
691 lines
14 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of POLL</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>POLL</H1>
|
|
Section: Linux Programmer's Manual (2)<BR>Updated: 2019-08-02<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
poll, ppoll - wait for some event on a file descriptor
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<PRE>
|
|
<B>#include <<A HREF="file:///usr/include/poll.h">poll.h</A>></B>
|
|
|
|
<B>int poll(struct pollfd *</B><I>fds</I><B>, nfds_t </B><I>nfds</I><B>, int </B><I>timeout</I><B>);</B>
|
|
|
|
<B>#define _GNU_SOURCE</B> /* See <A HREF="/cgi-bin/man/man2html?7+feature_test_macros">feature_test_macros</A>(7) */
|
|
<B>#include <<A HREF="file:///usr/include/signal.h">signal.h</A>></B>
|
|
<B>#include <<A HREF="file:///usr/include/poll.h">poll.h</A>></B>
|
|
|
|
<B>int ppoll(struct pollfd *</B><I>fds</I><B>, nfds_t </B><I>nfds</I><B>, </B>
|
|
<B> const struct timespec *</B><I>tmo_p</I><B>, const sigset_t *</B><I>sigmask</I><B>);</B>
|
|
</PRE>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
<B>poll</B>()
|
|
|
|
performs a similar task to
|
|
<B><A HREF="/cgi-bin/man/man2html?2+select">select</A></B>(2):
|
|
|
|
it waits for one of a set of file descriptors to become ready
|
|
to perform I/O.
|
|
<P>
|
|
|
|
The set of file descriptors to be monitored is specified in the
|
|
<I>fds</I>
|
|
|
|
argument, which is an array of structures of the following form:
|
|
<P>
|
|
|
|
|
|
|
|
struct pollfd {
|
|
<BR> int fd; /* file descriptor */
|
|
<BR> short events; /* requested events */
|
|
<BR> short revents; /* returned events */
|
|
};
|
|
|
|
|
|
<P>
|
|
|
|
The caller should specify the number of items in the
|
|
<I>fds</I>
|
|
|
|
array in
|
|
<I>nfds</I>.
|
|
|
|
<P>
|
|
|
|
The field
|
|
<I>fd</I>
|
|
|
|
contains a file descriptor for an open file.
|
|
If this field is negative, then the corresponding
|
|
<I>events</I>
|
|
|
|
field is ignored and the
|
|
<I>revents</I>
|
|
|
|
field returns zero.
|
|
(This provides an easy way of ignoring a
|
|
file descriptor for a single
|
|
<B>poll</B>()
|
|
|
|
call: simply negate the
|
|
<I>fd</I>
|
|
|
|
field.
|
|
Note, however, that this technique can't be used to ignore file descriptor 0.)
|
|
<P>
|
|
|
|
The field
|
|
<I>events</I>
|
|
|
|
is an input parameter, a bit mask specifying the events the application
|
|
is interested in for the file descriptor
|
|
<I>fd</I>.
|
|
|
|
This field may be specified as zero,
|
|
in which case the only events that can be returned in
|
|
<I>revents</I>
|
|
|
|
are
|
|
<B>POLLHUP</B>,
|
|
|
|
<B>POLLERR</B>,
|
|
|
|
and
|
|
<B>POLLNVAL</B>
|
|
|
|
(see below).
|
|
<P>
|
|
|
|
The field
|
|
<I>revents</I>
|
|
|
|
is an output parameter, filled by the kernel with the events that
|
|
actually occurred.
|
|
The bits returned in
|
|
<I>revents</I>
|
|
|
|
can include any of those specified in
|
|
<I>events</I>,
|
|
|
|
or one of the values
|
|
<B>POLLERR</B>,
|
|
|
|
<B>POLLHUP</B>,
|
|
|
|
or
|
|
<B>POLLNVAL</B>.
|
|
|
|
(These three bits are meaningless in the
|
|
<I>events</I>
|
|
|
|
field, and will be set in the
|
|
<I>revents</I>
|
|
|
|
field whenever the corresponding condition is true.)
|
|
<P>
|
|
|
|
If none of the events requested (and no error) has occurred for any
|
|
of the file descriptors, then
|
|
<B>poll</B>()
|
|
|
|
blocks until one of the events occurs.
|
|
<P>
|
|
|
|
The
|
|
<I>timeout</I>
|
|
|
|
argument specifies the number of milliseconds that
|
|
<B>poll</B>()
|
|
|
|
should block waiting for a file descriptor to become ready.
|
|
The call will block until either:
|
|
<DL COMPACT>
|
|
<DT id="1">*<DD>
|
|
a file descriptor becomes ready;
|
|
<DT id="2">*<DD>
|
|
the call is interrupted by a signal handler; or
|
|
<DT id="3">*<DD>
|
|
the timeout expires.
|
|
</DL>
|
|
<P>
|
|
|
|
Note that the
|
|
<I>timeout</I>
|
|
|
|
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</I>
|
|
|
|
means an infinite timeout.
|
|
Specifying a
|
|
<I>timeout</I>
|
|
|
|
of zero causes
|
|
<B>poll</B>()
|
|
|
|
to return immediately, even if no file descriptors are ready.
|
|
<P>
|
|
|
|
The bits that may be set/returned in
|
|
<I>events</I>
|
|
|
|
and
|
|
<I>revents</I>
|
|
|
|
are defined in <I><<A HREF="file:///usr/include/poll.h">poll.h</A>></I>:
|
|
<DL COMPACT>
|
|
<DT id="4"><B>POLLIN</B>
|
|
|
|
<DD>
|
|
There is data to read.
|
|
<DT id="5"><B>POLLPRI</B>
|
|
|
|
<DD>
|
|
There is some exceptional condition on the file descriptor.
|
|
Possibilities include:
|
|
<DL COMPACT><DT id="6"><DD>
|
|
<DL COMPACT>
|
|
<DT id="7">*<DD>
|
|
There is out-of-band data on a TCP socket (see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+tcp">tcp</A></B>(7)).
|
|
|
|
<DT id="8">*<DD>
|
|
A pseudoterminal master in packet mode has seen a state change on the slave
|
|
(see
|
|
<B><A HREF="/cgi-bin/man/man2html?2+ioctl_tty">ioctl_tty</A></B>(2)).
|
|
|
|
<DT id="9">*<DD>
|
|
A
|
|
<I>cgroup.events</I>
|
|
|
|
file has been modified (see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+cgroups">cgroups</A></B>(7)).
|
|
|
|
</DL>
|
|
</DL>
|
|
|
|
<DT id="10"><B>POLLOUT</B>
|
|
|
|
<DD>
|
|
Writing is now possible, though a write larger that the available space
|
|
in a socket or pipe will still block (unless
|
|
<B>O_NONBLOCK</B>
|
|
|
|
is set).
|
|
<DT id="11"><B>POLLRDHUP</B> (since Linux 2.6.17)
|
|
|
|
<DD>
|
|
Stream socket peer closed connection,
|
|
or shut down writing half of connection.
|
|
The
|
|
<B>_GNU_SOURCE</B>
|
|
|
|
feature test macro must be defined
|
|
(before including
|
|
<I>any</I>
|
|
|
|
header files)
|
|
in order to obtain this definition.
|
|
<DT id="12"><B>POLLERR</B>
|
|
|
|
<DD>
|
|
Error condition (only returned in
|
|
<I>revents</I>;
|
|
|
|
ignored in
|
|
<I>events</I>).
|
|
|
|
This bit is also set for a file descriptor referring
|
|
to the write end of a pipe when the read end has been closed.
|
|
<DT id="13"><B>POLLHUP</B>
|
|
|
|
<DD>
|
|
Hang up (only returned in
|
|
<I>revents</I>;
|
|
|
|
ignored in
|
|
<I>events</I>).
|
|
|
|
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.
|
|
<DT id="14"><B>POLLNVAL</B>
|
|
|
|
<DD>
|
|
Invalid request:
|
|
<I>fd</I>
|
|
|
|
not open (only returned in
|
|
<I>revents</I>;
|
|
|
|
ignored in
|
|
<I>events</I>).
|
|
|
|
</DL>
|
|
<P>
|
|
|
|
When compiling with
|
|
<B>_XOPEN_SOURCE</B>
|
|
|
|
defined, one also has the following,
|
|
which convey no further information beyond the bits listed above:
|
|
<DL COMPACT>
|
|
<DT id="15"><B>POLLRDNORM</B>
|
|
|
|
<DD>
|
|
Equivalent to
|
|
<B>POLLIN</B>.
|
|
|
|
<DT id="16"><B>POLLRDBAND</B>
|
|
|
|
<DD>
|
|
Priority band data can be read (generally unused on Linux).
|
|
|
|
<DT id="17"><B>POLLWRNORM</B>
|
|
|
|
<DD>
|
|
Equivalent to
|
|
<B>POLLOUT</B>.
|
|
|
|
<DT id="18"><B>POLLWRBAND</B>
|
|
|
|
<DD>
|
|
Priority data may be written.
|
|
</DL>
|
|
<P>
|
|
|
|
Linux also knows about, but does not use
|
|
<B>POLLMSG</B>.
|
|
|
|
<A NAME="lbAE"> </A>
|
|
<H3>ppoll()</H3>
|
|
|
|
The relationship between
|
|
<B>poll</B>()
|
|
|
|
and
|
|
<B>ppoll</B>()
|
|
|
|
is analogous to the relationship between
|
|
<B><A HREF="/cgi-bin/man/man2html?2+select">select</A></B>(2)
|
|
|
|
and
|
|
<B><A HREF="/cgi-bin/man/man2html?2+pselect">pselect</A></B>(2):
|
|
|
|
like
|
|
<B><A HREF="/cgi-bin/man/man2html?2+pselect">pselect</A></B>(2),
|
|
|
|
<B>ppoll</B>()
|
|
|
|
allows an application to safely wait until either a file descriptor
|
|
becomes ready or until a signal is caught.
|
|
<P>
|
|
|
|
Other than the difference in the precision of the
|
|
<I>timeout</I>
|
|
|
|
argument, the following
|
|
<B>ppoll</B>()
|
|
|
|
call:
|
|
<P>
|
|
|
|
|
|
|
|
ready = ppoll(&fds, nfds, tmo_p, &sigmask);
|
|
|
|
|
|
<P>
|
|
|
|
is nearly equivalent to
|
|
<I>atomically</I>
|
|
|
|
executing the following calls:
|
|
<P>
|
|
|
|
|
|
|
|
sigset_t origmask;
|
|
int timeout;
|
|
<P>
|
|
timeout = (tmo_p == NULL) ? -1 :
|
|
<BR> (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);
|
|
|
|
|
|
<P>
|
|
|
|
The above code segment is described as
|
|
<I>nearly</I>
|
|
|
|
equivalent because whereas a negative
|
|
<I>timeout</I>
|
|
|
|
value for
|
|
<B>poll</B>()
|
|
|
|
is interpreted as an infinite timeout, a negative value expressed in
|
|
<I>*tmo_p</I>
|
|
|
|
results in an error from
|
|
<B>ppoll</B>().
|
|
|
|
<P>
|
|
|
|
See the description of
|
|
<B><A HREF="/cgi-bin/man/man2html?2+pselect">pselect</A></B>(2)
|
|
|
|
for an explanation of why
|
|
<B>ppoll</B>()
|
|
|
|
is necessary.
|
|
<P>
|
|
|
|
If the
|
|
<I>sigmask</I>
|
|
|
|
argument is specified as NULL, then
|
|
no signal mask manipulation is performed
|
|
(and thus
|
|
<B>ppoll</B>()
|
|
|
|
differs from
|
|
<B>poll</B>()
|
|
|
|
only in the precision of the
|
|
<I>timeout</I>
|
|
|
|
argument).
|
|
<P>
|
|
|
|
The
|
|
<I>tmo_p</I>
|
|
|
|
argument specifies an upper limit on the amount of time that
|
|
<B>ppoll</B>()
|
|
|
|
will block.
|
|
This argument is a pointer to a structure of the following form:
|
|
<P>
|
|
|
|
|
|
|
|
struct timespec {
|
|
<BR> long tv_sec; /* seconds */
|
|
<BR> long tv_nsec; /* nanoseconds */
|
|
};
|
|
|
|
|
|
<P>
|
|
|
|
If
|
|
<I>tmo_p</I>
|
|
|
|
is specified as NULL, then
|
|
<B>ppoll</B>()
|
|
|
|
can block indefinitely.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
On success, a positive number is returned; this is
|
|
the number of structures which have nonzero
|
|
<I>revents</I>
|
|
|
|
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</I>
|
|
|
|
is set appropriately.
|
|
<A NAME="lbAG"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="19"><B>EFAULT</B>
|
|
|
|
<DD>
|
|
The array given as argument was not contained in the calling program's
|
|
address space.
|
|
<DT id="20"><B>EINTR</B>
|
|
|
|
<DD>
|
|
A signal occurred before any requested event; see
|
|
<B><A HREF="/cgi-bin/man/man2html?7+signal">signal</A></B>(7).
|
|
|
|
<DT id="21"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
The
|
|
<I>nfds</I>
|
|
|
|
value exceeds the
|
|
<B>RLIMIT_NOFILE</B>
|
|
|
|
value.
|
|
<DT id="22"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
(<B>ppoll</B>())
|
|
|
|
The timeout value expressed in
|
|
<I>*ip</I>
|
|
|
|
is invalid (negative).
|
|
<DT id="23"><B>ENOMEM</B>
|
|
|
|
<DD>
|
|
There was no space to allocate file descriptor tables.
|
|
</DL>
|
|
<A NAME="lbAH"> </A>
|
|
<H2>VERSIONS</H2>
|
|
|
|
The
|
|
<B>poll</B>()
|
|
|
|
system call was introduced in Linux 2.1.23.
|
|
On older kernels that lack this system call,
|
|
|
|
the glibc (and the old Linux libc)
|
|
<B>poll</B>()
|
|
|
|
wrapper function provides emulation using
|
|
<B><A HREF="/cgi-bin/man/man2html?2+select">select</A></B>(2).
|
|
|
|
<P>
|
|
|
|
The
|
|
<B>ppoll</B>()
|
|
|
|
system call was added to Linux in kernel 2.6.16.
|
|
The
|
|
<B>ppoll</B>()
|
|
|
|
library call was added in glibc 2.4.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
<B>poll</B>()
|
|
|
|
conforms to POSIX.1-2001 and POSIX.1-2008.
|
|
<B>ppoll</B>()
|
|
|
|
is Linux-specific.
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
The operation of
|
|
<B>poll</B>()
|
|
|
|
and
|
|
<B>ppoll</B>()
|
|
|
|
is not affected by the
|
|
<B>O_NONBLOCK</B>
|
|
|
|
flag.
|
|
<P>
|
|
|
|
On some other UNIX systems,
|
|
|
|
<B>poll</B>()
|
|
|
|
can fail with the error
|
|
<B>EAGAIN</B>
|
|
|
|
if the system fails to allocate kernel-internal resources, rather than
|
|
<B>ENOMEM</B>
|
|
|
|
as Linux does.
|
|
POSIX permits this behavior.
|
|
Portable programs may wish to check for
|
|
<B>EAGAIN</B>
|
|
|
|
and loop, just as with
|
|
<B>EINTR</B>.
|
|
|
|
<P>
|
|
|
|
Some implementations define the nonstandard constant
|
|
<B>INFTIM</B>
|
|
|
|
with the value -1 for use as a
|
|
<I>timeout</I>
|
|
|
|
for
|
|
<B>poll</B>().
|
|
|
|
This constant is not provided in glibc.
|
|
<P>
|
|
|
|
For a discussion of what may happen if a file descriptor being monitored by
|
|
<B>poll</B>()
|
|
|
|
is closed in another thread, see
|
|
<B><A HREF="/cgi-bin/man/man2html?2+select">select</A></B>(2).
|
|
|
|
<A NAME="lbAK"> </A>
|
|
<H3>C library/kernel differences</H3>
|
|
|
|
The Linux
|
|
<B>ppoll</B>()
|
|
|
|
system call modifies its
|
|
<I>tmo_p</I>
|
|
|
|
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
|
|
<B>ppoll</B>()
|
|
|
|
function does not modify its
|
|
<I>tmo_p</I>
|
|
|
|
argument.
|
|
<P>
|
|
|
|
The raw
|
|
<B>ppoll</B>()
|
|
|
|
system call has a fifth argument,
|
|
<I>size_t sigsetsize</I>,
|
|
|
|
which specifies the size in bytes of the
|
|
<I>sigmask</I>
|
|
|
|
argument.
|
|
The glibc
|
|
<B>ppoll</B>()
|
|
|
|
wrapper function specifies this argument as a fixed value
|
|
(equal to
|
|
<I>sizeof(kernel_sigset_t)</I>).
|
|
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?2+sigprocmask">sigprocmask</A></B>(2)
|
|
|
|
for a discussion on the differences between the kernel and the libc
|
|
notion of the sigset.
|
|
<A NAME="lbAL"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
See the discussion of spurious readiness notifications under the
|
|
BUGS section of
|
|
<B><A HREF="/cgi-bin/man/man2html?2+select">select</A></B>(2).
|
|
|
|
<A NAME="lbAM"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+restart_syscall">restart_syscall</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+select">select</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+select_tut">select_tut</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+epoll">epoll</A></B>(7),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+time">time</A></B>(7)
|
|
|
|
<A NAME="lbAN"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="24"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="25"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="26"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DL>
|
|
<DT id="27"><A HREF="#lbAE">ppoll()</A><DD>
|
|
</DL>
|
|
<DT id="28"><A HREF="#lbAF">RETURN VALUE</A><DD>
|
|
<DT id="29"><A HREF="#lbAG">ERRORS</A><DD>
|
|
<DT id="30"><A HREF="#lbAH">VERSIONS</A><DD>
|
|
<DT id="31"><A HREF="#lbAI">CONFORMING TO</A><DD>
|
|
<DT id="32"><A HREF="#lbAJ">NOTES</A><DD>
|
|
<DL>
|
|
<DT id="33"><A HREF="#lbAK">C library/kernel differences</A><DD>
|
|
</DL>
|
|
<DT id="34"><A HREF="#lbAL">BUGS</A><DD>
|
|
<DT id="35"><A HREF="#lbAM">SEE ALSO</A><DD>
|
|
<DT id="36"><A HREF="#lbAN">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:33 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|