|
Packit |
7cfc04 |
.\" Copyright (C) 2003 Davide Libenzi
|
|
Packit |
7cfc04 |
.\" Davide Libenzi <davidel@xmailserver.org>
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
|
|
Packit |
7cfc04 |
.\" This program is free software; you can redistribute it and/or modify
|
|
Packit |
7cfc04 |
.\" it under the terms of the GNU General Public License as published by
|
|
Packit |
7cfc04 |
.\" the Free Software Foundation; either version 2 of the License, or
|
|
Packit |
7cfc04 |
.\" (at your option) any later version.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" This program is distributed in the hope that it will be useful,
|
|
Packit |
7cfc04 |
.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
|
|
Packit |
7cfc04 |
.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
|
|
Packit |
7cfc04 |
.\" GNU General Public License for more details.
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" You should have received a copy of the GNU General Public
|
|
Packit |
7cfc04 |
.\" License along with this manual; if not, see
|
|
Packit |
7cfc04 |
.\" <http://www.gnu.org/licenses/>.
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.TH EPOLL_CTL 2 2017-09-15 "Linux" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
epoll_ctl \- control interface for an epoll file descriptor
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.B #include <sys/epoll.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "int epoll_ctl(int " epfd ", int " op ", int " fd \
|
|
Packit |
7cfc04 |
", struct epoll_event *" event );
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
This system call performs control operations on the
|
|
Packit |
7cfc04 |
.BR epoll (7)
|
|
Packit |
7cfc04 |
instance
|
|
Packit |
7cfc04 |
referred to by the file descriptor
|
|
Packit |
7cfc04 |
.IR epfd .
|
|
Packit |
7cfc04 |
It requests that the operation
|
|
Packit |
7cfc04 |
.I op
|
|
Packit |
7cfc04 |
be performed for the target file descriptor,
|
|
Packit |
7cfc04 |
.IR fd .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Valid values for the
|
|
Packit |
7cfc04 |
.I op
|
|
Packit |
7cfc04 |
argument are:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EPOLL_CTL_ADD
|
|
Packit |
7cfc04 |
Register the target file descriptor
|
|
Packit |
7cfc04 |
.I fd
|
|
Packit |
7cfc04 |
on the
|
|
Packit |
7cfc04 |
.B epoll
|
|
Packit |
7cfc04 |
instance referred to by the file descriptor
|
|
Packit |
7cfc04 |
.I epfd
|
|
Packit |
7cfc04 |
and associate the event
|
|
Packit |
7cfc04 |
.I event
|
|
Packit |
7cfc04 |
with the internal file linked to
|
|
Packit |
7cfc04 |
.IR fd .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EPOLL_CTL_MOD
|
|
Packit |
7cfc04 |
Change the event
|
|
Packit |
7cfc04 |
.I event
|
|
Packit |
7cfc04 |
associated with the target file descriptor
|
|
Packit |
7cfc04 |
.IR fd .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EPOLL_CTL_DEL
|
|
Packit |
7cfc04 |
Remove (deregister) the target file descriptor
|
|
Packit |
7cfc04 |
.I fd
|
|
Packit |
7cfc04 |
from the
|
|
Packit |
7cfc04 |
.B epoll
|
|
Packit |
7cfc04 |
instance referred to by
|
|
Packit |
7cfc04 |
.IR epfd .
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I event
|
|
Packit |
7cfc04 |
is ignored and can be NULL (but see BUGS below).
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I event
|
|
Packit |
7cfc04 |
argument describes the object linked to the file descriptor
|
|
Packit |
7cfc04 |
.IR fd .
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I struct epoll_event
|
|
Packit |
7cfc04 |
is defined as:
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
typedef union epoll_data {
|
|
Packit |
7cfc04 |
void *ptr;
|
|
Packit |
7cfc04 |
int fd;
|
|
Packit |
7cfc04 |
uint32_t u32;
|
|
Packit |
7cfc04 |
uint64_t u64;
|
|
Packit |
7cfc04 |
} epoll_data_t;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
struct epoll_event {
|
|
Packit |
7cfc04 |
uint32_t events; /* Epoll events */
|
|
Packit |
7cfc04 |
epoll_data_t data; /* User data variable */
|
|
Packit |
7cfc04 |
};
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I events
|
|
Packit |
7cfc04 |
member is a bit mask composed by ORing together zero or more of
|
|
Packit |
7cfc04 |
the following available event types:
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EPOLLIN
|
|
Packit |
7cfc04 |
The associated file is available for
|
|
Packit |
7cfc04 |
.BR read (2)
|
|
Packit |
7cfc04 |
operations.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EPOLLOUT
|
|
Packit |
7cfc04 |
The associated file is available for
|
|
Packit |
7cfc04 |
.BR write (2)
|
|
Packit |
7cfc04 |
operations.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EPOLLRDHUP " (since Linux 2.6.17)"
|
|
Packit |
7cfc04 |
Stream socket peer closed connection,
|
|
Packit |
7cfc04 |
or shut down writing half of connection.
|
|
Packit |
7cfc04 |
(This flag is especially useful for writing simple code to detect
|
|
Packit |
7cfc04 |
peer shutdown when using Edge Triggered monitoring.)
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EPOLLPRI
|
|
Packit |
7cfc04 |
There is an exceptional condition on the file descriptor.
|
|
Packit |
7cfc04 |
See the discussion of
|
|
Packit |
7cfc04 |
.B POLLPRI
|
|
Packit |
7cfc04 |
in
|
|
Packit |
7cfc04 |
.BR poll (2).
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EPOLLERR
|
|
Packit |
7cfc04 |
Error condition happened on the associated file descriptor.
|
|
Packit |
7cfc04 |
This event is also reported for the write end of a pipe when the read end
|
|
Packit |
7cfc04 |
has been closed.
|
|
Packit |
7cfc04 |
.BR epoll_wait (2)
|
|
Packit |
7cfc04 |
will always report for this event; it is not necessary to set it in
|
|
Packit |
7cfc04 |
.IR events .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EPOLLHUP
|
|
Packit |
7cfc04 |
Hang up happened on the associated file descriptor.
|
|
Packit |
7cfc04 |
.BR epoll_wait (2)
|
|
Packit |
7cfc04 |
will always wait for this event; it is not necessary to set it in
|
|
Packit |
7cfc04 |
.IR events .
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
Note that when reading from a channel such as a pipe or a stream socket,
|
|
Packit |
7cfc04 |
this event merely indicates that the peer closed its end of the channel.
|
|
Packit |
7cfc04 |
Subsequent reads from the channel will return 0 (end of file)
|
|
Packit |
7cfc04 |
only after all outstanding data in the channel has been consumed.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EPOLLET
|
|
Packit |
7cfc04 |
Sets the Edge Triggered behavior for the associated file descriptor.
|
|
Packit |
7cfc04 |
The default behavior for
|
|
Packit |
7cfc04 |
.B epoll
|
|
Packit |
7cfc04 |
is Level Triggered.
|
|
Packit |
7cfc04 |
See
|
|
Packit |
7cfc04 |
.BR epoll (7)
|
|
Packit |
7cfc04 |
for more detailed information about Edge and Level Triggered event
|
|
Packit |
7cfc04 |
distribution architectures.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EPOLLONESHOT " (since Linux 2.6.2)"
|
|
Packit |
7cfc04 |
Sets the one-shot behavior for the associated file descriptor.
|
|
Packit |
7cfc04 |
This means that after an event is pulled out with
|
|
Packit |
7cfc04 |
.BR epoll_wait (2)
|
|
Packit |
7cfc04 |
the associated file descriptor is internally disabled and no other events
|
|
Packit |
7cfc04 |
will be reported by the
|
|
Packit |
7cfc04 |
.B epoll
|
|
Packit |
7cfc04 |
interface.
|
|
Packit |
7cfc04 |
The user must call
|
|
Packit |
7cfc04 |
.BR epoll_ctl ()
|
|
Packit |
7cfc04 |
with
|
|
Packit |
7cfc04 |
.B EPOLL_CTL_MOD
|
|
Packit |
7cfc04 |
to rearm the file descriptor with a new event mask.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EPOLLWAKEUP " (since Linux 3.5)"
|
|
Packit |
7cfc04 |
.\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.B EPOLLONESHOT
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.B EPOLLET
|
|
Packit |
7cfc04 |
are clear and the process has the
|
|
Packit |
7cfc04 |
.B CAP_BLOCK_SUSPEND
|
|
Packit |
7cfc04 |
capability,
|
|
Packit |
7cfc04 |
ensure that the system does not enter "suspend" or
|
|
Packit |
7cfc04 |
"hibernate" while this event is pending or being processed.
|
|
Packit |
7cfc04 |
The event is considered as being "processed" from the time
|
|
Packit |
7cfc04 |
when it is returned by a call to
|
|
Packit |
7cfc04 |
.BR epoll_wait (2)
|
|
Packit |
7cfc04 |
until the next call to
|
|
Packit |
7cfc04 |
.BR epoll_wait (2)
|
|
Packit |
7cfc04 |
on the same
|
|
Packit |
7cfc04 |
.BR epoll (7)
|
|
Packit |
7cfc04 |
file descriptor,
|
|
Packit |
7cfc04 |
the closure of that file descriptor,
|
|
Packit |
7cfc04 |
the removal of the event file descriptor with
|
|
Packit |
7cfc04 |
.BR EPOLL_CTL_DEL ,
|
|
Packit |
7cfc04 |
or the clearing of
|
|
Packit |
7cfc04 |
.B EPOLLWAKEUP
|
|
Packit |
7cfc04 |
for the event file descriptor with
|
|
Packit |
7cfc04 |
.BR EPOLL_CTL_MOD .
|
|
Packit |
7cfc04 |
See also BUGS.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.BR EPOLLEXCLUSIVE " (since Linux 4.5)"
|
|
Packit |
7cfc04 |
Sets an exclusive wakeup mode for the epoll file descriptor that is being
|
|
Packit |
7cfc04 |
attached to the target file descriptor,
|
|
Packit |
7cfc04 |
.IR fd .
|
|
Packit |
7cfc04 |
When a wakeup event occurs and multiple epoll file descriptors
|
|
Packit |
7cfc04 |
are attached to the same target file using
|
|
Packit |
7cfc04 |
.BR EPOLLEXCLUSIVE ,
|
|
Packit |
7cfc04 |
one or more of the epoll file descriptors will receive an event with
|
|
Packit |
7cfc04 |
.BR epoll_wait (2).
|
|
Packit |
7cfc04 |
The default in this scenario (when
|
|
Packit |
7cfc04 |
.BR EPOLLEXCLUSIVE
|
|
Packit |
7cfc04 |
is not set) is for all epoll file descriptors to receive an event.
|
|
Packit |
7cfc04 |
.BR EPOLLEXCLUSIVE
|
|
Packit |
7cfc04 |
is thus useful for avoiding thundering herd problems in certain scenarios.
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
If the same file descriptor is in multiple epoll instances,
|
|
Packit |
7cfc04 |
some with the
|
|
Packit |
7cfc04 |
.BR EPOLLEXCLUSIVE
|
|
Packit |
7cfc04 |
flag, and others without, then events will be provided to all epoll
|
|
Packit |
7cfc04 |
instances that did not specify
|
|
Packit |
7cfc04 |
.BR EPOLLEXCLUSIVE ,
|
|
Packit |
7cfc04 |
and at least one of the epoll instances that did specify
|
|
Packit |
7cfc04 |
.BR EPOLLEXCLUSIVE .
|
|
Packit |
7cfc04 |
.IP
|
|
Packit |
7cfc04 |
The following values may be specified in conjunction with
|
|
Packit |
7cfc04 |
.BR EPOLLEXCLUSIVE :
|
|
Packit |
7cfc04 |
.BR EPOLLIN ,
|
|
Packit |
7cfc04 |
.BR EPOLLOUT ,
|
|
Packit |
7cfc04 |
.BR EPOLLWAKEUP,
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR EPOLLET .
|
|
Packit |
7cfc04 |
.BR EPOLLHUP
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR EPOLLERR
|
|
Packit |
7cfc04 |
can also be specified, but this is not required:
|
|
Packit |
7cfc04 |
as usual, these events are always reported if they occur,
|
|
Packit |
7cfc04 |
regardless of whether they are specified in
|
|
Packit |
7cfc04 |
.IR events .
|
|
Packit |
7cfc04 |
Attempts to specify other values in
|
|
Packit |
7cfc04 |
.I events
|
|
Packit |
7cfc04 |
yield an error.
|
|
Packit |
7cfc04 |
.B EPOLLEXCLUSIVE
|
|
Packit |
7cfc04 |
may be used only in an
|
|
Packit |
7cfc04 |
.B EPOLL_CTL_ADD
|
|
Packit |
7cfc04 |
operation; attempts to employ it with
|
|
Packit |
7cfc04 |
.B EPOLL_CTL_MOD
|
|
Packit |
7cfc04 |
yield an error.
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.B EPOLLEXCLUSIVE
|
|
Packit |
7cfc04 |
has been set using
|
|
Packit |
7cfc04 |
.BR epoll_ctl (),
|
|
Packit |
7cfc04 |
then a subsequent
|
|
Packit |
7cfc04 |
.B EPOLL_CTL_MOD
|
|
Packit |
7cfc04 |
on the same
|
|
Packit |
7cfc04 |
.IR epfd ",\ " fd
|
|
Packit |
7cfc04 |
pair yields an error.
|
|
Packit |
7cfc04 |
A call to
|
|
Packit |
7cfc04 |
.BR epoll_ctl ()
|
|
Packit |
7cfc04 |
that specifies
|
|
Packit |
7cfc04 |
.B EPOLLEXCLUSIVE
|
|
Packit |
7cfc04 |
in
|
|
Packit |
7cfc04 |
.I events
|
|
Packit |
7cfc04 |
and specifies the target file descriptor
|
|
Packit |
7cfc04 |
.I fd
|
|
Packit |
7cfc04 |
as an epoll instance will likewise fail.
|
|
Packit |
7cfc04 |
The error in all of these cases is
|
|
Packit |
7cfc04 |
.BR EINVAL .
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
When successful,
|
|
Packit |
7cfc04 |
.BR epoll_ctl ()
|
|
Packit |
7cfc04 |
returns zero.
|
|
Packit |
7cfc04 |
When an error occurs,
|
|
Packit |
7cfc04 |
.BR epoll_ctl ()
|
|
Packit |
7cfc04 |
returns \-1 and
|
|
Packit |
7cfc04 |
.I errno
|
|
Packit |
7cfc04 |
is set appropriately.
|
|
Packit |
7cfc04 |
.SH ERRORS
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EBADF
|
|
Packit |
7cfc04 |
.I epfd
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.I fd
|
|
Packit |
7cfc04 |
is not a valid file descriptor.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EEXIST
|
|
Packit |
7cfc04 |
.I op
|
|
Packit |
7cfc04 |
was
|
|
Packit |
7cfc04 |
.BR EPOLL_CTL_ADD ,
|
|
Packit |
7cfc04 |
and the supplied file descriptor
|
|
Packit |
7cfc04 |
.I fd
|
|
Packit |
7cfc04 |
is already registered with this epoll instance.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
.I epfd
|
|
Packit |
7cfc04 |
is not an
|
|
Packit |
7cfc04 |
.B epoll
|
|
Packit |
7cfc04 |
file descriptor,
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.I fd
|
|
Packit |
7cfc04 |
is the same as
|
|
Packit |
7cfc04 |
.IR epfd ,
|
|
Packit |
7cfc04 |
or the requested operation
|
|
Packit |
7cfc04 |
.I op
|
|
Packit |
7cfc04 |
is not supported by this interface.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
An invalid event type was specified along with
|
|
Packit |
7cfc04 |
.B EPOLLEXCLUSIVE
|
|
Packit |
7cfc04 |
in
|
|
Packit |
7cfc04 |
.IR events .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
.I op
|
|
Packit |
7cfc04 |
was
|
|
Packit |
7cfc04 |
.B EPOLL_CTL_MOD
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.IR events
|
|
Packit |
7cfc04 |
included
|
|
Packit |
7cfc04 |
.BR EPOLLEXCLUSIVE .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
.I op
|
|
Packit |
7cfc04 |
was
|
|
Packit |
7cfc04 |
.B EPOLL_CTL_MOD
|
|
Packit |
7cfc04 |
and the
|
|
Packit |
7cfc04 |
.BR EPOLLEXCLUSIVE
|
|
Packit |
7cfc04 |
flag has previously been applied to this
|
|
Packit |
7cfc04 |
.IR epfd ",\ " fd
|
|
Packit |
7cfc04 |
pair.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EINVAL
|
|
Packit |
7cfc04 |
.BR EPOLLEXCLUSIVE
|
|
Packit |
7cfc04 |
was specified in
|
|
Packit |
7cfc04 |
.IR event
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I fd
|
|
Packit |
7cfc04 |
refers to an epoll instance.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ELOOP
|
|
Packit |
7cfc04 |
.I fd
|
|
Packit |
7cfc04 |
refers to an epoll instance and this
|
|
Packit |
7cfc04 |
.B EPOLL_CTL_ADD
|
|
Packit |
7cfc04 |
operation would result in a circular loop of epoll instances
|
|
Packit |
7cfc04 |
monitoring one another.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ENOENT
|
|
Packit |
7cfc04 |
.I op
|
|
Packit |
7cfc04 |
was
|
|
Packit |
7cfc04 |
.B EPOLL_CTL_MOD
|
|
Packit |
7cfc04 |
or
|
|
Packit |
7cfc04 |
.BR EPOLL_CTL_DEL ,
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.I fd
|
|
Packit |
7cfc04 |
is not registered with this epoll instance.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ENOMEM
|
|
Packit |
7cfc04 |
There was insufficient memory to handle the requested
|
|
Packit |
7cfc04 |
.I op
|
|
Packit |
7cfc04 |
control operation.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B ENOSPC
|
|
Packit |
7cfc04 |
The limit imposed by
|
|
Packit |
7cfc04 |
.I /proc/sys/fs/epoll/max_user_watches
|
|
Packit |
7cfc04 |
was encountered while trying to register
|
|
Packit |
7cfc04 |
.RB ( EPOLL_CTL_ADD )
|
|
Packit |
7cfc04 |
a new file descriptor on an epoll instance.
|
|
Packit |
7cfc04 |
See
|
|
Packit |
7cfc04 |
.BR epoll (7)
|
|
Packit |
7cfc04 |
for further details.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B EPERM
|
|
Packit |
7cfc04 |
The target file
|
|
Packit |
7cfc04 |
.I fd
|
|
Packit |
7cfc04 |
does not support
|
|
Packit |
7cfc04 |
.BR epoll .
|
|
Packit |
7cfc04 |
This error can occur if
|
|
Packit |
7cfc04 |
.I fd
|
|
Packit |
7cfc04 |
refers to, for example, a regular file or a directory.
|
|
Packit |
7cfc04 |
.SH VERSIONS
|
|
Packit |
7cfc04 |
.BR epoll_ctl ()
|
|
Packit |
7cfc04 |
was added to the kernel in version 2.6.
|
|
Packit |
7cfc04 |
.\" To be precise: kernel 2.5.44.
|
|
Packit |
7cfc04 |
.\" The interface should be finalized by Linux kernel 2.5.66.
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
.BR epoll_ctl ()
|
|
Packit |
7cfc04 |
is Linux-specific.
|
|
Packit |
7cfc04 |
Library support is provided in glibc starting with version 2.3.2.
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.B epoll
|
|
Packit |
7cfc04 |
interface supports all file descriptors that support
|
|
Packit |
7cfc04 |
.BR poll (2).
|
|
Packit |
7cfc04 |
.SH BUGS
|
|
Packit |
7cfc04 |
In kernel versions before 2.6.9, the
|
|
Packit |
7cfc04 |
.B EPOLL_CTL_DEL
|
|
Packit |
7cfc04 |
operation required a non-null pointer in
|
|
Packit |
7cfc04 |
.IR event ,
|
|
Packit |
7cfc04 |
even though this argument is ignored.
|
|
Packit |
7cfc04 |
Since Linux 2.6.9,
|
|
Packit |
7cfc04 |
.I event
|
|
Packit |
7cfc04 |
can be specified as NULL
|
|
Packit |
7cfc04 |
when using
|
|
Packit |
7cfc04 |
.BR EPOLL_CTL_DEL .
|
|
Packit |
7cfc04 |
Applications that need to be portable to kernels before 2.6.9
|
|
Packit |
7cfc04 |
should specify a non-null pointer in
|
|
Packit |
7cfc04 |
.IR event .
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
If
|
|
Packit |
7cfc04 |
.B EPOLLWAKEUP
|
|
Packit |
7cfc04 |
is specified in
|
|
Packit |
7cfc04 |
.IR flags ,
|
|
Packit |
7cfc04 |
but the caller does not have the
|
|
Packit |
7cfc04 |
.BR CAP_BLOCK_SUSPEND
|
|
Packit |
7cfc04 |
capability, then the
|
|
Packit |
7cfc04 |
.B EPOLLWAKEUP
|
|
Packit |
7cfc04 |
flag is
|
|
Packit |
7cfc04 |
.IR "silently ignored" .
|
|
Packit |
7cfc04 |
This unfortunate behavior is necessary because no validity
|
|
Packit |
7cfc04 |
checks were performed on the
|
|
Packit |
7cfc04 |
.IR flags
|
|
Packit |
7cfc04 |
argument in the original implementation, and the addition of the
|
|
Packit |
7cfc04 |
.B EPOLLWAKEUP
|
|
Packit |
7cfc04 |
with a check that caused the call to fail if the caller did not have the
|
|
Packit |
7cfc04 |
.B CAP_BLOCK_SUSPEND
|
|
Packit |
7cfc04 |
capability caused a breakage in at least one existing user-space
|
|
Packit |
7cfc04 |
application that happened to randomly (and uselessly) specify this bit.
|
|
Packit |
7cfc04 |
.\" commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change)
|
|
Packit |
7cfc04 |
.\" https://lwn.net/Articles/520198/
|
|
Packit |
7cfc04 |
A robust application should therefore double check that it has the
|
|
Packit |
7cfc04 |
.B CAP_BLOCK_SUSPEND
|
|
Packit |
7cfc04 |
capability if attempting to use the
|
|
Packit |
7cfc04 |
.B EPOLLWAKEUP
|
|
Packit |
7cfc04 |
flag.
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR epoll_create (2),
|
|
Packit |
7cfc04 |
.BR epoll_wait (2),
|
|
Packit |
7cfc04 |
.BR poll (2),
|
|
Packit |
7cfc04 |
.BR epoll (7)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|