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>
5 .\" SPDX-License-Identifier: GPL-2.0-or-later
7 .TH epoll_ctl 2 (date) "Linux man-pages (unreleased)"
9 epoll_ctl \- control interface for an epoll file descriptor
12 .RI ( libc ", " \-lc )
15 .B #include <sys/epoll.h>
17 .BI "int epoll_ctl(int " epfd ", int " op ", int " fd ,
18 .BI " struct epoll_event *_Nullable " event );
21 This system call is used to add, modify, or remove
22 entries in the interest list of the
25 referred to by the file descriptor
27 It requests that the operation
29 be performed for the target file descriptor,
37 Add an entry to the interest list of the epoll file descriptor,
39 The entry includes the file descriptor,
41 a reference to the corresponding open file description (see
45 and the settings specified in
49 Change the settings associated with
51 in the interest list to the new settings specified in
55 Remove (deregister) the target file descriptor
57 from the interest list.
60 argument is ignored and can be NULL (but see BUGS below).
64 argument describes the object linked to the file descriptor
69 .BR epoll_event (3type).
75 structure specifies data that the kernel should save and then return (via
77 when this file descriptor becomes ready.
83 structure is a bit mask composed by ORing together zero or more event types,
86 and input flags, which affect its behaviour, but aren't returned.
87 The available event types are:
90 The associated file is available for
95 The associated file is available for
99 .BR EPOLLRDHUP " (since Linux 2.6.17)"
100 Stream socket peer closed connection,
101 or shut down writing half of connection.
102 (This flag is especially useful for writing simple code to detect
103 peer shutdown when using edge-triggered monitoring.)
106 There is an exceptional condition on the file descriptor.
107 See the discussion of
113 Error condition happened on the associated file descriptor.
114 This event is also reported for the write end of a pipe when the read end
118 will always report for this event; it is not necessary to set it in
124 Hang up happened on the associated file descriptor.
127 will always wait for this event; it is not necessary to set it in
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.
137 And the available input flags are:
140 Requests edge-triggered notification for the associated file descriptor.
141 The default behavior for
146 for more detailed information about edge-triggered and
147 level-triggered notification.
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
153 the file descriptor is disabled in the interest list and no other events
154 will be reported by the
161 to rearm the file descriptor with a new event mask.
163 .BR EPOLLWAKEUP " (since Linux 3.5)"
164 .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
169 are clear and the process has the
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
177 until the next call to
182 the closure of that file descriptor,
183 the removal of the event file descriptor with
187 for the event file descriptor with
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,
195 When a wakeup event occurs and multiple epoll file descriptors
196 are attached to the same target file using
198 one or more of the epoll file descriptors will receive an event with
200 The default in this scenario (when
202 is not set) is for all epoll file descriptors to receive an event.
204 is thus useful for avoiding thundering herd problems in certain scenarios.
206 If the same file descriptor is in multiple epoll instances,
209 flag, and others without, then events will be provided to all epoll
210 instances that did not specify
212 and at least one of the epoll instances that did specify
215 The following values may be specified in conjunction with
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
229 Attempts to specify other values in
235 may be used only in an
237 operation; attempts to employ it with
248 pair yields an error.
255 and specifies the target file descriptor
257 as an epoll instance will likewise fail.
258 The error in all of these cases is
264 When an error occurs,
268 is set to indicate the error.
275 is not a valid file descriptor.
281 and the supplied file descriptor
283 is already registered with this epoll instance.
294 or the requested operation
296 is not supported by this interface.
299 An invalid event type was specified along with
319 flag has previously been applied to this
329 refers to an epoll instance.
333 refers to an epoll instance and this
335 operation would result in a circular loop of epoll instances
336 monitoring one another or a nesting depth of epoll instances
347 is not registered with this epoll instance.
350 There was insufficient memory to handle the requested
356 .I /proc/sys/fs/epoll/max_user_watches
357 was encountered while trying to register
358 .RB ( EPOLL_CTL_ADD )
359 a new file descriptor on an epoll instance.
369 This error can occur if
371 refers to, for example, a regular file or a directory.
376 .\" To be precise: Linux 2.5.44.
377 .\" The interface should be finalized by Linux 2.5.66.
382 interface supports all file descriptors that support
385 Before Linux 2.6.9, the
387 operation required a non-null pointer in
389 even though this argument is ignored.
392 can be specified as NULL
395 Applications that need to be portable to kernels before Linux 2.6.9
396 should specify a non-null pointer in
403 but the caller does not have the
408 .IR "silently ignored" .
409 This unfortunate behavior is necessary because no validity
410 checks were performed on the
412 argument in the original implementation, and the addition of the
414 with a check that caused the call to fail if the caller did not have the
416 capability caused a breakage in at least one existing user-space
417 application that happened to randomly (and uselessly) specify this bit.
418 .\" commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change)
419 .\" https://lwn.net/Articles/520198/
420 A robust application should therefore double check that it has the
422 capability if attempting to use the
426 .BR epoll_create (2),