man7/epoll.7

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