1EPOLL_CTL(2) Linux Programmer's Manual EPOLL_CTL(2)
2
6 epoll_ctl - control interface for an epoll file descriptor
7
9 #include <sys/epoll.h>
10 int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);
12
14 This system call is used to add, modify, or remove entries in the in‐
15 terest list of the epoll(7) instance referred to by the file descriptor
16 epfd. It requests that the operation op be performed for the target
17 file descriptor, fd.
18 Valid values for the op argument are:
20 EPOLL_CTL_ADD
22 Add an entry to the interest list of the epoll file descriptor,
23 epfd. The entry includes the file descriptor, fd, a reference
24 to the corresponding open file description (see epoll(7) and
25 open(2)), and the settings specified in event.
26 EPOLL_CTL_MOD
28 Change the settings associated with fd in the interest list to
29 the new settings specified in event.
30 EPOLL_CTL_DEL
32 Remove (deregister) the target file descriptor fd from the in‐
33 terest list. The event argument is ignored and can be NULL (but
34 see BUGS below).
35 The event argument describes the object linked to the file descriptor
37 fd. The struct epoll_event is defined as:
38 typedef union epoll_data {
40 void *ptr;
41 int fd;
42 uint32_t u32;
43 uint64_t u64;
44 } epoll_data_t;
45 struct epoll_event {
47 uint32_t events; /* Epoll events */
48 epoll_data_t data; /* User data variable */
49 };
50 The data member of the epoll_event structure specifies data that the
52 kernel should save and then return (via epoll_wait(2)) when this file
53 descriptor becomes ready.
54 The events member of the epoll_event structure is a bit mask composed
56 by ORing together zero or more of the following available event types:
57 EPOLLIN
59 The associated file is available for read(2) operations.
60 EPOLLOUT
62 The associated file is available for write(2) operations.
63 EPOLLRDHUP (since Linux 2.6.17)
65 Stream socket peer closed connection, or shut down writing half
66 of connection. (This flag is especially useful for writing sim‐
67 ple code to detect peer shutdown when using edge-triggered moni‐
68 toring.)
69 EPOLLPRI
71 There is an exceptional condition on the file descriptor. See
72 the discussion of POLLPRI in poll(2).
73 EPOLLERR
75 Error condition happened on the associated file descriptor.
76 This event is also reported for the write end of a pipe when the
77 read end has been closed.
78 epoll_wait(2) will always report for this event; it is not nec‐
80 essary to set it in events when calling epoll_ctl().
81 EPOLLHUP
83 Hang up happened on the associated file descriptor.
84 epoll_wait(2) will always wait for this event; it is not neces‐
86 sary to set it in events when calling epoll_ctl().
87 Note that when reading from a channel such as a pipe or a stream
89 socket, this event merely indicates that the peer closed its end
90 of the channel. Subsequent reads from the channel will return 0
91 (end of file) only after all outstanding data in the channel has
92 been consumed.
93 EPOLLET
95 Requests edge-triggered notification for the associated file de‐
96 scriptor. The default behavior for epoll is level-triggered.
97 See epoll(7) for more detailed information about edge-triggered
98 and level-triggered notification.
99 This flag is an input flag for the event.events field when call‐
101 ing epoll_ctl(); it is never returned by epoll_wait(2).
102 EPOLLONESHOT (since Linux 2.6.2)
104 Requests one-shot notification for the associated file descrip‐
105 tor. This means that after an event notified for the file de‐
106 scriptor by epoll_wait(2), the file descriptor is disabled in
107 the interest list and no other events will be reported by the
108 epoll interface. The user must call epoll_ctl() with
109 EPOLL_CTL_MOD to rearm the file descriptor with a new event
110 mask.
111 This flag is an input flag for the event.events field when call‐
113 ing epoll_ctl(); it is never returned by epoll_wait(2).
114 EPOLLWAKEUP (since Linux 3.5)
116 If EPOLLONESHOT and EPOLLET are clear and the process has the
117 CAP_BLOCK_SUSPEND capability, ensure that the system does not
118 enter "suspend" or "hibernate" while this event is pending or
119 being processed. The event is considered as being "processed"
120 from the time when it is returned by a call to epoll_wait(2) un‐
121 til the next call to epoll_wait(2) on the same epoll(7) file de‐
122 scriptor, the closure of that file descriptor, the removal of
123 the event file descriptor with EPOLL_CTL_DEL, or the clearing of
124 EPOLLWAKEUP for the event file descriptor with EPOLL_CTL_MOD.
125 See also BUGS.
126 This flag is an input flag for the event.events field when call‐
128 ing epoll_ctl(); it is never returned by epoll_wait(2).
129 EPOLLEXCLUSIVE (since Linux 4.5)
131 Sets an exclusive wakeup mode for the epoll file descriptor that
132 is being attached to the target file descriptor, fd. When a
133 wakeup event occurs and multiple epoll file descriptors are at‐
134 tached to the same target file using EPOLLEXCLUSIVE, one or more
135 of the epoll file descriptors will receive an event with
136 epoll_wait(2). The default in this scenario (when EPOLLEXCLU‐
137 SIVE is not set) is for all epoll file descriptors to receive an
138 event. EPOLLEXCLUSIVE is thus useful for avoiding thundering
139 herd problems in certain scenarios.
140 If the same file descriptor is in multiple epoll instances, some
142 with the EPOLLEXCLUSIVE flag, and others without, then events
143 will be provided to all epoll instances that did not specify
144 EPOLLEXCLUSIVE, and at least one of the epoll instances that did
145 specify EPOLLEXCLUSIVE.
146 The following values may be specified in conjunction with
148 EPOLLEXCLUSIVE: EPOLLIN, EPOLLOUT, EPOLLWAKEUP, and EPOLLET.
149 EPOLLHUP and EPOLLERR can also be specified, but this is not re‐
150 quired: as usual, these events are always reported if they oc‐
151 cur, regardless of whether they are specified in events. At‐
152 tempts to specify other values in events yield the error EINVAL.
153 EPOLLEXCLUSIVE may be used only in an EPOLL_CTL_ADD operation;
155 attempts to employ it with EPOLL_CTL_MOD yield an error. If
156 EPOLLEXCLUSIVE has been set using epoll_ctl(), then a subsequent
157 EPOLL_CTL_MOD on the same epfd, fd pair yields an error. A call
158 to epoll_ctl() that specifies EPOLLEXCLUSIVE in events and spec‐
159 ifies the target file descriptor fd as an epoll instance will
160 likewise fail. The error in all of these cases is EINVAL.
161 The EPOLLEXCLUSIVE flag is an input flag for the event.events
163 field when calling epoll_ctl(); it is never returned by
164 epoll_wait(2).
165
167 When successful, epoll_ctl() returns zero. When an error occurs,
168 epoll_ctl() returns -1 and errno is set to indicate the error.
169
171 EBADF epfd or fd is not a valid file descriptor.
172 EEXIST op was EPOLL_CTL_ADD, and the supplied file descriptor fd is al‐
174 ready registered with this epoll instance.
175 EINVAL epfd is not an epoll file descriptor, or fd is the same as epfd,
177 or the requested operation op is not supported by this inter‐
178 face.
179 EINVAL An invalid event type was specified along with EPOLLEXCLUSIVE in
181 events.
182 EINVAL op was EPOLL_CTL_MOD and events included EPOLLEXCLUSIVE.
184 EINVAL op was EPOLL_CTL_MOD and the EPOLLEXCLUSIVE flag has previously
186 been applied to this epfd, fd pair.
187 EINVAL EPOLLEXCLUSIVE was specified in event and fd refers to an epoll
189 instance.
190 ELOOP fd refers to an epoll instance and this EPOLL_CTL_ADD operation
192 would result in a circular loop of epoll instances monitoring
193 one another or a nesting depth of epoll instances greater than
194 5.
195 ENOENT op was EPOLL_CTL_MOD or EPOLL_CTL_DEL, and fd is not registered
197 with this epoll instance.
198 ENOMEM There was insufficient memory to handle the requested op control
200 operation.
201 ENOSPC The limit imposed by /proc/sys/fs/epoll/max_user_watches was en‐
203 countered while trying to register (EPOLL_CTL_ADD) a new file
204 descriptor on an epoll instance. See epoll(7) for further de‐
205 tails.
206 EPERM The target file fd does not support epoll. This error can occur
208 if fd refers to, for example, a regular file or a directory.
209
211 epoll_ctl() was added to the kernel in version 2.6. Library support is
212 provided in glibc starting with version 2.3.2.
213
215 epoll_ctl() is Linux-specific.
216
218 The epoll interface supports all file descriptors that support poll(2).
219
221 In kernel versions before 2.6.9, the EPOLL_CTL_DEL operation required a
222 non-null pointer in event, even though this argument is ignored. Since
223 Linux 2.6.9, event can be specified as NULL when using EPOLL_CTL_DEL.
224 Applications that need to be portable to kernels before 2.6.9 should
225 specify a non-null pointer in event.
226 If EPOLLWAKEUP is specified in flags, but the caller does not have the
228 CAP_BLOCK_SUSPEND capability, then the EPOLLWAKEUP flag is silently ig‐
229 nored. This unfortunate behavior is necessary because no validity
230 checks were performed on the flags argument in the original implementa‐
231 tion, and the addition of the EPOLLWAKEUP with a check that caused the
232 call to fail if the caller did not have the CAP_BLOCK_SUSPEND capabil‐
233 ity caused a breakage in at least one existing user-space application
234 that happened to randomly (and uselessly) specify this bit. A robust
235 application should therefore double check that it has the
236 CAP_BLOCK_SUSPEND capability if attempting to use the EPOLLWAKEUP flag.
237
239 epoll_create(2), epoll_wait(2), poll(2), epoll(7)
240
242 This page is part of release 5.12 of the Linux man-pages project. A
243 description of the project, information about reporting bugs, and the
244 latest version of this page, can be found at
245 https://www.kernel.org/doc/man-pages/.
246Linux 2021-03-22 EPOLL_CTL(2)