643 lines
13 KiB
HTML
643 lines
13 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of EPOLL_CTL</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>EPOLL_CTL</H1>
|
|
Section: Linux Programmer's Manual (2)<BR>Updated: 2019-03-06<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
epoll_ctl - control interface for an epoll file descriptor
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>#include <<A HREF="file:///usr/include/sys/epoll.h">sys/epoll.h</A>></B>
|
|
|
|
<P>
|
|
|
|
<B>int epoll_ctl(int </B><I>epfd</I><B>, int </B><I>op</I><B>, int </B><I>fd</I><B>, struct epoll_event *</B><I>event</I><B>);</B>
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
This system call is used to add, modify, or remove
|
|
entries in the interest list of the
|
|
<B><A HREF="/cgi-bin/man/man2html?7+epoll">epoll</A></B>(7)
|
|
|
|
instance
|
|
referred to by the file descriptor
|
|
<I>epfd</I>.
|
|
|
|
It requests that the operation
|
|
<I>op</I>
|
|
|
|
be performed for the target file descriptor,
|
|
<I>fd</I>.
|
|
|
|
<P>
|
|
|
|
Valid values for the
|
|
<I>op</I>
|
|
|
|
argument are:
|
|
<DL COMPACT>
|
|
<DT id="1"><B>EPOLL_CTL_ADD</B>
|
|
|
|
<DD>
|
|
Add
|
|
<I>fd</I>
|
|
|
|
to the interest list
|
|
and associate the settings specified in
|
|
<I>event</I>
|
|
|
|
with the internal file linked to
|
|
<I>fd</I>.
|
|
|
|
<DT id="2"><B>EPOLL_CTL_MOD</B>
|
|
|
|
<DD>
|
|
Change the settings associated with
|
|
<I>fd</I>
|
|
|
|
in the interest list to the new settings specified in
|
|
<I>event</I>.
|
|
|
|
<DT id="3"><B>EPOLL_CTL_DEL</B>
|
|
|
|
<DD>
|
|
Remove (deregister) the target file descriptor
|
|
<I>fd</I>
|
|
|
|
from the interest list.
|
|
The
|
|
<I>event</I>
|
|
|
|
argument is ignored and can be NULL (but see BUGS below).
|
|
</DL>
|
|
<P>
|
|
|
|
The
|
|
<I>event</I>
|
|
|
|
argument describes the object linked to the file descriptor
|
|
<I>fd</I>.
|
|
|
|
The
|
|
<I>struct epoll_event</I>
|
|
|
|
is defined as:
|
|
<P>
|
|
|
|
|
|
|
|
typedef union epoll_data {
|
|
<BR> void *ptr;
|
|
<BR> int fd;
|
|
<BR> uint32_t u32;
|
|
<BR> uint64_t u64;
|
|
} epoll_data_t;
|
|
<P>
|
|
struct epoll_event {
|
|
<BR> uint32_t events; /* Epoll events */
|
|
<BR> epoll_data_t data; /* User data variable */
|
|
};
|
|
|
|
|
|
<P>
|
|
|
|
The
|
|
<I>events</I>
|
|
|
|
member is a bit mask composed by ORing together zero or more of
|
|
the following available event types:
|
|
<DL COMPACT>
|
|
<DT id="4"><B>EPOLLIN</B>
|
|
|
|
<DD>
|
|
The associated file is available for
|
|
<B><A HREF="/cgi-bin/man/man2html?2+read">read</A></B>(2)
|
|
|
|
operations.
|
|
<DT id="5"><B>EPOLLOUT</B>
|
|
|
|
<DD>
|
|
The associated file is available for
|
|
<B><A HREF="/cgi-bin/man/man2html?2+write">write</A></B>(2)
|
|
|
|
operations.
|
|
<DT id="6"><B>EPOLLRDHUP</B> (since Linux 2.6.17)
|
|
|
|
<DD>
|
|
Stream socket peer closed connection,
|
|
or shut down writing half of connection.
|
|
(This flag is especially useful for writing simple code to detect
|
|
peer shutdown when using Edge Triggered monitoring.)
|
|
<DT id="7"><B>EPOLLPRI</B>
|
|
|
|
<DD>
|
|
There is an exceptional condition on the file descriptor.
|
|
See the discussion of
|
|
<B>POLLPRI</B>
|
|
|
|
in
|
|
<B><A HREF="/cgi-bin/man/man2html?2+poll">poll</A></B>(2).
|
|
|
|
<DT id="8"><B>EPOLLERR</B>
|
|
|
|
<DD>
|
|
Error condition happened on the associated file descriptor.
|
|
This event is also reported for the write end of a pipe when the read end
|
|
has been closed.
|
|
<B><A HREF="/cgi-bin/man/man2html?2+epoll_wait">epoll_wait</A></B>(2)
|
|
|
|
will always report for this event; it is not necessary to set it in
|
|
<I>events</I>.
|
|
|
|
<DT id="9"><B>EPOLLHUP</B>
|
|
|
|
<DD>
|
|
Hang up happened on the associated file descriptor.
|
|
<B><A HREF="/cgi-bin/man/man2html?2+epoll_wait">epoll_wait</A></B>(2)
|
|
|
|
will always wait for this event; it is not necessary to set it in
|
|
<I>events</I>.
|
|
|
|
<DT id="10"><DD>
|
|
Note that when reading from a channel such as a pipe or a stream socket,
|
|
this event merely indicates that the peer closed its end of the channel.
|
|
Subsequent reads from the channel will return 0 (end of file)
|
|
only after all outstanding data in the channel has been consumed.
|
|
<DT id="11"><B>EPOLLET</B>
|
|
|
|
<DD>
|
|
Sets the Edge Triggered behavior for the associated file descriptor.
|
|
The default behavior for
|
|
<B>epoll</B>
|
|
|
|
is Level Triggered.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?7+epoll">epoll</A></B>(7)
|
|
|
|
for more detailed information about Edge and Level Triggered event
|
|
distribution architectures.
|
|
<DT id="12"><B>EPOLLONESHOT</B> (since Linux 2.6.2)
|
|
|
|
<DD>
|
|
Sets the one-shot behavior for the associated file descriptor.
|
|
This means that after an event is pulled out with
|
|
<B><A HREF="/cgi-bin/man/man2html?2+epoll_wait">epoll_wait</A></B>(2)
|
|
|
|
the associated file descriptor is internally disabled and no other events
|
|
will be reported by the
|
|
<B>epoll</B>
|
|
|
|
interface.
|
|
The user must call
|
|
<B>epoll_ctl</B>()
|
|
|
|
with
|
|
<B>EPOLL_CTL_MOD</B>
|
|
|
|
to rearm the file descriptor with a new event mask.
|
|
<DT id="13"><B>EPOLLWAKEUP</B> (since Linux 3.5)
|
|
|
|
<DD>
|
|
|
|
If
|
|
<B>EPOLLONESHOT</B>
|
|
|
|
and
|
|
<B>EPOLLET</B>
|
|
|
|
are clear and the process has the
|
|
<B>CAP_BLOCK_SUSPEND</B>
|
|
|
|
capability,
|
|
ensure that the system does not enter "suspend" or
|
|
"hibernate" while this event is pending or being processed.
|
|
The event is considered as being "processed" from the time
|
|
when it is returned by a call to
|
|
<B><A HREF="/cgi-bin/man/man2html?2+epoll_wait">epoll_wait</A></B>(2)
|
|
|
|
until the next call to
|
|
<B><A HREF="/cgi-bin/man/man2html?2+epoll_wait">epoll_wait</A></B>(2)
|
|
|
|
on the same
|
|
<B><A HREF="/cgi-bin/man/man2html?7+epoll">epoll</A></B>(7)
|
|
|
|
file descriptor,
|
|
the closure of that file descriptor,
|
|
the removal of the event file descriptor with
|
|
<B>EPOLL_CTL_DEL</B>,
|
|
|
|
or the clearing of
|
|
<B>EPOLLWAKEUP</B>
|
|
|
|
for the event file descriptor with
|
|
<B>EPOLL_CTL_MOD</B>.
|
|
|
|
See also BUGS.
|
|
<DT id="14"><B>EPOLLEXCLUSIVE</B> (since Linux 4.5)
|
|
|
|
<DD>
|
|
Sets an exclusive wakeup mode for the epoll file descriptor that is being
|
|
attached to the target file descriptor,
|
|
<I>fd</I>.
|
|
|
|
When a wakeup event occurs and multiple epoll file descriptors
|
|
are attached to the same target file using
|
|
<B>EPOLLEXCLUSIVE</B>,
|
|
|
|
one or more of the epoll file descriptors will receive an event with
|
|
<B><A HREF="/cgi-bin/man/man2html?2+epoll_wait">epoll_wait</A></B>(2).
|
|
|
|
The default in this scenario (when
|
|
<B>EPOLLEXCLUSIVE</B>
|
|
|
|
is not set) is for all epoll file descriptors to receive an event.
|
|
<B>EPOLLEXCLUSIVE</B>
|
|
|
|
is thus useful for avoiding thundering herd problems in certain scenarios.
|
|
<DT id="15"><DD>
|
|
If the same file descriptor is in multiple epoll instances,
|
|
some with the
|
|
<B>EPOLLEXCLUSIVE</B>
|
|
|
|
flag, and others without, then events will be provided to all epoll
|
|
instances that did not specify
|
|
<B>EPOLLEXCLUSIVE</B>,
|
|
|
|
and at least one of the epoll instances that did specify
|
|
<B>EPOLLEXCLUSIVE</B>.
|
|
|
|
<DT id="16"><DD>
|
|
The following values may be specified in conjunction with
|
|
<B>EPOLLEXCLUSIVE</B>:
|
|
|
|
<B>EPOLLIN</B>,
|
|
|
|
<B>EPOLLOUT</B>,
|
|
|
|
<B>EPOLLWAKEUP</B>,
|
|
|
|
and
|
|
<B>EPOLLET</B>.
|
|
|
|
<B>EPOLLHUP</B>
|
|
|
|
and
|
|
<B>EPOLLERR</B>
|
|
|
|
can also be specified, but this is not required:
|
|
as usual, these events are always reported if they occur,
|
|
regardless of whether they are specified in
|
|
<I>events</I>.
|
|
|
|
Attempts to specify other values in
|
|
<I>events</I>
|
|
|
|
yield the error
|
|
<B>EINVAL</B>.
|
|
|
|
<DT id="17"><DD>
|
|
<B>EPOLLEXCLUSIVE</B>
|
|
|
|
may be used only in an
|
|
<B>EPOLL_CTL_ADD</B>
|
|
|
|
operation; attempts to employ it with
|
|
<B>EPOLL_CTL_MOD</B>
|
|
|
|
yield an error.
|
|
If
|
|
<B>EPOLLEXCLUSIVE</B>
|
|
|
|
has been set using
|
|
<B>epoll_ctl</B>(),
|
|
|
|
then a subsequent
|
|
<B>EPOLL_CTL_MOD</B>
|
|
|
|
on the same
|
|
<I>epfd</I>, <I>fd</I>
|
|
|
|
pair yields an error.
|
|
A call to
|
|
<B>epoll_ctl</B>()
|
|
|
|
that specifies
|
|
<B>EPOLLEXCLUSIVE</B>
|
|
|
|
in
|
|
<I>events</I>
|
|
|
|
and specifies the target file descriptor
|
|
<I>fd</I>
|
|
|
|
as an epoll instance will likewise fail.
|
|
The error in all of these cases is
|
|
<B>EINVAL</B>.
|
|
|
|
</DL>
|
|
<A NAME="lbAE"> </A>
|
|
<H2>RETURN VALUE</H2>
|
|
|
|
When successful,
|
|
<B>epoll_ctl</B>()
|
|
|
|
returns zero.
|
|
When an error occurs,
|
|
<B>epoll_ctl</B>()
|
|
|
|
returns -1 and
|
|
<I>errno</I>
|
|
|
|
is set appropriately.
|
|
<A NAME="lbAF"> </A>
|
|
<H2>ERRORS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="18"><B>EBADF</B>
|
|
|
|
<DD>
|
|
<I>epfd</I>
|
|
|
|
or
|
|
<I>fd</I>
|
|
|
|
is not a valid file descriptor.
|
|
<DT id="19"><B>EEXIST</B>
|
|
|
|
<DD>
|
|
<I>op</I>
|
|
|
|
was
|
|
<B>EPOLL_CTL_ADD</B>,
|
|
|
|
and the supplied file descriptor
|
|
<I>fd</I>
|
|
|
|
is already registered with this epoll instance.
|
|
<DT id="20"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
<I>epfd</I>
|
|
|
|
is not an
|
|
<B>epoll</B>
|
|
|
|
file descriptor,
|
|
or
|
|
<I>fd</I>
|
|
|
|
is the same as
|
|
<I>epfd</I>,
|
|
|
|
or the requested operation
|
|
<I>op</I>
|
|
|
|
is not supported by this interface.
|
|
<DT id="21"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
An invalid event type was specified along with
|
|
<B>EPOLLEXCLUSIVE</B>
|
|
|
|
in
|
|
<I>events</I>.
|
|
|
|
<DT id="22"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
<I>op</I>
|
|
|
|
was
|
|
<B>EPOLL_CTL_MOD</B>
|
|
|
|
and
|
|
<I>events</I>
|
|
|
|
included
|
|
<B>EPOLLEXCLUSIVE</B>.
|
|
|
|
<DT id="23"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
<I>op</I>
|
|
|
|
was
|
|
<B>EPOLL_CTL_MOD</B>
|
|
|
|
and the
|
|
<B>EPOLLEXCLUSIVE</B>
|
|
|
|
flag has previously been applied to this
|
|
<I>epfd</I>, <I>fd</I>
|
|
|
|
pair.
|
|
<DT id="24"><B>EINVAL</B>
|
|
|
|
<DD>
|
|
<B>EPOLLEXCLUSIVE</B>
|
|
|
|
was specified in
|
|
<I>event</I>
|
|
|
|
and
|
|
<I>fd</I>
|
|
|
|
refers to an epoll instance.
|
|
<DT id="25"><B>ELOOP</B>
|
|
|
|
<DD>
|
|
<I>fd</I>
|
|
|
|
refers to an epoll instance and this
|
|
<B>EPOLL_CTL_ADD</B>
|
|
|
|
operation would result in a circular loop of epoll instances
|
|
monitoring one another.
|
|
<DT id="26"><B>ENOENT</B>
|
|
|
|
<DD>
|
|
<I>op</I>
|
|
|
|
was
|
|
<B>EPOLL_CTL_MOD</B>
|
|
|
|
or
|
|
<B>EPOLL_CTL_DEL</B>,
|
|
|
|
and
|
|
<I>fd</I>
|
|
|
|
is not registered with this epoll instance.
|
|
<DT id="27"><B>ENOMEM</B>
|
|
|
|
<DD>
|
|
There was insufficient memory to handle the requested
|
|
<I>op</I>
|
|
|
|
control operation.
|
|
<DT id="28"><B>ENOSPC</B>
|
|
|
|
<DD>
|
|
The limit imposed by
|
|
<I>/proc/sys/fs/epoll/max_user_watches</I>
|
|
|
|
was encountered while trying to register
|
|
(<B>EPOLL_CTL_ADD</B>)
|
|
|
|
a new file descriptor on an epoll instance.
|
|
See
|
|
<B><A HREF="/cgi-bin/man/man2html?7+epoll">epoll</A></B>(7)
|
|
|
|
for further details.
|
|
<DT id="29"><B>EPERM</B>
|
|
|
|
<DD>
|
|
The target file
|
|
<I>fd</I>
|
|
|
|
does not support
|
|
<B>epoll</B>.
|
|
|
|
This error can occur if
|
|
<I>fd</I>
|
|
|
|
refers to, for example, a regular file or a directory.
|
|
</DL>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>VERSIONS</H2>
|
|
|
|
<B>epoll_ctl</B>()
|
|
|
|
was added to the kernel in version 2.6.
|
|
|
|
|
|
<A NAME="lbAH"> </A>
|
|
<H2>CONFORMING TO</H2>
|
|
|
|
<B>epoll_ctl</B>()
|
|
|
|
is Linux-specific.
|
|
Library support is provided in glibc starting with version 2.3.2.
|
|
<A NAME="lbAI"> </A>
|
|
<H2>NOTES</H2>
|
|
|
|
The
|
|
<B>epoll</B>
|
|
|
|
interface supports all file descriptors that support
|
|
<B><A HREF="/cgi-bin/man/man2html?2+poll">poll</A></B>(2).
|
|
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
In kernel versions before 2.6.9, the
|
|
<B>EPOLL_CTL_DEL</B>
|
|
|
|
operation required a non-null pointer in
|
|
<I>event</I>,
|
|
|
|
even though this argument is ignored.
|
|
Since Linux 2.6.9,
|
|
<I>event</I>
|
|
|
|
can be specified as NULL
|
|
when using
|
|
<B>EPOLL_CTL_DEL</B>.
|
|
|
|
Applications that need to be portable to kernels before 2.6.9
|
|
should specify a non-null pointer in
|
|
<I>event</I>.
|
|
|
|
<P>
|
|
|
|
If
|
|
<B>EPOLLWAKEUP</B>
|
|
|
|
is specified in
|
|
<I>flags</I>,
|
|
|
|
but the caller does not have the
|
|
<B>CAP_BLOCK_SUSPEND</B>
|
|
|
|
capability, then the
|
|
<B>EPOLLWAKEUP</B>
|
|
|
|
flag is
|
|
<I>silently ignored</I>.
|
|
|
|
This unfortunate behavior is necessary because no validity
|
|
checks were performed on the
|
|
<I>flags</I>
|
|
|
|
argument in the original implementation, and the addition of the
|
|
<B>EPOLLWAKEUP</B>
|
|
|
|
with a check that caused the call to fail if the caller did not have the
|
|
<B>CAP_BLOCK_SUSPEND</B>
|
|
|
|
capability caused a breakage in at least one existing user-space
|
|
application that happened to randomly (and uselessly) specify this bit.
|
|
|
|
|
|
A robust application should therefore double check that it has the
|
|
<B>CAP_BLOCK_SUSPEND</B>
|
|
|
|
capability if attempting to use the
|
|
<B>EPOLLWAKEUP</B>
|
|
|
|
flag.
|
|
<A NAME="lbAK"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+epoll_create">epoll_create</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+epoll_wait">epoll_wait</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?2+poll">poll</A></B>(2),
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?7+epoll">epoll</A></B>(7)
|
|
|
|
<A NAME="lbAL"> </A>
|
|
<H2>COLOPHON</H2>
|
|
|
|
This page is part of release 5.05 of the Linux
|
|
<I>man-pages</I>
|
|
|
|
project.
|
|
A description of the project,
|
|
information about reporting bugs,
|
|
and the latest version of this page,
|
|
can be found at
|
|
<A HREF="https://www.kernel.org/doc/man-pages/.">https://www.kernel.org/doc/man-pages/.</A>
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="30"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="31"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="32"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="33"><A HREF="#lbAE">RETURN VALUE</A><DD>
|
|
<DT id="34"><A HREF="#lbAF">ERRORS</A><DD>
|
|
<DT id="35"><A HREF="#lbAG">VERSIONS</A><DD>
|
|
<DT id="36"><A HREF="#lbAH">CONFORMING TO</A><DD>
|
|
<DT id="37"><A HREF="#lbAI">NOTES</A><DD>
|
|
<DT id="38"><A HREF="#lbAJ">BUGS</A><DD>
|
|
<DT id="39"><A HREF="#lbAK">SEE ALSO</A><DD>
|
|
<DT id="40"><A HREF="#lbAL">COLOPHON</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:32 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|