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