Debian Codegraph @

upstream/debian-unstable/man2/epoll_ctl.2

raw
1 .\" Copyright, the authors of the Linux man-pages project
2 .\"
3 .\" SPDX-License-Identifier: GPL-2.0-or-later
4 .\"
5 .TH epoll_ctl 2 2025-12-25 "Linux man-pages 6.18"
6 .SH NAME
7 epoll_ctl \- control interface for an epoll file descriptor
8 .SH LIBRARY
9 Standard C library
10 .RI ( libc ,\~ \-lc )
11 .SH SYNOPSIS
12 .nf
13 .B #include <sys/epoll.h>
14 .P
15 .BI "int epoll_ctl(int " epfd ", int " op ", int " fd ,
16 .BI " struct epoll_event *_Nullable " event );
17 .fi
18 .SH DESCRIPTION
19 This system call is used to add, modify, or remove
20 entries in the interest list of the
21 .BR epoll (7)
22 instance
23 referred to by the file descriptor
24 .IR epfd .
25 It requests that the operation
26 .I op
27 be performed for the target file descriptor,
28 .IR fd .
29 .P
30 Valid values for the
31 .I op
32 argument are:
33 .TP
34 .B EPOLL_CTL_ADD
35 Add an entry to the interest list of the epoll file descriptor,
36 .IR epfd .
37 The entry includes the file descriptor,
38 .IR fd ,
39 a reference to the corresponding open file description (see
40 .BR epoll (7)
41 and
42 .BR open (2)),
43 and the settings specified in
44 .IR event .
45 .TP
46 .B EPOLL_CTL_MOD
47 Change the settings associated with
48 .I fd
49 in the interest list to the new settings specified in
50 .IR event .
51 .TP
52 .B EPOLL_CTL_DEL
53 Remove (deregister) the target file descriptor
54 .I fd
55 from the interest list.
56 The
57 .I event
58 argument is ignored and can be NULL (but see BUGS below).
59 .P
60 The
61 .I event
62 argument describes the object linked to the file descriptor
63 .IR fd .
64 The
65 .I struct epoll_event
66 is described in
67 .BR epoll_event (3type).
68 .P
69 The
70 .I data
71 member of the
72 .I epoll_event
73 structure specifies data that the kernel should save and then return (via
74 .BR epoll_wait (2))
75 when this file descriptor becomes ready.
76 .P
77 The
78 .I events
79 member of the
80 .I epoll_event
81 structure is a bit mask composed by ORing together zero or more event types,
82 returned by
83 .BR epoll_wait (2),
84 and input flags, which affect its behavior, but aren't returned.
85 The available event types are:
86 .TP
87 .B EPOLLIN
88 The associated file is available for
89 .BR read (2)
90 operations.
91 .TP
92 .B EPOLLOUT
93 The associated file is available for
94 .BR write (2)
95 operations.
96 .TP
97 .BR EPOLLRDHUP " (since Linux 2.6.17)"
98 Stream socket peer closed connection,
99 or shut down writing half of connection.
100 (This flag is especially useful for writing simple code to detect
101 peer shutdown when using edge-triggered monitoring.)
102 .TP
103 .B EPOLLPRI
104 There is an exceptional condition on the file descriptor.
105 See the discussion of
106 .B POLLPRI
107 in
108 .BR poll (2).
109 .TP
110 .B EPOLLERR
111 Error condition happened on the associated file descriptor.
112 This event is also reported for the write end of a pipe when the read end
113 has been closed.
114 .IP
115 .BR epoll_wait (2)
116 will always report for this event;
117 it is not necessary to set it in
118 .I events
119 when calling
120 .BR epoll_ctl ().
121 .TP
122 .B EPOLLHUP
123 Hang up happened on the associated file descriptor.
124 .IP
125 .BR epoll_wait (2)
126 will always wait for this event;
127 it is not necessary to set it in
128 .I events
129 when calling
130 .BR epoll_ctl ().
131 .IP
132 Note that when reading from a channel such as a pipe or a stream socket,
133 this event merely indicates that the peer closed its end of the channel.
134 Subsequent reads from the channel will return 0 (end of file)
135 only after all outstanding data in the channel has been consumed.
136 .P
137 And the available input flags are:
138 .TP
139 .B EPOLLET
140 Requests edge-triggered notification for the associated file descriptor.
141 The default behavior for
142 .B epoll
143 is level-triggered.
144 See
145 .BR epoll (7)
146 for more detailed information about edge-triggered and
147 level-triggered notification.
148 .TP
149 .BR EPOLLONESHOT " (since Linux 2.6.2)"
150 Requests one-shot notification for the associated file descriptor.
151 This means that after an event notified for the file descriptor by
152 .BR epoll_wait (2),
153 the file descriptor is disabled in the interest list and no other events
154 will be reported by the
155 .B epoll
156 interface.
157 The user must call
158 .BR epoll_ctl ()
159 with
160 .B EPOLL_CTL_MOD
161 to rearm the file descriptor with a new event mask.
162 .TP
163 .BR EPOLLWAKEUP " (since Linux 3.5)"
164 .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
165 If
166 .B EPOLLONESHOT
167 and
168 .B EPOLLET
169 are clear and the process has the
170 .B CAP_BLOCK_SUSPEND
171 capability,
172 ensure that the system does not enter "suspend" or
173 "hibernate" while this event is pending or being processed.
174 The event is considered as being "processed" from the time
175 when it is returned by a call to
176 .BR epoll_wait (2)
177 until the next call to
178 .BR epoll_wait (2)
179 on the same
180 .BR epoll (7)
181 file descriptor,
182 the closure of that file descriptor,
183 the removal of the event file descriptor with
184 .BR EPOLL_CTL_DEL ,
185 or the clearing of
186 .B EPOLLWAKEUP
187 for the event file descriptor with
188 .BR EPOLL_CTL_MOD .
189 See also BUGS.
190 .TP
191 .BR EPOLLEXCLUSIVE " (since Linux 4.5)"
192 Sets an exclusive wakeup mode for the epoll file descriptor that is being
193 attached to the target file descriptor,
194 .IR fd .
195 When a wakeup event occurs and multiple epoll file descriptors
196 are attached to the same target file using
197 .BR EPOLLEXCLUSIVE ,
198 one or more of the epoll file descriptors will receive an event with
199 .BR epoll_wait (2).
200 The default in this scenario (when
201 .B EPOLLEXCLUSIVE
202 is not set) is for all epoll file descriptors to receive an event.
203 .B EPOLLEXCLUSIVE
204 is thus useful for avoiding thundering herd problems in certain scenarios.
205 .IP
206 If the same file descriptor is in multiple epoll instances,
207 some with the
208 .B EPOLLEXCLUSIVE
209 flag, and others without, then events will be provided to all epoll
210 instances that did not specify
211 .BR EPOLLEXCLUSIVE ,
212 and at least one of the epoll instances that did specify
213 .BR EPOLLEXCLUSIVE .
214 .IP
215 The following values may be specified in conjunction with
216 .BR EPOLLEXCLUSIVE :
217 .BR EPOLLIN ,
218 .BR EPOLLOUT ,
219 .BR EPOLLWAKEUP ,
220 and
221 .BR EPOLLET .
222 .B EPOLLHUP
223 and
224 .B EPOLLERR
225 can also be specified, but this is not required:
226 as usual, these events are always reported if they occur,
227 regardless of whether they are specified in
228 .IR events .
229 Attempts to specify other values in
230 .I events
231 yield the error
232 .BR EINVAL .
233 .IP
234 .B EPOLLEXCLUSIVE
235 may be used only in an
236 .B EPOLL_CTL_ADD
237 operation;
238 attempts to employ it with
239 .B EPOLL_CTL_MOD
240 yield an error.
241 If
242 .B EPOLLEXCLUSIVE
243 has been set using
244 .BR epoll_ctl (),
245 then a subsequent
246 .B EPOLL_CTL_MOD
247 on the same
248 .IR epfd ,\~ fd
249 pair yields an error.
250 A call to
251 .BR epoll_ctl ()
252 that specifies
253 .B EPOLLEXCLUSIVE
254 in
255 .I events
256 and specifies the target file descriptor
257 .I fd
258 as an epoll instance will likewise fail.
259 The error in all of these cases is
260 .BR EINVAL .
261 .SH RETURN VALUE
262 When successful,
263 .BR epoll_ctl ()
264 returns zero.
265 When an error occurs,
266 .BR epoll_ctl ()
267 returns \-1 and
268 .I errno
269 is set to indicate the error.
270 .SH ERRORS
271 .TP
272 .B EBADF
273 .I epfd
274 or
275 .I fd
276 is not a valid file descriptor.
277 .TP
278 .B EEXIST
279 .I op
280 was
281 .BR EPOLL_CTL_ADD ,
282 and the supplied file descriptor
283 .I fd
284 is already registered with this epoll instance.
285 .TP
286 .B EINVAL
287 .I epfd
288 is not an
289 .B epoll
290 file descriptor,
291 or
292 .I fd
293 is the same as
294 .IR epfd ,
295 or the requested operation
296 .I op
297 is not supported by this interface.
298 .TP
299 .B EINVAL
300 An invalid event type was specified along with
301 .B EPOLLEXCLUSIVE
302 in
303 .IR events .
304 .TP
305 .B EINVAL
306 .I op
307 was
308 .B EPOLL_CTL_MOD
309 and
310 .I events
311 included
312 .BR EPOLLEXCLUSIVE .
313 .TP
314 .B EINVAL
315 .I op
316 was
317 .B EPOLL_CTL_MOD
318 and the
319 .B EPOLLEXCLUSIVE
320 flag has previously been applied to this
321 .IR epfd ,\~ fd
322 pair.
323 .TP
324 .B EINVAL
325 .B EPOLLEXCLUSIVE
326 was specified in
327 .I event
328 and
329 .I fd
330 refers to an epoll instance.
331 .TP
332 .B ELOOP
333 .I fd
334 refers to an epoll instance and this
335 .B EPOLL_CTL_ADD
336 operation would result in a circular loop of epoll instances
337 monitoring one another or a nesting depth of epoll instances
338 greater than 5.
339 .TP
340 .B ENOENT
341 .I op
342 was
343 .B EPOLL_CTL_MOD
344 or
345 .BR EPOLL_CTL_DEL ,
346 and
347 .I fd
348 is not registered with this epoll instance.
349 .TP
350 .B ENOMEM
351 There was insufficient memory to handle the requested
352 .I op
353 control operation.
354 .TP
355 .B ENOSPC
356 The limit imposed by
357 .I /proc/sys/fs/epoll/max_user_watches
358 was encountered while trying to register
359 .RB ( EPOLL_CTL_ADD )
360 a new file descriptor on an epoll instance.
361 See
362 .BR epoll (7)
363 for further details.
364 .TP
365 .B EPERM
366 The target file
367 .I fd
368 does not support
369 .BR epoll .
370 This error can occur if
371 .I fd
372 refers to, for example, a regular file or a directory.
373 .SH STANDARDS
374 Linux.
375 .SH HISTORY
376 Linux 2.6,
377 .\" To be precise: Linux 2.5.44.
378 .\" The interface should be finalized by Linux 2.5.66.
379 glibc 2.3.2.
380 .SH NOTES
381 The
382 .B epoll
383 interface supports all file descriptors that support
384 .BR poll (2).
385 .SH BUGS
386 Before Linux 2.6.9, the
387 .B EPOLL_CTL_DEL
388 operation required a non-null pointer in
389 .IR event ,
390 even though this argument is ignored.
391 Since Linux 2.6.9,
392 .I event
393 can be specified as NULL
394 when using
395 .BR EPOLL_CTL_DEL .
396 Applications that need to be portable to kernels before Linux 2.6.9
397 should specify a non-null pointer in
398 .IR event .
399 .P
400 If
401 .B EPOLLWAKEUP
402 is specified in
403 .IR flags ,
404 but the caller does not have the
405 .B CAP_BLOCK_SUSPEND
406 capability, then the
407 .B EPOLLWAKEUP
408 flag is
409 .IR "silently ignored" .
410 This unfortunate behavior is necessary because no validity
411 checks were performed on the
412 .I flags
413 argument in the original implementation, and the addition of the
414 .B EPOLLWAKEUP
415 with a check that caused the call to fail if the caller did not have the
416 .B CAP_BLOCK_SUSPEND
417 capability caused a breakage in at least one existing user-space
418 application that happened to randomly (and uselessly) specify this bit.
419 .\" commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change)
420 .\" https://lwn.net/Articles/520198/
421 A robust application should therefore double check that it has the
422 .B CAP_BLOCK_SUSPEND
423 capability if attempting to use the
424 .B EPOLLWAKEUP
425 flag.
426 .SH SEE ALSO
427 .BR epoll_create (2),
428 .BR epoll_wait (2),
429 .BR ioctl_eventpoll (2),
430 .BR poll (2),
431 .BR epoll (7)