]>
Commit | Line | Data |
---|---|---|
fea681da | 1 | .\" Copyright (C) 2003 Davide Libenzi |
4366109b | 2 | .\" Davide Libenzi <davidel@xmailserver.org> |
fea681da | 3 | .\" |
f0008367 | 4 | .\" %%%LICENSE_START(GPLv2+_SW_3_PARA) |
fea681da MK |
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. | |
9 | .\" | |
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. | |
14 | .\" | |
68fa4398 MK |
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/>. | |
8ff7380d | 18 | .\" %%%LICENSE_END |
fea681da | 19 | .\" |
4b8c67d9 | 20 | .TH EPOLL_CTL 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 21 | .SH NAME |
d9cb0d7d | 22 | epoll_ctl \- control interface for an epoll file descriptor |
fea681da MK |
23 | .SH SYNOPSIS |
24 | .B #include <sys/epoll.h> | |
68e4db0a | 25 | .PP |
52e87bbe MK |
26 | .BI "int epoll_ctl(int " epfd ", int " op ", int " fd \ |
27 | ", struct epoll_event *" event ); | |
fea681da | 28 | .SH DESCRIPTION |
a16ce618 MK |
29 | This system call is used to add, modify, or remove |
30 | entries in the interest list of the | |
78d1cbde MK |
31 | .BR epoll (7) |
32 | instance | |
a58b3360 MK |
33 | referred to by the file descriptor |
34 | .IR epfd . | |
35 | It requests that the operation | |
0daa9e92 | 36 | .I op |
7829230a | 37 | be performed for the target file descriptor, |
fea681da | 38 | .IR fd . |
efeece04 | 39 | .PP |
7829230a MK |
40 | Valid values for the |
41 | .I op | |
e87feb33 | 42 | argument are: |
7829230a MK |
43 | .TP |
44 | .B EPOLL_CTL_ADD | |
a16ce618 | 45 | Add |
7829230a | 46 | .I fd |
a16ce618 | 47 | to the interest list |
f6d844a9 | 48 | and associate the settings specified in |
7829230a MK |
49 | .I event |
50 | with the internal file linked to | |
51 | .IR fd . | |
52 | .TP | |
53 | .B EPOLL_CTL_MOD | |
f6d844a9 | 54 | Change the settings associated with |
a16ce618 | 55 | .IR fd |
f6d844a9 MK |
56 | in the interest list to the new settings specified in |
57 | .IR event . | |
7829230a MK |
58 | .TP |
59 | .B EPOLL_CTL_DEL | |
60 | Remove (deregister) the target file descriptor | |
61 | .I fd | |
a16ce618 | 62 | from the interest list. |
7829230a MK |
63 | The |
64 | .I event | |
f6d844a9 | 65 | argument is ignored and can be NULL (but see BUGS below). |
7829230a | 66 | .PP |
fea681da | 67 | The |
0daa9e92 | 68 | .I event |
7829230a | 69 | argument describes the object linked to the file descriptor |
fea681da MK |
70 | .IR fd . |
71 | The | |
8478ee02 | 72 | .I struct epoll_event |
e87feb33 | 73 | is defined as: |
0ffeaeae | 74 | .PP |
a08ea57c | 75 | .in +4n |
0ffeaeae | 76 | .EX |
cf0a9ace | 77 | typedef union epoll_data { |
6ebde978 MK |
78 | void *ptr; |
79 | int fd; | |
2677bc5c MK |
80 | uint32_t u32; |
81 | uint64_t u64; | |
cf0a9ace | 82 | } epoll_data_t; |
fea681da | 83 | |
cf0a9ace | 84 | struct epoll_event { |
2677bc5c | 85 | uint32_t events; /* Epoll events */ |
6ebde978 | 86 | epoll_data_t data; /* User data variable */ |
cf0a9ace | 87 | }; |
0ffeaeae | 88 | .EE |
a08ea57c | 89 | .in |
efeece04 | 90 | .PP |
fea681da MK |
91 | The |
92 | .I events | |
967631f2 MK |
93 | member is a bit mask composed by ORing together zero or more of |
94 | the following available event types: | |
fea681da MK |
95 | .TP |
96 | .B EPOLLIN | |
97 | The associated file is available for | |
98 | .BR read (2) | |
99 | operations. | |
100 | .TP | |
101 | .B EPOLLOUT | |
102 | The associated file is available for | |
103 | .BR write (2) | |
104 | operations. | |
105 | .TP | |
64d6219c | 106 | .BR EPOLLRDHUP " (since Linux 2.6.17)" |
c13182ef | 107 | Stream socket peer closed connection, |
04706fd7 | 108 | or shut down writing half of connection. |
c13182ef | 109 | (This flag is especially useful for writing simple code to detect |
04706fd7 MK |
110 | peer shutdown when using Edge Triggered monitoring.) |
111 | .TP | |
fea681da | 112 | .B EPOLLPRI |
0dea65b8 MK |
113 | There is an exceptional condition on the file descriptor. |
114 | See the discussion of | |
115 | .B POLLPRI | |
116 | in | |
117 | .BR poll (2). | |
fea681da MK |
118 | .TP |
119 | .B EPOLLERR | |
120 | Error condition happened on the associated file descriptor. | |
4258cf6d MK |
121 | This event is also reported for the write end of a pipe when the read end |
122 | has been closed. | |
3d9a2200 | 123 | .BR epoll_wait (2) |
25c2dd2f | 124 | will always report for this event; it is not necessary to set it in |
3d9a2200 | 125 | .IR events . |
fea681da MK |
126 | .TP |
127 | .B EPOLLHUP | |
128 | Hang up happened on the associated file descriptor. | |
3d9a2200 MK |
129 | .BR epoll_wait (2) |
130 | will always wait for this event; it is not necessary to set it in | |
131 | .IR events . | |
efeece04 | 132 | .IP |
ea735ea8 MK |
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. | |
fea681da MK |
137 | .TP |
138 | .B EPOLLET | |
d9bfdb9c MK |
139 | Sets the Edge Triggered behavior for the associated file descriptor. |
140 | The default behavior for | |
fea681da | 141 | .B epoll |
c13182ef MK |
142 | is Level Triggered. |
143 | See | |
2315114c | 144 | .BR epoll (7) |
704a18f0 | 145 | for more detailed information about Edge and Level Triggered event |
fea681da MK |
146 | distribution architectures. |
147 | .TP | |
64d6219c | 148 | .BR EPOLLONESHOT " (since Linux 2.6.2)" |
d9bfdb9c | 149 | Sets the one-shot behavior for the associated file descriptor. |
019934ed | 150 | This means that after an event is pulled out with |
fea681da MK |
151 | .BR epoll_wait (2) |
152 | the associated file descriptor is internally disabled and no other events | |
153 | will be reported by the | |
154 | .B epoll | |
c13182ef MK |
155 | interface. |
156 | The user must call | |
2777b1ca | 157 | .BR epoll_ctl () |
fea681da MK |
158 | with |
159 | .B EPOLL_CTL_MOD | |
3b777aff | 160 | to rearm the file descriptor with a new event mask. |
573f05ef N |
161 | .TP |
162 | .BR EPOLLWAKEUP " (since Linux 3.5)" | |
1bc86e8a | 163 | .\" commit 4d7e30d98939a0340022ccd49325a3d70f7e0238 |
573f05ef N |
164 | If |
165 | .B EPOLLONESHOT | |
166 | and | |
167 | .B EPOLLET | |
168 | are clear and the process has the | |
169 | .B CAP_BLOCK_SUSPEND | |
1bc86e8a | 170 | capability, |
573f05ef N |
171 | ensure that the system does not enter "suspend" or |
172 | "hibernate" while this event is pending or being processed. | |
1bc86e8a MK |
173 | The event is considered as being "processed" from the time |
174 | when it is returned by a call to | |
573f05ef N |
175 | .BR epoll_wait (2) |
176 | until the next call to | |
177 | .BR epoll_wait (2) | |
178 | on the same | |
179 | .BR epoll (7) | |
c835f12b N |
180 | file descriptor, |
181 | the closure of that file descriptor, | |
182 | the removal of the event file descriptor with | |
183 | .BR EPOLL_CTL_DEL , | |
184 | or the clearing of | |
185 | .B EPOLLWAKEUP | |
186 | for the event file descriptor with | |
187 | .BR EPOLL_CTL_MOD . | |
8ab32b47 | 188 | See also BUGS. |
6a6d83b2 MK |
189 | .TP |
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, | |
193 | .IR fd . | |
194 | When a wakeup event occurs and multiple epoll file descriptors | |
195 | are attached to the same target file using | |
196 | .BR EPOLLEXCLUSIVE , | |
197 | one or more of the epoll file descriptors will receive an event with | |
198 | .BR epoll_wait (2). | |
199 | The default in this scenario (when | |
200 | .BR EPOLLEXCLUSIVE | |
201 | is not set) is for all epoll file descriptors to receive an event. | |
202 | .BR EPOLLEXCLUSIVE | |
203 | is thus useful for avoiding thundering herd problems in certain scenarios. | |
efeece04 | 204 | .IP |
6a6d83b2 | 205 | If the same file descriptor is in multiple epoll instances, |
2c767761 | 206 | some with the |
6a6d83b2 | 207 | .BR EPOLLEXCLUSIVE |
7bf58d66 | 208 | flag, and others without, then events will be provided to all epoll |
6a6d83b2 MK |
209 | instances that did not specify |
210 | .BR EPOLLEXCLUSIVE , | |
211 | and at least one of the epoll instances that did specify | |
212 | .BR EPOLLEXCLUSIVE . | |
efeece04 | 213 | .IP |
6a6d83b2 MK |
214 | The following values may be specified in conjunction with |
215 | .BR EPOLLEXCLUSIVE : | |
216 | .BR EPOLLIN , | |
217 | .BR EPOLLOUT , | |
218 | .BR EPOLLWAKEUP, | |
219 | and | |
220 | .BR EPOLLET . | |
221 | .BR EPOLLHUP | |
222 | and | |
223 | .BR EPOLLERR | |
9982c065 MK |
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 | |
227 | .IR events . | |
6a6d83b2 MK |
228 | Attempts to specify other values in |
229 | .I events | |
503e3782 MK |
230 | yield the error |
231 | .BR EINVAL . | |
232 | .IP | |
6a6d83b2 MK |
233 | .B EPOLLEXCLUSIVE |
234 | may be used only in an | |
235 | .B EPOLL_CTL_ADD | |
236 | operation; attempts to employ it with | |
237 | .B EPOLL_CTL_MOD | |
238 | yield an error. | |
239 | If | |
240 | .B EPOLLEXCLUSIVE | |
370f8e34 | 241 | has been set using |
23298342 | 242 | .BR epoll_ctl (), |
6a6d83b2 MK |
243 | then a subsequent |
244 | .B EPOLL_CTL_MOD | |
245 | on the same | |
246 | .IR epfd ",\ " fd | |
247 | pair yields an error. | |
248 | A call to | |
23298342 | 249 | .BR epoll_ctl () |
6a6d83b2 MK |
250 | that specifies |
251 | .B EPOLLEXCLUSIVE | |
252 | in | |
253 | .I events | |
254 | and specifies the target file descriptor | |
255 | .I fd | |
256 | as an epoll instance will likewise fail. | |
257 | The error in all of these cases is | |
258 | .BR EINVAL . | |
47297adb | 259 | .SH RETURN VALUE |
c13182ef | 260 | When successful, |
2777b1ca | 261 | .BR epoll_ctl () |
c13182ef MK |
262 | returns zero. |
263 | When an error occurs, | |
2777b1ca | 264 | .BR epoll_ctl () |
fea681da MK |
265 | returns \-1 and |
266 | .I errno | |
267 | is set appropriately. | |
268 | .SH ERRORS | |
269 | .TP | |
270 | .B EBADF | |
fea681da | 271 | .I epfd |
2cfa66cf MK |
272 | or |
273 | .I fd | |
3d9a2200 MK |
274 | is not a valid file descriptor. |
275 | .TP | |
276 | .B EEXIST | |
277 | .I op | |
682edefb MK |
278 | was |
279 | .BR EPOLL_CTL_ADD , | |
280 | and the supplied file descriptor | |
0daa9e92 | 281 | .I fd |
a58b3360 | 282 | is already registered with this epoll instance. |
fea681da MK |
283 | .TP |
284 | .B EINVAL | |
0daa9e92 | 285 | .I epfd |
fea681da MK |
286 | is not an |
287 | .B epoll | |
3d9a2200 MK |
288 | file descriptor, |
289 | or | |
0daa9e92 | 290 | .I fd |
3d9a2200 MK |
291 | is the same as |
292 | .IR epfd , | |
293 | or the requested operation | |
fea681da MK |
294 | .I op |
295 | is not supported by this interface. | |
296 | .TP | |
6a6d83b2 MK |
297 | .B EINVAL |
298 | An invalid event type was specified along with | |
299 | .B EPOLLEXCLUSIVE | |
300 | in | |
301 | .IR events . | |
302 | .TP | |
303 | .B EINVAL | |
304 | .I op | |
305 | was | |
306 | .B EPOLL_CTL_MOD | |
307 | and | |
308 | .IR events | |
309 | included | |
310 | .BR EPOLLEXCLUSIVE . | |
311 | .TP | |
312 | .B EINVAL | |
313 | .I op | |
314 | was | |
315 | .B EPOLL_CTL_MOD | |
316 | and the | |
317 | .BR EPOLLEXCLUSIVE | |
318 | flag has previously been applied to this | |
319 | .IR epfd ",\ " fd | |
320 | pair. | |
321 | .TP | |
322 | .B EINVAL | |
323 | .BR EPOLLEXCLUSIVE | |
324 | was specified in | |
325 | .IR event | |
326 | and | |
327 | .I fd | |
328 | refers to an epoll instance. | |
329 | .TP | |
808397e3 MK |
330 | .B ELOOP |
331 | .I fd | |
332 | refers to an epoll instance and this | |
333 | .B EPOLL_CTL_ADD | |
334 | operation would result in a circular loop of epoll instances | |
335 | monitoring one another. | |
336 | .TP | |
3d9a2200 MK |
337 | .B ENOENT |
338 | .I op | |
682edefb | 339 | was |
0daa9e92 | 340 | .B EPOLL_CTL_MOD |
682edefb MK |
341 | or |
342 | .BR EPOLL_CTL_DEL , | |
343 | and | |
0daa9e92 | 344 | .I fd |