man/man3c/epoll_ctl.3c

         te
 Copyright (c) 2014, Joyent, Inc. All Rights Reserved.
 Copyright 2020 Oxide Computer Company
 This file and its contents are supplied under the terms of the
 Common Development and Distribution License ("CDDL"), version 1.0.
 You may only use this file in accordance with the terms of version
 1.0 of the CDDL.

 A full copy of the text of the CDDL should have accompanied this
 source. A copy of the CDDL is also available via the Internet at
 http://www.illumos.org/license/CDDL.
 EPOLL_CTL 3C "June 29, 2020"
 NAME
epoll_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 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.


EPOLLEXCLUSIVE

This is present for binary compatibility and is effectively a no-op on illumos.

The flag was added to Linux in v4.5 to provide a means to mitigate thundering
herd problems when multiple epoll instances contain the same event source. Set
on a specified event source during EPOLL_CTL_ADD (and not allowed with
EPOLL_CTL_MOD), it indicates that epoll should attempt to limit the scope
of pollers woken when a shared target resource changes state. All pollers
without the flag set in the event will be notified and one or more of
those with it set will be as well.


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.


 RETURN VALUES
Upon successful completion, epoll_ctl() returns 0.
If an error occurs, -1 is returned and errno is set to indicate
the error.

 ERRORS
epoll_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
compatibility for Linux-borne applications; native
applications should continue to prefer using event ports via the
port_create(3C), port_associate(3C) and port_get(3C)
interfaces. See epoll(5) for compatibility details and restrictions.

 SEE ALSO
epoll_create(3C), epoll_wait(3C),
port_create(3C), port_associate(3C), port_get(3C),
epoll(5)