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>
|
|
|
|
.\"
|
2009-01-15 18:53:24 +00:00
|
|
|
.TH EPOLL_CTL 2 2009-01-17 "Linux" "Linux Programmer's Manual"
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH NAME
|
|
|
|
epoll_ctl \- control interface for an epoll descriptor
|
|
|
|
.SH SYNOPSIS
|
|
|
|
.B #include <sys/epoll.h>
|
|
|
|
.sp
|
2007-07-10 04:51:30 +00:00
|
|
|
.BI "int epoll_ctl(int " epfd ", int " op ", int " fd \
|
|
|
|
", struct epoll_event *" event );
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH DESCRIPTION
|
2009-01-15 18:53:24 +00:00
|
|
|
This system call performs control operations on the epoll instance
|
|
|
|
referred to by the file descriptor
|
|
|
|
.IR epfd .
|
|
|
|
It requests that the operation
|
2007-09-20 16:26:31 +00:00
|
|
|
.I op
|
2009-01-15 18:58:54 +00:00
|
|
|
be performed for the target file descriptor,
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR fd .
|
2009-01-15 18:58:54 +00:00
|
|
|
|
|
|
|
Valid values for the
|
|
|
|
.I op
|
|
|
|
argument are :
|
|
|
|
.TP
|
|
|
|
.B EPOLL_CTL_ADD
|
|
|
|
Register the target file descriptor
|
|
|
|
.I fd
|
|
|
|
on the
|
|
|
|
.B epoll
|
|
|
|
instance referred to by the file descriptor
|
|
|
|
.I epfd
|
|
|
|
and associate the event
|
|
|
|
.I event
|
|
|
|
with the internal file linked to
|
|
|
|
.IR fd .
|
|
|
|
.TP
|
|
|
|
.B EPOLL_CTL_MOD
|
|
|
|
Change the event
|
|
|
|
.I event
|
|
|
|
associated with the target file descriptor
|
|
|
|
.IR fd .
|
|
|
|
.TP
|
|
|
|
.B EPOLL_CTL_DEL
|
|
|
|
Remove (deregister) the target file descriptor
|
|
|
|
.I fd
|
|
|
|
from the
|
|
|
|
.B epoll
|
|
|
|
instance referred to by
|
|
|
|
.IR epfd .
|
|
|
|
The
|
|
|
|
.I event
|
|
|
|
is ignored and can be NULL (but see BUGS below).
|
|
|
|
.PP
|
2004-11-03 13:51:07 +00:00
|
|
|
The
|
2007-09-20 16:26:31 +00:00
|
|
|
.I event
|
2009-01-15 18:58:54 +00:00
|
|
|
argument describes the object linked to the file descriptor
|
2004-11-03 13:51:07 +00:00
|
|
|
.IR fd .
|
|
|
|
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 {
|
2009-04-27 03:26:19 +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 {
|
2009-04-27 03:26:19 +00:00
|
|
|
__uint32_t events; /* Epoll events */
|
|
|
|
epoll_data_t data; /* User data variable */
|
2007-04-05 12:36:57 +00:00
|
|
|
};
|
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 events
|
|
|
|
member is a bit set composed using the following available event
|
2007-07-09 19:41:16 +00:00
|
|
|
types:
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EPOLLIN
|
|
|
|
The associated file is available for
|
|
|
|
.BR read (2)
|
|
|
|
operations.
|
|
|
|
.TP
|
|
|
|
.B EPOLLOUT
|
|
|
|
The associated file is available for
|
|
|
|
.BR write (2)
|
|
|
|
operations.
|
|
|
|
.TP
|
2008-05-07 13:33:52 +00:00
|
|
|
.BR EPOLLRDHUP " (since Linux 2.6.17)"
|
2007-04-12 22:42:49 +00:00
|
|
|
Stream socket peer closed connection,
|
2006-07-01 08:30:24 +00:00
|
|
|
or shut down writing half of connection.
|
2007-04-12 22:42:49 +00:00
|
|
|
(This flag is especially useful for writing simple code to detect
|
2006-07-01 08:30:24 +00:00
|
|
|
peer shutdown when using Edge Triggered monitoring.)
|
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B EPOLLPRI
|
|
|
|
There is urgent data available for
|
|
|
|
.BR read (2)
|
|
|
|
operations.
|
|
|
|
.TP
|
|
|
|
.B EPOLLERR
|
|
|
|
Error condition happened on the associated file descriptor.
|
2005-04-04 16:33:48 +00:00
|
|
|
.BR epoll_wait (2)
|
|
|
|
will always wait for this event; it is not necessary to set it in
|
|
|
|
.IR events .
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EPOLLHUP
|
|
|
|
Hang up happened on the associated file descriptor.
|
2005-04-04 16:33:48 +00:00
|
|
|
.BR epoll_wait (2)
|
|
|
|
will always wait for this event; it is not necessary to set it in
|
|
|
|
.IR events .
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EPOLLET
|
2007-06-08 09:56:56 +00:00
|
|
|
Sets the Edge Triggered behavior for the associated file descriptor.
|
|
|
|
The default behavior for
|
2004-11-03 13:51:07 +00:00
|
|
|
.B epoll
|
2007-04-12 22:42:49 +00:00
|
|
|
is Level Triggered.
|
|
|
|
See
|
2006-04-21 00:29:37 +00:00
|
|
|
.BR epoll (7)
|
2005-04-18 13:35:29 +00:00
|
|
|
for more detailed information about Edge and Level Triggered event
|
2004-11-03 13:51:07 +00:00
|
|
|
distribution architectures.
|
|
|
|
.TP
|
2008-05-07 13:33:52 +00:00
|
|
|
.BR EPOLLONESHOT " (since Linux 2.6.2)"
|
2007-06-08 09:56:56 +00:00
|
|
|
Sets the one-shot behavior for the associated file descriptor.
|
2005-06-17 11:33:07 +00:00
|
|
|
This means that after an event is pulled out with
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR epoll_wait (2)
|
|
|
|
the associated file descriptor is internally disabled and no other events
|
|
|
|
will be reported by the
|
|
|
|
.B epoll
|
2007-04-12 22:42:49 +00:00
|
|
|
interface.
|
|
|
|
The user must call
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR epoll_ctl ()
|
2004-11-03 13:51:07 +00:00
|
|
|
with
|
|
|
|
.B EPOLL_CTL_MOD
|
close.2, epoll_create.2, epoll_ctl.2, fcntl.2, madvise.2, mmap.2, mremap.2, select_tut.2, setgid.2, setuid.2, syscalls.2, vmsplice.2, dlopen.3, fts.3, getpw.3, stdio.3, fd.4, initrd.4, random.4, sd.4, bootparam.7, capabilities.7, cpuset.7, epoll.7, inotify.7, man.7, socket.7, x25.7: Global fix: s/re-/re/
The tendency in English, as prescribed in style guides like
Chicago MoS, is towards removing hyphens after prefixes
like "re-" etc.
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
2010-01-16 17:45:23 +00:00
|
|
|
to rearm the file descriptor with a new event mask.
|
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_ctl ()
|
2007-04-12 22:42:49 +00:00
|
|
|
returns zero.
|
|
|
|
When an error occurs,
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR epoll_ctl ()
|
2004-11-03 13:51:07 +00:00
|
|
|
returns \-1 and
|
|
|
|
.I errno
|
|
|
|
is set appropriately.
|
|
|
|
.SH ERRORS
|
|
|
|
.TP
|
|
|
|
.B EBADF
|
|
|
|
.I epfd
|
2006-07-22 17:37:37 +00:00
|
|
|
or
|
|
|
|
.I fd
|
2005-04-04 16:33:48 +00:00
|
|
|
is not a valid file descriptor.
|
|
|
|
.TP
|
|
|
|
.B EEXIST
|
|
|
|
.I op
|
2007-06-22 17:16:20 +00:00
|
|
|
was
|
|
|
|
.BR EPOLL_CTL_ADD ,
|
|
|
|
and the supplied file descriptor
|
2007-09-20 16:26:31 +00:00
|
|
|
.I fd
|
2009-01-15 18:53:24 +00:00
|
|
|
is already registered with this epoll instance.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.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
|
2007-09-20 16:26:31 +00:00
|
|
|
.I fd
|
2005-04-04 16:33:48 +00:00
|
|
|
is the same as
|
|
|
|
.IR epfd ,
|
|
|
|
or the requested operation
|
2004-11-03 13:51:07 +00:00
|
|
|
.I op
|
|
|
|
is not supported by this interface.
|
|
|
|
.TP
|
2005-04-04 16:33:48 +00:00
|
|
|
.B ENOENT
|
|
|
|
.I op
|
2007-06-22 17:16:20 +00:00
|
|
|
was
|
2007-09-20 16:26:31 +00:00
|
|
|
.B EPOLL_CTL_MOD
|
2007-06-22 17:16:20 +00:00
|
|
|
or
|
|
|
|
.BR EPOLL_CTL_DEL ,
|
|
|
|
and
|
2007-09-20 16:26:31 +00:00
|
|
|
.I fd
|
2009-09-27 07:40:07 +00:00
|
|
|
is not registered with this epoll instance.
|
2005-04-04 16:33:48 +00:00
|
|
|
.TP
|
2004-11-03 13:51:07 +00:00
|
|
|
.B ENOMEM
|
|
|
|
There was insufficient memory to handle the requested
|
|
|
|
.I op
|
|
|
|
control operation.
|
2009-09-27 06:55:59 +00:00
|
|
|
.TP
|
|
|
|
.B ENOSPC
|
2009-01-16 08:40:15 +00:00
|
|
|
The limit imposed by
|
|
|
|
.I /proc/sys/fs/epoll/max_user_watches
|
|
|
|
was encountered while trying to register
|
|
|
|
.RB ( EPOLL_CTL_ADD )
|
|
|
|
a new file descriptor on an epoll instance.
|
|
|
|
See
|
|
|
|
.BR epoll (7)
|
|
|
|
for further details.
|
2004-11-03 13:51:07 +00:00
|
|
|
.TP
|
|
|
|
.B EPERM
|
|
|
|
The target file
|
|
|
|
.I fd
|
2005-04-04 16:33:48 +00:00
|
|
|
does not support
|
2004-11-03 13:51:07 +00:00
|
|
|
.BR epoll .
|
|
|
|
.SH CONFORMING TO
|
2007-11-24 10:10:39 +00:00
|
|
|
.BR epoll_ctl ()
|
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.
|
2009-01-15 18:58:54 +00:00
|
|
|
.SH NOTES
|
|
|
|
The
|
|
|
|
.B epoll
|
|
|
|
interface supports all file descriptors that support
|
|
|
|
.BR poll (2).
|
2005-06-17 11:33:07 +00:00
|
|
|
.SH BUGS
|
|
|
|
In kernel versions before 2.6.9, the
|
|
|
|
.B EPOLL_CTL_DEL
|
2007-04-12 22:42:49 +00:00
|
|
|
operation required a non-NULL pointer in
|
2005-06-17 11:33:07 +00:00
|
|
|
.IR event ,
|
|
|
|
even though this argument is ignored.
|
2008-05-07 13:33:52 +00:00
|
|
|
Since Linux 2.6.9,
|
2005-06-17 11:33:07 +00:00
|
|
|
.I event
|
|
|
|
can be specified as NULL
|
2007-04-12 22:42:49 +00:00
|
|
|
when using
|
2005-06-17 11:33:07 +00:00
|
|
|
.BR EPOLL_CTL_DEL .
|
2008-03-14 13:23:39 +00:00
|
|
|
Applications that need to be portable to kernels before 2.6.9
|
|
|
|
should specify a non-NULL pointer in
|
|
|
|
.IR event .
|
2004-11-03 13:51:07 +00:00
|
|
|
.SH "SEE ALSO"
|
|
|
|
.BR epoll_create (2),
|
|
|
|
.BR epoll_wait (2),
|
2006-09-04 08:57:04 +00:00
|
|
|
.BR poll (2),
|
2006-04-21 00:29:37 +00:00
|
|
|
.BR epoll (7)
|