2004-11-03 13:51:07 +00:00
|
|
|
.\"
|
|
|
|
.\" epoll by Davide Libenzi ( efficient event notification retrieval )
|
|
|
|
.\" Copyright (C) 2003 Davide Libenzi
|
|
|
|
.\"
|
|
|
|
.\" 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
|
|
|
|
.\" (at your option) any later version.
|
|
|
|
.\"
|
|
|
|
.\" This program is distributed in the hope that it will be useful,
|
|
|
|
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
|
|
.\" 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>
|
|
|
|
.\"
|
2007-04-30 16:08:08 +00:00
|
|
|
.\" 2007-04-30: mtk, Added description of epoll_pwait()
|
2006-11-25 04:13:21 +00:00
|
|
|
.\"
|
2009-01-15 18:40:16 +00:00
|
|
|
.TH EPOLL_WAIT 2 2009-01-17 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
2007-04-30 16:08:08 +00:00
|
|
|
epoll_wait, epoll_pwait \- wait for an I/O event on an epoll file descriptor
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH SYNOPSIS
|
2006-05-13 04:57:40 +00:00
|
|
|
.nf
|
2004-11-03 13:51:07 +00:00
|
|
|
.B #include <sys/epoll.h>
|
|
|
|
.sp
|
2007-04-12 22:42:49 +00:00
|
|
|
.BI "int epoll_wait(int " epfd ", struct epoll_event *" events ,
|
2007-04-30 16:08:08 +00:00
|
|
|
.BI " int " maxevents ", int " timeout );
|
2007-04-30 16:11:48 +00:00
|
|
|
.BI "int epoll_pwait(int " epfd ", struct epoll_event *" events ,
|
2007-06-21 22:55:04 +00:00
|
|
|
.BI " int " maxevents ", int " timeout ,
|
2007-04-30 16:08:08 +00:00
|
|
|
.BI " const sigset_t *" sigmask );
|
2006-05-13 04:57:40 +00:00
|
|
|
.fi
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
2007-04-30 16:11:48 +00:00
|
|
|
The
|
|
|
|
.BR epoll_wait ()
|
|
|
|
system call waits for events on the
|
2004-11-03 13:51:07 +00:00
|
|
|
.B epoll
|
2009-01-15 18:40:16 +00:00
|
|
|
instance referred to by the file descriptor
|
|
|
|
.IR epfd .
|
2007-04-12 22:42:49 +00:00
|
|
|
The memory area pointed to by
|
2004-11-03 13:51:07 +00:00
|
|
|
.I events
|
|
|
|
will contain the events that will be available for the caller.
|
|
|
|
Up to
|
|
|
|
.I maxevents
|
|
|
|
are returned by
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR epoll_wait ().
|
2004-11-03 13:51:07 +00:00
|
|
|
The
|
|
|
|
.I maxevents
|
2008-07-10 20:53:08 +00:00
|
|
|
argument must be greater than zero.
|
2009-01-15 18:43:02 +00:00
|
|
|
|
|
|
|
The call waits for a maximum time of
|
|
|
|
.I timeout
|
|
|
|
milliseconds.
|
2007-04-12 22:42:49 +00:00
|
|
|
Specifying a
|
2004-11-03 13:51:07 +00:00
|
|
|
.I timeout
|
|
|
|
of \-1 makes
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR epoll_wait ()
|
2004-11-03 13:51:07 +00:00
|
|
|
wait indefinitely, while specifying a
|
|
|
|
.I timeout
|
|
|
|
equal to zero makes
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR epoll_wait ()
|
2007-04-12 22:42:49 +00:00
|
|
|
to return immediately even if no events are available
|
2006-01-14 17:09:59 +00:00
|
|
|
(return code equal to zero).
|
2009-01-15 18:43:02 +00:00
|
|
|
|
2004-11-03 13:51:07 +00:00
|
|
|
The
|
2005-11-02 13:55:25 +00:00
|
|
|
.I struct epoll_event
|
2004-11-03 13:51:07 +00:00
|
|
|
is defined as :
|
|
|
|
.sp
|
2007-12-19 05:53:30 +00:00
|
|
|
.in +4n
|
2004-11-03 13:51:07 +00:00
|
|
|
.nf
|
2007-04-05 12:36:57 +00:00
|
|
|
typedef union epoll_data {
|
2007-12-19 05:53:30 +00:00
|
|
|
void *ptr;
|
|
|
|
int fd;
|
|
|
|
uint32_t u32;
|
|
|
|
uint64_t u64;
|
2007-04-05 12:36:57 +00:00
|
|
|
} epoll_data_t;
|
2004-11-03 13:51:07 +00:00
|
|
|
|
2007-04-05 12:36:57 +00:00
|
|
|
struct epoll_event {
|
2007-12-19 05:53:30 +00:00
|
|
|
uint32_t events; /* Epoll events */
|
2007-04-05 12:36:57 +00:00
|
|
|
epoll_data_t data; /* User data variable */
|
|
|
|
};
|
2004-11-03 13:51:07 +00:00
|
|
|
.fi
|
2007-12-19 05:53:30 +00:00
|
|
|
.in
|
2004-11-03 13:51:07 +00:00
|
|
|
|
|
|
|
The
|
|
|
|
.I data
|
2007-12-29 18:01:05 +00:00
|
|
|
of each returned structure will contain the same data the user set with an
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR epoll_ctl (2)
|
2007-12-16 13:47:37 +00:00
|
|
|
.RB ( EPOLL_CTL_ADD , EPOLL_CTL_MOD )
|
2004-11-03 13:51:07 +00:00
|
|
|
while the
|
|
|
|
.I events
|
|
|
|
member will contain the returned event bit field.
|
2007-04-30 16:08:08 +00:00
|
|
|
.SS epoll_pwait()
|
|
|
|
The relationship between
|
|
|
|
.BR epoll_wait ()
|
|
|
|
and
|
|
|
|
.BR epoll_pwait ()
|
|
|
|
is analogous to the relationship between
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR select (2)
|
2007-04-30 16:08:08 +00:00
|
|
|
and
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR pselect (2):
|
2007-04-30 16:08:08 +00:00
|
|
|
like
|
2007-05-11 23:07:02 +00:00
|
|
|
.BR pselect (2),
|
2007-04-30 16:08:08 +00:00
|
|
|
.BR epoll_pwait ()
|
|
|
|
allows an application to safely wait until either a file descriptor
|
|
|
|
becomes ready or until a signal is caught.
|
|
|
|
|
|
|
|
The following
|
|
|
|
.BR epoll_pwait ()
|
|
|
|
call:
|
|
|
|
.nf
|
|
|
|
|
|
|
|
ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
|
|
|
|
|
|
|
|
.fi
|
|
|
|
is equivalent to
|
|
|
|
.I atomically
|
|
|
|
executing the following calls:
|
|
|
|
.nf
|
|
|
|
|
|
|
|
sigset_t origmask;
|
|
|
|
|
|
|
|
sigprocmask(SIG_SETMASK, &sigmask, &origmask);
|
|
|
|
ready = epoll_wait(epfd, &events, maxevents, timeout);
|
|
|
|
sigprocmask(SIG_SETMASK, &origmask, NULL);
|
|
|
|
.fi
|
2008-04-23 14:40:47 +00:00
|
|
|
.PP
|
|
|
|
The
|
|
|
|
.I sigmask
|
|
|
|
argument may be specified as NULL, in which case
|
|
|
|
.BR epoll_pwait ()
|
|
|
|
is equivalent to
|
|
|
|
.BR epoll_wait ().
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "RETURN VALUE"
|
2007-04-12 22:42:49 +00:00
|
|
|
When successful,
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR epoll_wait ()
|
2004-11-03 13:51:07 +00:00
|
|
|
returns the number of file descriptors ready for the requested I/O, or zero
|
|
|
|
if no file descriptor became ready during the requested
|
|
|
|
.I timeout
|
2007-04-12 22:42:49 +00:00
|
|
|
milliseconds.
|
|
|
|
When an error occurs,
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR epoll_wait ()
|
2004-11-03 13:51:07 +00:00
|
|
|
returns \-1 and
|
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EBADF
|
|
|
|
.I epfd
|
|
|
|
is not a valid file descriptor.
|
|
|
|
.TP
|
|
|
|
.B EFAULT
|
|
|
|
The memory area pointed to by
|
|
|
|
.I events
|
|
|
|
is not accessible with write permissions.
|
|
|
|
.TP
|
2005-03-31 13:41:40 +00:00
|
|
|
.B EINTR
|
|
|
|
The call was interrupted by a signal handler before any of the
|
|
|
|
requested events occurred or the
|
|
|
|
.I timeout
|
2008-07-04 15:50:36 +00:00
|
|
|
expired; see
|
|
|
|
.BR signal (7).
|
2005-03-31 13:41:40 +00:00
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B EINVAL
|
2007-09-20 16:26:31 +00:00
|
|
|
.I epfd
|
2004-11-03 13:51:07 +00:00
|
|
|
is not an
|
|
|
|
.B epoll
|
2005-04-04 16:33:48 +00:00
|
|
|
file descriptor, or
|
2004-11-03 13:51:07 +00:00
|
|
|
.I maxevents
|
2005-04-04 16:33:48 +00:00
|
|
|
is less than or equal to zero.
|
2007-05-18 16:06:42 +00:00
|
|
|
.SH VERSIONS
|
|
|
|
.BR epoll_pwait ()
|
|
|
|
was added to Linux in kernel 2.6.19.
|
|
|
|
|
2007-06-21 22:55:04 +00:00
|
|
|
Glibc support for
|
2007-05-18 16:06:42 +00:00
|
|
|
.BR epoll_pwait ()
|
|
|
|
is provided starting with version 2.6.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH CONFORMING TO
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR epoll_wait ()
|
2007-12-25 21:28:09 +00:00
|
|
|
is Linux-specific, and was introduced in kernel 2.5.44.
|
2006-12-17 01:34:44 +00:00
|
|
|
.\" The interface should be finalized by Linux kernel 2.5.66.
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR epoll_create (2),
|
|
|
|
.BR epoll_ctl (2),
|
2006-04-21 00:29:37 +00:00
|
|
|
.BR epoll (7)
|