1 .\" Copyright (C) 2003 Davide Libenzi
2 .\" Davide Libenzi <davidel@xmailserver.org>
4 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
5 .\" This program is free software; you can redistribute it and/or modify
6 .\" it under the terms of the GNU General Public License as published by
7 .\" the Free Software Foundation; either version 2 of the License, or
8 .\" (at your option) any later version.
10 .\" This program is distributed in the hope that it will be useful,
11 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
12 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 .\" GNU General Public License for more details.
15 .\" You should have received a copy of the GNU General Public
16 .\" License along with this manual; if not, see
17 .\" <http://www.gnu.org/licenses/>.
20 .TH EPOLL_CTL 2 2017-09-15 "Linux" "Linux Programmer's Manual"
22 epoll_ctl \- control interface for an epoll file descriptor
24 .B #include <sys/epoll.h>
26 .BI "int epoll_ctl(int " epfd ", int " op ", int " fd \
27 ", struct epoll_event *" event );
29 This system call is used to add, modify, or remove
30 entries in the interest list of the
33 referred to by the file descriptor
35 It requests that the operation
37 be performed for the target file descriptor,
48 and associate the settings specified in
50 with the internal file linked to
54 Change the settings associated with
56 in the interest list to the new settings specified in
60 Remove (deregister) the target file descriptor
62 from the interest list.
65 argument is ignored and can be NULL (but see BUGS below).
69 argument describes the object linked to the file descriptor
77 typedef union epoll_data {
85 uint32_t events; /* Epoll events */
86 epoll_data_t data; /* User data variable */
93 member is a bit mask composed by ORing together zero or more of
94 the following available event types:
97 The associated file is available for
102 The associated file is available for
106 .BR EPOLLRDHUP " (since Linux 2.6.17)"
107 Stream socket peer closed connection,
108 or shut down writing half of connection.
109 (This flag is especially useful for writing simple code to detect
110 peer shutdown when using Edge Triggered monitoring.)
113 There is an exceptional condition on the file descriptor.
114 See the discussion of
120 Error condition happened on the associated file descriptor.
121 This event is also reported for the write end of a pipe when the read end
124 will always report for this event; it is not necessary to set it in
128 Hang up happened on the associated file descriptor.
130 will always wait for this event; it is not necessary to set it in
133 Note that when reading from a channel such as a pipe or a stream socket,
134 this event merely indicates that the peer closed its end of the channel.
135 Subsequent reads from the channel will return 0 (end of file)
136 only after all outstanding data in the channel has been consumed.
139 Sets the Edge Triggered behavior for the associated file descriptor.
140 The default behavior for
145 for more detailed information about Edge and Level Triggered event
146 distribution architectures.
148 .BR EPOLLONESHOT " (since Linux 2.6.2)"
149 Sets the one-shot behavior for the associated file descriptor.
150 This means that after an event is pulled out with
152 the associated file descriptor is internally disabled and no other events
153 will be reported by the
160 to rearm the file descriptor with a new event mask.
162 .BR EPOLLWAKEUP " (since Linux 3.5)"
163 .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
168 are clear and the process has the
171 ensure that the system does not enter "suspend" or
172 "hibernate" while this event is pending or being processed.
173 The event is considered as being "processed" from the time
174 when it is returned by a call to
176 until the next call to
181 the closure of that file descriptor,
182 the removal of the event file descriptor with
186 for the event file descriptor with
190 .BR EPOLLEXCLUSIVE " (since Linux 4.5)"
191 Sets an exclusive wakeup mode for the epoll file descriptor that is being
192 attached to the target file descriptor,
194 When a wakeup event occurs and multiple epoll file descriptors
195 are attached to the same target file using
197 one or more of the epoll file descriptors will receive an event with
199 The default in this scenario (when
201 is not set) is for all epoll file descriptors to receive an event.
203 is thus useful for avoiding thundering herd problems in certain scenarios.
205 If the same file descriptor is in multiple epoll instances,
208 flag, and others without, then events will be provided to all epoll
209 instances that did not specify
211 and at least one of the epoll instances that did specify
214 The following values may be specified in conjunction with
224 can also be specified, but this is not required:
225 as usual, these events are always reported if they occur,
226 regardless of whether they are specified in
228 Attempts to specify other values in
234 may be used only in an
236 operation; attempts to employ it with
247 pair yields an error.
254 and specifies the target file descriptor
256 as an epoll instance will likewise fail.
257 The error in all of these cases is
263 When an error occurs,
267 is set appropriately.
274 is not a valid file descriptor.
280 and the supplied file descriptor
282 is already registered with this epoll instance.
293 or the requested operation
295 is not supported by this interface.
298 An invalid event type was specified along with
318 flag has previously been applied to this
328 refers to an epoll instance.
332 refers to an epoll instance and this
334 operation would result in a circular loop of epoll instances
335 monitoring one another.
345 is not registered with this epoll instance.
348 There was insufficient memory to handle the requested
354 .I /proc/sys/fs/epoll/max_user_watches
355 was encountered while trying to register
356 .RB ( EPOLL_CTL_ADD )
357 a new file descriptor on an epoll instance.
367 This error can occur if
369 refers to, for example, a regular file or a directory.
372 was added to the kernel in version 2.6.
373 .\" To be precise: kernel 2.5.44.
374 .\" The interface should be finalized by Linux kernel 2.5.66.
378 Library support is provided in glibc starting with version 2.3.2.
382 interface supports all file descriptors that support
385 In kernel versions before 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 2.6.9
396 should specify a non-null pointer in
403 but the caller does not have the
404 .BR CAP_BLOCK_SUSPEND
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),