mirror of https://github.com/mkerrisk/man-pages
320 lines
7.5 KiB
Groff
320 lines
7.5 KiB
Groff
.\" Hey Emacs! This file is -*- nroff -*- source.
|
|
.\"
|
|
.\" Copyright (C) 1997 Andries Brouwer (aeb@cwi.nl)
|
|
.\" and Copyright (C) 2006, Michael Kerrisk <mtk.manpages@gmail.com>
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\" FIXME . 2.6.17 has a definition for POLLREMOVE, but this
|
|
.\" flag is not used in the code. Check later to see if it
|
|
.\" does get a use. 2.6.21 still shows no use.
|
|
.\"
|
|
.TH POLL 2 2006-03-13 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
poll, ppoll \- wait for some event on a file descriptor
|
|
.SH SYNOPSIS
|
|
.nf
|
|
.B #include <poll.h>
|
|
.sp
|
|
.BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout );
|
|
.sp
|
|
.B #define _GNU_SOURCE
|
|
.B #include <poll.h>
|
|
.sp
|
|
.BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ", "
|
|
.BI " const struct timespec *" timeout ", 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.
|
|
|
|
The set of file descriptors to be monitored is specified in the
|
|
.I fds
|
|
argument, which is an array of
|
|
.I nfds
|
|
structures of the following form:
|
|
.nf
|
|
|
|
struct pollfd {
|
|
int fd; /* file descriptor */
|
|
short events; /* requested events */
|
|
short revents; /* returned events */
|
|
};
|
|
|
|
.fi
|
|
The field
|
|
.I fd
|
|
contains a file descriptor for an open file.
|
|
|
|
The field
|
|
.I events
|
|
is an input parameter, a bit mask specifying the events the application
|
|
is interested in.
|
|
|
|
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.)
|
|
|
|
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.
|
|
|
|
The
|
|
.I timeout
|
|
argument specifies an upper limit on the time for which
|
|
.BR poll ()
|
|
will block, in milliseconds.
|
|
Specifying a negative value in
|
|
.I timeout
|
|
means an infinite timeout.
|
|
|
|
The bits that may be set/returned in
|
|
.I events
|
|
and
|
|
.I revents
|
|
are defined in \fI<poll.h>\fP:
|
|
.RS
|
|
.TP
|
|
.B POLLIN
|
|
There is data to read.
|
|
.TP
|
|
.B POLLPRI
|
|
There is urgent data to read (e.g., out-of-band data on TCP socket;
|
|
pseudo-terminal master in packet mode has seen state change in slave).
|
|
.TP
|
|
.B POLLOUT
|
|
Writing now will not block.
|
|
.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 in order to obtain this definition.
|
|
.TP
|
|
.B POLLERR
|
|
Error condition (output only).
|
|
.TP
|
|
.B POLLHUP
|
|
Hang up (output only).
|
|
.TP
|
|
.B POLLNVAL
|
|
Invalid request:
|
|
.I fd
|
|
not open (output only).
|
|
.RE
|
|
.PP
|
|
When compiling with
|
|
.B _XOPEN_SOURCE
|
|
defined, one also has the following,
|
|
which convey no further information beyond the bits listed above:
|
|
.RS
|
|
.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.
|
|
.RE
|
|
.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
|
|
.I timeout
|
|
argument, the following
|
|
.BR ppoll ()
|
|
call:
|
|
.nf
|
|
|
|
ready = ppoll(&fds, nfds, timeout, &sigmask);
|
|
|
|
.fi
|
|
is equivalent to
|
|
.I atomically
|
|
executing the following calls:
|
|
.nf
|
|
|
|
sigset_t origmask;
|
|
|
|
sigprocmask(SIG_SETMASK, &sigmask, &origmask);
|
|
ready = poll(&fds, nfds, timeout);
|
|
sigprocmask(SIG_SETMASK, &origmask, NULL);
|
|
.fi
|
|
.PP
|
|
See the description of
|
|
.BR pselect (2)
|
|
for an explanation of why
|
|
.BR ppoll ()
|
|
is necessary.
|
|
|
|
The
|
|
.I timeout
|
|
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:
|
|
.in +0.25i
|
|
.nf
|
|
|
|
struct timespec {
|
|
long tv_sec; /* seconds */
|
|
long tv_nsec; /* nanoseconds */
|
|
};
|
|
.fi
|
|
.in -0.25i
|
|
|
|
If
|
|
.I timeout
|
|
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 non-zero
|
|
.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 EBADF
|
|
An invalid file descriptor was given in one of the sets.
|
|
.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.
|
|
.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.
|
|
The
|
|
.BR poll ()
|
|
library call was introduced in libc 5.4.28
|
|
(and provides emulation using select(2) if your kernel does not
|
|
have a
|
|
.BR poll ()
|
|
system call).
|
|
|
|
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.
|
|
.BR ppoll ()
|
|
is Linux specific.
|
|
.\" NetBSD 3.0 has a pollts() which is like Linux ppoll().
|
|
.SH NOTES
|
|
Some implementations define the non-standard constant
|
|
.B INFTIM
|
|
with the value \-1 for use as a
|
|
.IR timeout .
|
|
This constant is not provided in glibc.
|
|
.SS "Linux Notes"
|
|
The Linux
|
|
.BR ppoll ()
|
|
system call modifies its
|
|
.I timeout
|
|
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 timeout
|
|
argument.
|
|
.SH BUGS
|
|
See the discussion of spurious readiness notifications under the
|
|
BUGS section of
|
|
.BR select (2).
|
|
.SH "SEE ALSO"
|
|
.BR select (2),
|
|
.BR select_tut (2),
|
|
.BR feature_test_macros (7)
|