Debian Codegraph @

upstream/debian-unstable/man7/epoll.7

raw
1 .\" Copyright 2003, Davide Libenzi <[email protected]>
2 .\" Copyright, the authors of the Linux man-pages project
3 .\"
4 .\" SPDX-License-Identifier: GPL-2.0-or-later
5 .\"
6 .TH epoll 7 2026-02-08 "Linux man-pages 6.18"
7 .SH NAME
8 epoll \- I/O event notification facility
9 .SH SYNOPSIS
10 .nf
11 .B #include <sys/epoll.h>
12 .fi
13 .SH DESCRIPTION
14 The
15 .B epoll
16 API performs a similar task to
17 .BR poll (2):
18 monitoring multiple file descriptors to see if I/O is possible on any of them.
19 The
20 .B epoll
21 API can be used either as an edge-triggered or a level-triggered
22 interface and scales well to large numbers of watched file descriptors.
23 .P
24 The central concept of the
25 .B epoll
26 API is the
27 .B epoll
28 .IR instance ,
29 an in-kernel data structure which, from a user-space perspective,
30 can be considered as a container for two lists:
31 .IP \[bu] 3
32 The
33 .I interest
34 list (sometimes also called the
35 .B epoll
36 set): the set of file descriptors that the process has registered
37 an interest in monitoring.
38 .IP \[bu]
39 The
40 .I ready
41 list: the set of file descriptors that are "ready" for I/O.
42 The ready list is a subset of
43 (or, more precisely, a set of references to)
44 the file descriptors in the interest list.
45 The ready list is dynamically populated
46 by the kernel as a result of I/O activity on those file descriptors.
47 .P
48 The following system calls are provided to
49 create and manage an
50 .B epoll
51 instance:
52 .IP \[bu] 3
53 .BR epoll_create (2)
54 creates a new
55 .B epoll
56 instance and returns a file descriptor referring to that instance.
57 (The more recent
58 .BR epoll_create1 (2)
59 extends the functionality of
60 .BR epoll_create (2).)
61 .IP \[bu]
62 Interest in particular file descriptors is then registered via
63 .BR epoll_ctl (2),
64 which adds items to the interest list of the
65 .B epoll
66 instance.
67 .IP \[bu]
68 .BR epoll_wait (2)
69 waits for I/O events,
70 blocking the calling thread if no events are currently available.
71 (This system call can be thought of as fetching items from
72 the ready list of the
73 .B epoll
74 instance.)
75 .\"
76 .SS Level-triggered and edge-triggered
77 The
78 .B epoll
79 event distribution interface is able to behave both as edge-triggered
80 (ET) and as level-triggered (LT).
81 The difference between the two mechanisms
82 can be described as follows.
83 Suppose that
84 this scenario happens:
85 .IP (1) 5
86 The file descriptor that represents the read side of a pipe
87 .RI ( rfd )
88 is registered on the
89 .B epoll
90 instance.
91 .IP (2)
92 A pipe writer writes 2\ kB of data on the write side of the pipe.
93 .IP (3)
94 A call to
95 .BR epoll_wait (2)
96 is done that will return
97 .I rfd
98 as a ready file descriptor.
99 .IP (4)
100 The pipe reader reads 1\ kB of data from
101 .IR rfd .
102 .IP (5)
103 A call to
104 .BR epoll_wait (2)
105 is done.
106 .P
107 If the
108 .I rfd
109 file descriptor has been added to the
110 .B epoll
111 interface using the
112 .B EPOLLET
113 (edge-triggered)
114 flag, the call to
115 .BR epoll_wait (2)
116 done in step
117 .B 5
118 will probably hang despite the available data still present in the file
119 input buffer;
120 meanwhile the remote peer might be expecting a response based on the
121 data it already sent.
122 The reason for this is that edge-triggered mode
123 delivers events only when changes occur on the monitored file descriptor,
124 that is, an event will be generated upon each receipt of a chunk of data.
125 So, in step
126 .B 5
127 the caller might end up waiting for some data that is already present inside
128 the input buffer.
129 In the above example, an event on
130 .I rfd
131 will be generated because of the write done in
132 .B 2
133 and the event is consumed in
134 .BR 3 .
135 Since the read operation done in
136 .B 4
137 does not consume the whole buffer data, the call to
138 .BR epoll_wait (2)
139 done in step
140 .B 5
141 might block indefinitely.
142 .P
143 An application that employs the
144 .B EPOLLET
145 flag should use nonblocking file descriptors to avoid having a blocking
146 read or write starve a task that is handling multiple file descriptors.
147 The suggested way to use
148 .B epoll
149 as an edge-triggered
150 .RB ( EPOLLET )
151 interface is as follows:
152 .IP (1) 5
153 with nonblocking file descriptors;
154 and
155 .IP (2)
156 by waiting for an event only after
157 .BR read (2)
158 or
159 .BR write (2)
160 return
161 .BR EAGAIN .
162 .P
163 By contrast, when used as a level-triggered interface
164 (the default, when
165 .B EPOLLET
166 is not specified),
167 .B epoll
168 is simply a faster
169 .BR poll (2),
170 and can be used wherever the latter is used since it shares the
171 same semantics.
172 .P
173 Since even with edge-triggered
174 .BR epoll ,
175 multiple events can be generated upon receipt of multiple chunks of data,
176 the caller has the option to specify the
177 .B EPOLLONESHOT
178 flag, to tell
179 .B epoll
180 to disable the associated file descriptor after the receipt of an event with
181 .BR epoll_wait (2).
182 When the
183 .B EPOLLONESHOT
184 flag is specified,
185 it is the caller's responsibility to rearm the file descriptor using
186 .BR epoll_ctl (2)
187 with
188 .BR EPOLL_CTL_MOD .
189 .P
190 If multiple threads
191 (or processes, if child processes have inherited the
192 .B epoll
193 file descriptor across
194 .BR fork (2))
195 are blocked in
196 .BR epoll_wait (2)
197 waiting on the same epoll file descriptor and a file descriptor
198 in the interest list that is marked for edge-triggered
199 .RB ( EPOLLET )
200 notification becomes ready,
201 just one of the threads (or processes) is awoken from
202 .BR epoll_wait (2).
203 This provides a useful optimization for avoiding "thundering herd" wake-ups
204 in some scenarios.
205 .\"
206 .SS Interaction with autosleep
207 If the system is in
208 .B autosleep
209 mode via
210 .I /sys/power/autosleep
211 and an event happens which wakes the device from sleep, the device
212 driver will keep the device awake only until that event is queued.
213 To keep the device awake until the event has been processed,
214 it is necessary to use the
215 .BR epoll_ctl (2)
216 .B EPOLLWAKEUP
217 flag.
218 .P
219 When the
220 .B EPOLLWAKEUP
221 flag is set in the
222 .B events
223 field for a
224 .IR "struct epoll_event" ,
225 the system will be kept awake from the moment the event is queued,
226 through the
227 .BR epoll_wait (2)
228 call which returns the event until the subsequent
229 .BR epoll_wait (2)
230 call.
231 If the event should keep the system awake beyond that time,
232 then a separate
233 .I wake_lock
234 should be taken before the second
235 .BR epoll_wait (2)
236 call.
237 .SS /proc interfaces
238 The following interfaces can be used to limit the amount of
239 kernel memory consumed by epoll:
240 .\" Following was added in Linux 2.6.28, but them removed in Linux 2.6.29
241 .\" .TP
242 .\" .IR /proc/sys/fs/epoll/max_user_instances " (since Linux 2.6.28)"
243 .\" This specifies an upper limit on the number of epoll instances
244 .\" that can be created per real user ID.
245 .TP
246 .IR /proc/sys/fs/epoll/max_user_watches " (since Linux 2.6.28)"
247 This specifies a limit on the total number of
248 file descriptors that a user can register across
249 all epoll instances on the system.
250 The limit is per real user ID.
251 Each registered file descriptor costs roughly 90 bytes on a 32-bit kernel,
252 and roughly 160 bytes on a 64-bit kernel.
253 Currently,
254 .\" Linux 2.6.29 (in Linux 2.6.28, the default was 1/32 of lowmem)
255 the default value for
256 .I max_user_watches
257 is 1/25 (4%) of the available low memory,
258 divided by the registration cost in bytes.
259 .SS Example for suggested usage
260 While the usage of
261 .B epoll
262 when employed as a level-triggered interface does have the same
263 semantics as
264 .BR poll (2),
265 the edge-triggered usage requires more clarification to avoid stalls
266 in the application event loop.
267 In this example, listener is a
268 nonblocking socket on which
269 .BR listen (2)
270 has been called.
271 The function
272 .I do_use_fd()
273 uses the new ready file descriptor until
274 .B EAGAIN
275 is returned by either
276 .BR read (2)
277 or
278 .BR write (2).
279 An event-driven state machine application should, after having received
280 .BR EAGAIN ,
281 record its current state so that at the next call to
282 .I do_use_fd()
283 it will continue to
284 .BR read (2)
285 or
286 .BR write (2)
287 from where it stopped before.
288 .P
289 .in +4n
290 .EX
291 #define MAX_EVENTS 10
292 struct epoll_event ev, events[MAX_EVENTS];
293 int listen_sock, conn_sock, nfds, epollfd;
294 \&
295 /* Code to set up listening socket, \[aq]listen_sock\[aq],
296 (socket(), bind(), listen()) omitted. */
297 \&
298 epollfd = epoll_create1(0);
299 if (epollfd == \-1) {
300 perror("epoll_create1");
301 exit(EXIT_FAILURE);
302 }
303 \&
304 ev.events = EPOLLIN;
305 ev.data.fd = listen_sock;
306 if (epoll_ctl(epollfd, EPOLL_CTL_ADD, listen_sock, &ev) == \-1) {
307 perror("epoll_ctl: listen_sock");
308 exit(EXIT_FAILURE);
309 }
310 \&
311 for (;;) {
312 nfds = epoll_wait(epollfd, events, MAX_EVENTS, \-1);
313 if (nfds == \-1) {
314 perror("epoll_wait");
315 exit(EXIT_FAILURE);
316 }
317 \&
318 for (n = 0; n < nfds; ++n) {
319 if (events[n].data.fd == listen_sock) {
320 conn_sock = accept(listen_sock,
321 (struct sockaddr *) &addr, &addrlen);
322 if (conn_sock == \-1) {
323 perror("accept");
324 exit(EXIT_FAILURE);
325 }
326 setnonblocking(conn_sock);
327 ev.events = EPOLLIN | EPOLLET;
328 ev.data.fd = conn_sock;
329 if (epoll_ctl(epollfd, EPOLL_CTL_ADD, conn_sock,
330 &ev) == \-1) {
331 perror("epoll_ctl: conn_sock");
332 exit(EXIT_FAILURE);
333 }
334 } else {
335 do_use_fd(events[n].data.fd);
336 }
337 }
338 }
339 .EE
340 .in
341 .P
342 When used as an edge-triggered interface, for performance reasons, it is
343 possible to add the file descriptor inside the
344 .B epoll
345 interface
346 .RB ( EPOLL_CTL_ADD )
347 once by specifying
348 .RB ( EPOLLIN | EPOLLOUT ).
349 This allows you to avoid
350 continuously switching between
351 .B EPOLLIN
352 and
353 .B EPOLLOUT
354 calling
355 .BR epoll_ctl (2)
356 with
357 .BR EPOLL_CTL_MOD .
358 .SS Questions and answers
359 .IP \[bu] 3
360 What is the key used to distinguish the file descriptors registered in an
361 interest list?
362 .IP
363 The key is the combination of the file descriptor number and
364 the open file description
365 (also known as an "open file handle",
366 the kernel's internal representation of an open file).
367 .IP \[bu]
368 What happens if you register the same file descriptor on an
369 .B epoll
370 instance twice?
371 .IP
372 You will probably get
373 .BR EEXIST .
374 However, it is possible to add a duplicate
375 .RB ( dup (2),
376 .BR dup2 (2),
377 .BR fcntl (2)
378 .BR F_DUPFD )
379 file descriptor to the same
380 .B epoll
381 instance.
382 .\" But a file descriptor duplicated by fork(2) can't be added to the
383 .\" set, because the [file *, fd] pair is already in the epoll set.
384 .\" That is a somewhat ugly inconsistency. On the one hand, a child process
385 .\" cannot add the duplicate file descriptor to the epoll set. (In every
386 .\" other case that I can think of, file descriptors duplicated by fork have
387 .\" similar semantics to file descriptors duplicated by dup() and friends.) On
388 .\" the other hand, the very fact that the child has a duplicate of the
389 .\" file descriptor means that even if the parent closes its file descriptor,
390 .\" then epoll_wait() in the parent will continue to receive notifications for
391 .\" that file descriptor because of the duplicated file descriptor in the child.
392 .\"
393 .\" See http://thread.gmane.org/gmane.linux.kernel/596462/
394 .\" "epoll design problems with common fork/exec patterns"
395 .\"
396 .\" mtk, Feb 2008
397 This can be a useful technique for filtering events,
398 if the duplicate file descriptors are registered with different
399 .I events
400 masks.
401 .IP \[bu]
402 Can two
403 .B epoll
404 instances wait for the same file descriptor?
405 If so, are events reported to both
406 .B epoll
407 file descriptors?
408 .IP
409 Yes, and events would be reported to both.
410 However, careful programming may be needed to do this correctly.
411 .IP \[bu]
412 Is the
413 .B epoll
414 file descriptor itself poll/epoll/selectable?
415 .IP
416 Yes.
417 If an
418 .B epoll
419 file descriptor has events waiting, then it will
420 indicate as being readable.
421 .IP \[bu]
422 What happens if one attempts to put an
423 .B epoll
424 file descriptor into its own file descriptor set?
425 .IP
426 The
427 .BR epoll_ctl (2)
428 call fails
429 .RB ( EINVAL ).
430 However, you can add an
431 .B epoll
432 file descriptor inside another
433 .B epoll
434 file descriptor set.
435 .IP \[bu]
436 Can I send an
437 .B epoll
438 file descriptor over a UNIX domain socket to another process?
439 .IP
440 Yes, but it does not make sense to do this, since the receiving process
441 would not have copies of the file descriptors in the interest list.
442 .IP \[bu]
443 Will closing a file descriptor cause it to be removed from all
444 .B epoll
445 interest lists?
446 .IP
447 Yes, but be aware of the following point.
448 A file descriptor is a reference to an open file description (see
449 .BR open (2)).
450 Whenever a file descriptor is duplicated via
451 .BR dup (2),
452 .BR dup2 (2),
453 .BR fcntl (2)
454 .BR F_DUPFD ,
455 or
456 .BR fork (2),
457 a new file descriptor referring to the same open file description is
458 created.
459 An open file description continues to exist until all
460 file descriptors referring to it have been closed.
461 .IP
462 A file descriptor is removed from an
463 interest list only after all the file descriptors referring to the underlying
464 open file description have been closed.
465 This means that even after a file descriptor that is part of an
466 interest list has been closed,
467 events may be reported for that file descriptor if other file
468 descriptors referring to the same underlying file description remain open.
469 To prevent this happening,
470 the file descriptor must be explicitly removed from the interest list (using
471 .BR epoll_ctl (2)
472 .BR EPOLL_CTL_DEL )
473 before it is duplicated.
474 Alternatively,
475 the application must ensure that all file descriptors are closed
476 (which may be difficult if file descriptors were duplicated
477 behind the scenes by library functions that used
478 .BR dup (2)
479 or
480 .BR fork (2)).
481 .IP \[bu]
482 If more than one event occurs between
483 .BR epoll_wait (2)
484 calls, are they combined or reported separately?
485 .IP
486 They will be combined.
487 .IP \[bu]
488 Does an operation on a file descriptor affect the
489 already collected but not yet reported events?
490 .IP
491 You can do two operations on an existing file descriptor.
492 Remove would be meaningless for
493 this case.
494 Modify will reread available I/O.
495 .IP \[bu]
496 Do I need to continuously read/write a file descriptor
497 until
498 .B EAGAIN
499 when using the
500 .B EPOLLET
501 flag (edge-triggered behavior)?
502 .IP
503 Receiving an event from
504 .BR epoll_wait (2)
505 should suggest to you that such
506 file descriptor is ready for the requested I/O operation.
507 You must consider it ready until the next (nonblocking)
508 read/write yields
509 .BR EAGAIN .
510 When and how you will use the file descriptor is entirely up to you.
511 .IP
512 For packet/token-oriented files (e.g., datagram socket,
513 terminal in canonical mode),
514 the only way to detect the end of the read/write I/O space
515 is to continue to read/write until
516 .BR EAGAIN .
517 .IP
518 For stream-oriented files (e.g., pipe, FIFO, stream socket), the
519 condition that the read/write I/O space is exhausted can also be detected by
520 checking the amount of data read from / written to the target file
521 descriptor.
522 For example, if you call
523 .BR read (2)
524 by asking to read a certain amount of data and
525 .BR read (2)
526 returns a lower number of bytes, you
527 can be sure of having exhausted the read I/O space for the file
528 descriptor.
529 The same is true when writing using
530 .BR write (2).
531 (Avoid this latter technique if you cannot guarantee that
532 the monitored file descriptor always refers to a stream-oriented file.)
533 .SS Possible pitfalls and ways to avoid them
534 .IP \[bu] 3
535 .B Starvation (edge-triggered)
536 .IP
537 If there is a large amount of I/O space,
538 it is possible that by trying to drain
539 it the other files will not get processed causing starvation.
540 (This problem is not specific to
541 .BR epoll .)
542 .IP
543 The solution is to maintain a ready list
544 and mark the file descriptor as ready
545 in its associated data structure, thereby allowing the application to
546 remember which files need to be processed but still round robin amongst
547 all the ready files.
548 This also supports ignoring subsequent events you
549 receive for file descriptors that are already ready.
550 .IP \[bu]
551 .B If using an event cache...
552 .IP
553 If you use an event cache or store all the file descriptors returned from
554 .BR epoll_wait (2),
555 then make sure to provide a way to mark
556 its closure dynamically (i.e., caused by
557 a previous event's processing).
558 Suppose you receive 100 events from
559 .BR epoll_wait (2),
560 and in event #47 a condition causes event #13 to be closed.
561 If you remove the structure and
562 .BR close (2)
563 the file descriptor for event #13, then your
564 event cache might still say there are events waiting for that
565 file descriptor causing confusion.
566 .IP
567 One solution for this is to call, during the processing of event 47,
568 .BR epoll_ctl ( EPOLL_CTL_DEL )
569 to delete file descriptor 13 and
570 .BR close (2),
571 then mark its associated
572 data structure as removed and link it to a cleanup list.
573 If you find another
574 event for file descriptor 13 in your batch processing,
575 you will discover the file descriptor had been
576 previously removed and there will be no confusion.
577 .SH VERSIONS
578 Some other systems provide similar mechanisms;
579 for example,
580 FreeBSD has
581 .IR kqueue ,
582 and Solaris has
583 .IR /dev/poll .
584 .SH STANDARDS
585 Linux.
586 .SH HISTORY
587 Linux 2.5.44.
588 .\" Its interface should be finalized in Linux 2.5.66.
589 glibc 2.3.2.
590 .SH NOTES
591 The set of file descriptors that is being monitored via
592 an epoll file descriptor can be viewed via the entry for
593 the epoll file descriptor in the process's
594 .IR /proc/ pid /fdinfo
595 directory.
596 See
597 .BR proc (5)
598 for further details.
599 .P
600 The
601 .BR kcmp (2)
602 .B KCMP_EPOLL_TFD
603 operation can be used to test whether a file descriptor
604 is present in an epoll instance.
605 .SH SEE ALSO
606 .BR epoll_create (2),
607 .BR epoll_create1 (2),
608 .BR epoll_ctl (2),
609 .BR epoll_wait (2),
610 .BR ioctl_eventpoll (2),
611 .BR poll (2),
612 .BR select (2)