-.\"
-.\" epoll by Davide Libenzi ( efficient event notification retrieval )
.\" Copyright (C) 2003 Davide Libenzi
+.\" Davide Libenzi <davidel@xmailserver.org>
.\"
+.\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
.\" This program is free software; you can redistribute it and/or modify
.\" it under the terms of the GNU General Public License as published by
.\" the Free Software Foundation; either version 2 of the License, or
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
.\" GNU General Public License for more details.
.\"
-.\" You should have received a copy of the GNU General Public License
-.\" along with this program; if not, write to the Free Software
-.\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
-.\"
-.\" Davide Libenzi <davidel@xmailserver.org>
+.\" You should have received a copy of the GNU General Public
+.\" License along with this manual; if not, see
+.\" <http://www.gnu.org/licenses/>.
+.\" %%%LICENSE_END
.\"
.\" 2007-04-30: mtk, Added description of epoll_pwait()
.\"
-.TH EPOLL_WAIT 2 2009-01-17 "Linux" "Linux Programmer's Manual"
+.TH EPOLL_WAIT 2 2014-01-31 "Linux" "Linux Programmer's Manual"
.SH NAME
epoll_wait, epoll_pwait \- wait for an I/O event on an epoll file descriptor
.SH SYNOPSIS
The
.BR epoll_wait ()
system call waits for events on the
-.B epoll
+.BR epoll (7)
instance referred to by the file descriptor
.IR epfd .
The memory area pointed to by
.I maxevents
argument must be greater than zero.
-The call waits for a maximum time of
+The
.I timeout
-milliseconds.
+argument specifies the number of milliseconds that
+.BR epoll_wait ()
+will block.
+The call will block until either:
+.IP * 3
+a file descriptor delivers an event;
+.IP *
+the call is interrupted by a signal handler; or
+.IP *
+the timout 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
.I timeout
-of \-1 makes
+of \-1 causes
.BR epoll_wait ()
-wait indefinitely, while specifying a
+to block indefinitely, while specifying a
.I timeout
-equal to zero makes
+equal to zero cause
.BR epoll_wait ()
-to return immediately even if no events are available
-(return code equal to zero).
+to return immediately, even if no events are available.
The
.I struct epoll_event
.I data
of each returned structure will contain the same data the user set with an
.BR epoll_ctl (2)
-.RB ( EPOLL_CTL_ADD , EPOLL_CTL_MOD )
+.RB ( EPOLL_CTL_ADD ", " EPOLL_CTL_MOD )
while the
.I events
member will contain the returned event bit field.
.BR epoll_pwait ()
is equivalent to
.BR epoll_wait ().
-.SH "RETURN VALUE"
+.SH RETURN VALUE
When successful,
.BR epoll_wait ()
returns the number of file descriptors ready for the requested I/O, or zero
is not accessible with write permissions.
.TP
.B EINTR
-The call was interrupted by a signal handler before any of the
-requested events occurred or the
+The call was interrupted by a signal handler before either (1) any of the
+requested events occurred or (2) the
.I timeout
expired; see
.BR signal (7).
.I maxevents
is less than or equal to zero.
.SH VERSIONS
-.BR epoll_pwait ()
-was added to Linux in kernel 2.6.19.
+.BR epoll_wait ()
+was added to the kernel in version 2.6.
+.\" To be precise: kernel 2.5.44.
+.\" The interface should be finalized by Linux kernel 2.5.66.
+Library support is provided in glibc starting with version 2.3.2.
-Glibc support for
.BR epoll_pwait ()
-is provided starting with version 2.6.
+was added to Linux in kernel 2.6.19.
+Library support is provided in glibc starting with version 2.6.
.SH CONFORMING TO
.BR epoll_wait ()
-is Linux-specific, and was introduced in kernel 2.5.44.
-.\" The interface should be finalized by Linux kernel 2.5.66.
-.SH "SEE ALSO"
+is Linux-specific.
+.SH NOTES
+While one thread is blocked in a call to
+.BR epoll_pwait (),
+it is possible for another thread to add a file descriptor to the waited-upon
+.B epoll
+instance.
+If the new file descriptor becomes ready,
+it will cause the
+.BR epoll_wait ()
+call to unblock.
+
+For a discussion of what may happen if a file descriptor in an
+.B epoll
+instance being monitored by
+.BR epoll_wait ()
+is closed in another thread, see
+.BR select (2).
+.SH BUGS
+In kernels before 2.6.37, a
+.I timeout
+value larger than approximately
+.I LONG_MAX / HZ
+milliseconds is treated as \-1 (i.e., infinity).
+Thus, for example, on a system where the
+.I sizeof(long)
+is 4 and the kernel
+.I HZ
+value is 1000,
+this means that timeouts greater than 35.79 minutes are treated as infinity.
+.SH SEE ALSO
.BR epoll_create (2),
.BR epoll_ctl (2),
.BR epoll (7)
+.SH COLOPHON
+This page is part of release 3.65 of the Linux
+.I man-pages
+project.
+A description of the project,
+and information about reporting bugs,
+can be found at
+\%http://www.kernel.org/doc/man\-pages/.
OSDN Git Service
