-.\"
-.\" epoll by Davide Libenzi ( efficient event notification retrieval )
.\" Copyright (C) 2003 Davide Libenzi
.\"
+.\" %%%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
+.\" 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
.\"
.\" Davide Libenzi <davidel@xmailserver.org>
.\"
-.TH EPOLL 7 2009-02-01 "Linux" "Linux Programmer's Manual"
+.TH EPOLL 7 2015-01-10 "Linux" "Linux Programmer's Manual"
.SH NAME
epoll \- I/O event notification facility
.SH SYNOPSIS
.B #include <sys/epoll.h>
.SH DESCRIPTION
+The
+.B epoll
+API performs a similar task to
+.BR poll (2):
+monitoring multiple file descriptors to see if I/O is possible on any of them.
+The
.B epoll
-is a variant of
-.BR poll (2)
-that can be used either as an edge-triggered or a level-triggered
+API can be used either as an edge-triggered or a level-triggered
interface and scales well to large numbers of watched file descriptors.
The following system calls are provided to
create and manage an
.B epoll
instance:
.IP * 3
-An
+.BR epoll_create (2)
+creates an
.B epoll
-instance created by
-.BR epoll_create (2),
-which returns a file descriptor referring to the epoll instance.
+instance and returns a file descriptor referring to that instance.
(The more recent
.BR epoll_create1 (2)
extends the functionality of
.I epoll
set.
.IP *
-Finally, the actual wait is started by
-.BR epoll_wait (2).
-.SS Level-Triggered and Edge-Triggered
+.BR epoll_wait (2)
+waits for I/O events,
+blocking the calling thread if no events are currently available.
+.SS Level-triggered and edge-triggered
The
.B epoll
event distribution interface is able to behave both as edge-triggered
input buffer;
meanwhile the remote peer might be expecting a response based on the
data it already sent.
-The reason for this is that edge-triggered mode only
-delivers events when changes occur on the monitored file descriptor.
+The reason for this is that edge-triggered mode
+delivers events only when changes occur on the monitored file descriptor.
So, in step
.B 5
the caller might end up waiting for some data that is already present inside
.BR epoll_ctl (2)
with
.BR EPOLL_CTL_MOD .
+.SS Interaction with autosleep
+If the system is in
+.B autosleep
+mode via
+.I /sys/power/autosleep
+and an event happens which wakes the device from sleep, the device
+driver will keep the device awake only until that event is queued.
+To keep the device awake until the event has been processed,
+it is necessary to use the
+.BR epoll (7)
+.B EPOLLWAKEUP
+flag.
+
+When the
+.B EPOLLWAKEUP
+flag is set in the
+.B events
+field for a
+.IR "struct epoll_event" ,
+the system will be kept awake from the moment the event is queued,
+through the
+.BR epoll_wait (2)
+call which returns the event until the subsequent
+.BR epoll_wait (2)
+call.
+If the event should keep the system awake beyond that time,
+then a separate
+.I wake_lock
+should be taken before the second
+.BR epoll_wait (2)
+call.
.SS /proc interfaces
The following interfaces can be used to limit the amount of
kernel memory consumed by epoll:
.I max_user_watches
is 1/25 (4%) of the available low memory,
divided by the registration cost in bytes.
-.SS Example for Suggested Usage
+.SS Example for suggested usage
While the usage of
.B epoll
when employed as a level-triggered interface does have the same
struct epoll_event ev, events[MAX_EVENTS];
int listen_sock, conn_sock, nfds, epollfd;
-/* Set up listening socket, \(aqlisten_sock\(aq (socket(),
- bind(), listen()) */
+/* Code to set up listening socket, \(aqlisten_sock\(aq,
+ (socket(), bind(), listen()) omitted */
-epollfd = epoll_create(10);
+epollfd = epoll_create1(0);
if (epollfd == \-1) {
- perror("epoll_create");
+ perror("epoll_create1");
exit(EXIT_FAILURE);
}
.BR epoll_ctl (2)
with
.BR EPOLL_CTL_MOD .
-.SS Questions and Answers
+.SS Questions and answers
.TP 4
.B Q0
What is the key used to distinguish the file descriptors registered in an
Yes.
If an
.B epoll
-file descriptor has events waiting then it will
+file descriptor has events waiting, then it will
indicate as being readable.
.TP
.B Q4
set only after all the file descriptors referring to the underlying
open file description have been closed
(or before if the descriptor is explicitly removed using
-.BR epoll_ctl ()
+.BR epoll_ctl (2)
.BR EPOLL_CTL_DEL ).
This means that even after a file descriptor that is part of an
.B epoll
.BR write (2).
(Avoid this latter technique if you cannot guarantee that
the monitored file descriptor always refers to a stream-oriented file.)
-.SS Possible Pitfalls and Ways to Avoid Them
+.SS Possible pitfalls and ways to avoid them
.TP
.B o Starvation (edge-triggered)
.PP
.IR kqueue ,
and Solaris has
.IR /dev/poll .
-.SH "SEE ALSO"
+.SH SEE ALSO
.BR epoll_create (2),
.BR epoll_create1 (2),
.BR epoll_ctl (2),
.BR epoll_wait (2)
+.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
