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 2014-12-31 "Linux" "Linux Programmer's Manual"
22 epoll_ctl \- control interface for an epoll 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 performs control operations on the
32 referred to by the file descriptor
34 It requests that the operation
36 be performed for the target file descriptor,
44 Register the target file descriptor
48 instance referred to by the file descriptor
50 and associate the event
52 with the internal file linked to
58 associated with the target file descriptor
62 Remove (deregister) the target file descriptor
66 instance referred to by
70 is ignored and can be NULL (but see BUGS below).
74 argument describes the object linked to the file descriptor
82 typedef union epoll_data {
90 uint32_t events; /* Epoll events */
91 epoll_data_t data; /* User data variable */
98 member is a bit set composed using the following available event
102 The associated file is available for
107 The associated file is available for
111 .BR EPOLLRDHUP " (since Linux 2.6.17)"
112 Stream socket peer closed connection,
113 or shut down writing half of connection.
114 (This flag is especially useful for writing simple code to detect
115 peer shutdown when using Edge Triggered monitoring.)
118 There is urgent data available for
123 Error condition happened on the associated file descriptor.
125 will always wait for this event; it is not necessary to set it in
129 Hang up happened on the associated file descriptor.
131 will always wait for this event; it is not necessary to set it in
135 Sets the Edge Triggered behavior for the associated file descriptor.
136 The default behavior for
141 for more detailed information about Edge and Level Triggered event
142 distribution architectures.
144 .BR EPOLLONESHOT " (since Linux 2.6.2)"
145 Sets the one-shot behavior for the associated file descriptor.
146 This means that after an event is pulled out with
148 the associated file descriptor is internally disabled and no other events
149 will be reported by the
156 to rearm the file descriptor with a new event mask.
158 .BR EPOLLWAKEUP " (since Linux 3.5)"
159 .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238
164 are clear and the process has the
167 ensure that the system does not enter "suspend" or
168 "hibernate" while this event is pending or being processed.
169 The event is considered as being "processed" from the time
170 when it is returned by a call to
172 until the next call to
177 the closure of that file descriptor,
178 the removal of the event file descriptor with
182 for the event file descriptor with
189 When an error occurs,
193 is set appropriately.
200 is not a valid file descriptor.
206 and the supplied file descriptor
208 is already registered with this epoll instance.
219 or the requested operation
221 is not supported by this interface.
231 is not registered with this epoll instance.
234 There was insufficient memory to handle the requested
240 .I /proc/sys/fs/epoll/max_user_watches
241 was encountered while trying to register
242 .RB ( EPOLL_CTL_ADD )
243 a new file descriptor on an epoll instance.
253 This error can occur if
255 refers to, for example, a regular file or a directory.
258 was added to the kernel in version 2.6.
259 .\" To be precise: kernel 2.5.44.
260 .\" The interface should be finalized by Linux kernel 2.5.66.
264 Library support is provided in glibc starting with version 2.3.2.
268 interface supports all file descriptors that support
271 In kernel versions before 2.6.9, the
273 operation required a non-null pointer in
275 even though this argument is ignored.
278 can be specified as NULL
281 Applications that need to be portable to kernels before 2.6.9
282 should specify a non-null pointer in
289 but the caller does not have the
290 .BR CAP_BLOCK_SUSPEND
294 .IR "silently ignored" .
295 This unfortunate behavior is necessary because no validity
296 checks were performed on the
298 argument in the original implementation, and the addition of the
300 with a check that caused the call to fail if the caller did not have the
302 capability caused a breakage in at least one existing user-space
303 application that happened to randomly (and uselessly) specify this bit.
304 .\" commit a8159414d7e3af7233e7a5a82d1c5d85379bd75c (behavior change)
305 .\" https://lwn.net/Articles/520198/
306 A robust application should therefore double check that it has the
308 capability if attempting to use the
312 .BR epoll_create (2),
317 This page is part of release 3.79 of the Linux
320 A description of the project,
321 information about reporting bugs,
322 and the latest version of this page,
324 \%http://www.kernel.org/doc/man\-pages/.