EPOLL_CTL(3C)EPOLL_CTL(3C)NAMEepoll_ctl - control an epoll instance
SYNOPSIS
#include <sys/epoll.h>
int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);
DESCRIPTION
The epoll_ctl() function executes the operation specified by op (as
parameterized by event) on the epfd epoll instance. Valid values for
op:
EPOLL_CTL_ADD
For the epoll(5) instance specified by epfd, associate the
file descriptor specified by fd with the event specified by
event.
EPOLL_CTL_DEL
For the epoll(5) instance specified by epfd, remove all
event associations for the file descriptor specified by fd.
event is ignored, and may be NULL.
EPOLL_CTL_MOD
For the epoll(5) instance specified by epfd, modify the
event association for the file descriptor specified by fd
to be that specified by event.
The event parameter has the following structure:
typedef union epoll_data {
void *ptr;
int fd;
uint32_t u32;
uint64_t u64;
} epoll_data_t;
struct epoll_event {
uint32_t events;
epoll_data_t data;
};
The data field specifies the datum to be associated with the event and
will be returned via epoll_wait(3C). The events field denotes both the
desired events (when specified via epoll_ctl()) and the events that
have occurred (when returned via epoll_wait(3C)). In either case, the
events field is a bitmask constructed by a logical OR operation of any
combination of the following event flags:
EPOLLIN
Data other than high priority data may be read without
blocking. For streams, this flag is set in the returned
events even if the message is of zero length.
EPOLLPRI
Normal data (priority band equals 0) may be read without
blocking. For streams, this flag is set in the returned
events even if the message is of zero length.
EPOLLOUT
Normal data (priority band equals 0) may be written with‐
out blocking.
EPOLLRDNORM
Normal data (priority band equals 0) may be read without
blocking. For streams, this flag is set in the returned
revents even if the message is of zero length.
EPOLLRDBAND
Data from a non-zero priority band may be read without
blocking. For streams, this flag is set in the returned
revents even if the message is of zero length.
EPOLLWRNORM
The same as EPOLLOUT.
EPOLLWRBAND
Priority data (priority band > 0) may be written. This
event only examines bands that have been written to at
least once.
EPOLLMSG
This exists only for backwards binary and source compati‐
bility with Linux; it has no meaning and is ignored.
EPOLLERR
An error has occurred on the device or stream. This flag
is only valid in the returned events field.
EPOLLHUP
A hangup has occurred on the stream. This event and
EPOLLOUT are mutually exclusive; a stream can never be
writable if a hangup has occurred. However, this event
and EPOLLIN, EPOLLRDNORM, EPOLLRDBAND, EPOLLRDHUP or
EPOLLPRI are not mutually exclusive. This flag is only
valid in the the events field returned from
epoll_wait(3C); it is not used in the events field speci‐
fied via epoll_ctl().
EPOLLRDHUP
The stream socket peer shutdown the writing half of the
connection and no further data will be readable via the
socket. This event is not mutually exclusive with
EPOLLIN.
EPOLLWAKEUP
This exists only for backwards binary and source compati‐
bility with Linux; it has no meaning and is ignored.
EPOLLONESHOT
Sets the specified event to be in one-shot mode, whereby
the event association with the epoll(5) instance speci‐
fied by epfd is removed atomically as the event is
returned via epoll_wait(3C). Use of this mode allows for
resolution of some of the races inherent in multithreaded
use of epoll_wait(3C).
EPOLLET
Sets the specified event to be edge-triggered mode
instead of the default mode of level-triggered. In this
mode, events will be induced by transitions on an event
source rather than the state of the event source. While
perhaps superficially appealing, this mode introduces
several new potential failure modes for user-level soft‐
ware and should be used with caution.
RETURN VALUES
Upon succesful completion, epoll_ctl() returns 0. If an error occurs,
-1 is returned and errno is set to indicate the error.
ERRORSepoll_ctl() will fail if:
EBADF
epfd is not a valid file descriptor.
EFAULT
The memory associated with event was not mapped.
EEXIST
The operation specified was EPOLL_CTL_ADD and the specified
file descriptor is already associated with an event for the
specified epoll(5) instance.
ENOENT
The operation specified was EPOLL_CTL_MOD or EPOLL_CTL_DEL
and the specified file descriptor is not associated with an
event for the specified epoll(5) instance.
NOTES
The epoll(5) facility is implemented for purposes of offering compati‐
bility for Linux-borne applications; native applications should con‐
tinue to prefer using event ports via the port_create(3C), port_asso‐
ciate(3C) and port_get(3C) interfaces. See epoll(5) for compatibility
details and restrictions.
SEE ALSOepoll_create(3C), epoll_wait(3C), port_create(3C), port_associate(3C),
port_get(3C), epoll(5)
Apr 17, 2014 EPOLL_CTL(3C)
