+++ /dev/null
-.\" 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 2014-09-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>
-.sp
-.BI "int poll(struct pollfd *" fds ", nfds_t " nfds ", int " timeout );
-.sp
-.BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
-.B #include <signal.h>
-.B #include <poll.h>
-.sp
-.BI "int ppoll(struct pollfd *" fds ", nfds_t " nfds ", "
-.BI " const struct timespec *" timeout_ts ", 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 structures of the following form:
-.in +4n
-.nf
-
-struct pollfd {
- int fd; /* file descriptor */
- short events; /* requested events */
- short revents; /* returned events */
-};
-.in
-.fi
-.PP
-The caller should specify the number of items in the
-.I fds
-array in
-.IR nfds .
-
-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.)
-
-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).
-
-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 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.
-
-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;
-pseudoterminal master in packet mode has seen state change in slave).
-.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 (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 precision of the
-.I timeout
-argument, the following
-.BR ppoll ()
-call:
-.nf
-
- ready = ppoll(&fds, nfds, timeout_ts, &sigmask);
-
-.fi
-is equivalent to
-.I atomically
-executing the following calls:
-.nf
-
- sigset_t origmask;
- int timeout;
-
- timeout = (timeout_ts == NULL) ? \-1 :
- (timeout_ts.tv_sec * 1000 + timeout_ts.tv_nsec / 1000000);
- 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.
-
-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).
-
-The
-.I timeout_ts
-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 +4n
-.nf
-
-struct timespec {
- long tv_sec; /* seconds */
- long tv_nsec; /* nanoseconds */
-};
-.fi
-.in
-
-If
-.I timeout_ts
-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).
-
-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 nonstandard constant
-.B INFTIM
-with the value \-1 for use as a
-.IR timeout
-for
-.BR poll ().
-This constant is not provided in glibc.
-
-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 ABI differences
-The Linux
-.BR ppoll ()
-system call modifies its
-.I timeout_ts
-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_ts
-argument.
-
-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(sigset_t) ).
-.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 time (7)
-.SH COLOPHON
-This page is part of release 3.79 of the Linux
-.I man-pages
-project.
-A description of the project,
-information about reporting bugs,
-and the latest version of this page,
-can be found at
-\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
