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
without 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
compatibility 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 events field
returned from epoll_wait(3C); it is not used in the events field
specified 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
compatibility 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 specified 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 software and should be used with
caution.