1 .\" epoll by Davide Libenzi ( efficient event notification retrieval )
2 .\" Copyright (C) 2003 Davide Libenzi
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 .\" Davide Libenzi <davidel@xmailserver.org>
22 .TH EPOLL_CTL 2 2012-04-15 "Linux" "Linux Programmer's Manual"
24 epoll_ctl \- control interface for an epoll descriptor
26 .B #include <sys/epoll.h>
28 .BI "int epoll_ctl(int " epfd ", int " op ", int " fd \
29 ", struct epoll_event *" event );
31 This system call performs control operations on the
34 referred to by the file descriptor
36 It requests that the operation
38 be performed for the target file descriptor,
46 Register the target file descriptor
50 instance referred to by the file descriptor
52 and associate the event
54 with the internal file linked to
60 associated with the target file descriptor
64 Remove (deregister) the target file descriptor
68 instance referred to by
72 is ignored and can be NULL (but see BUGS below).
76 argument describes the object linked to the file descriptor
84 typedef union epoll_data {
92 uint32_t events; /* Epoll events */
93 epoll_data_t data; /* User data variable */
100 member is a bit set composed using the following available event
104 The associated file is available for
109 The associated file is available for
113 .BR EPOLLRDHUP " (since Linux 2.6.17)"
114 Stream socket peer closed connection,
115 or shut down writing half of connection.
116 (This flag is especially useful for writing simple code to detect
117 peer shutdown when using Edge Triggered monitoring.)
120 There is urgent data available for
125 Error condition happened on the associated file descriptor.
127 will always wait for this event; it is not necessary to set it in
131 Hang up happened on the associated file descriptor.
133 will always wait for this event; it is not necessary to set it in
137 Sets the Edge Triggered behavior for the associated file descriptor.
138 The default behavior for
143 for more detailed information about Edge and Level Triggered event
144 distribution architectures.
146 .BR EPOLLONESHOT " (since Linux 2.6.2)"
147 Sets the one-shot behavior for the associated file descriptor.
148 This means that after an event is pulled out with
150 the associated file descriptor is internally disabled and no other events
151 will be reported by the
158 to rearm the file descriptor with a new event mask.
163 When an error occurs,
167 is set appropriately.
174 is not a valid file descriptor.
180 and the supplied file descriptor
182 is already registered with this epoll instance.
193 or the requested operation
195 is not supported by this interface.
205 is not registered with this epoll instance.
208 There was insufficient memory to handle the requested
214 .I /proc/sys/fs/epoll/max_user_watches
215 was encountered while trying to register
216 .RB ( EPOLL_CTL_ADD )
217 a new file descriptor on an epoll instance.
229 was added to the kernel in version 2.6.
230 .\" To be precise: kernel 2.5.44.
231 .\" The interface should be finalized by Linux kernel 2.5.66.
235 Library support is provided in glibc starting with version 2.3.2.
239 interface supports all file descriptors that support
242 In kernel versions before 2.6.9, the
244 operation required a non-NULL pointer in
246 even though this argument is ignored.
249 can be specified as NULL
252 Applications that need to be portable to kernels before 2.6.9
253 should specify a non-NULL pointer in
256 .BR epoll_create (2),