Epoll

Linux-specific system call for a scalable I/O event notification mechanism

`epoll` is a Linux kernel system call for a scalable I/O event notification mechanism, first introduced in version 2.5.45 of the Linux kernel.[1][failed verification – see discussion] Its function is to monitor multiple file descriptors to see whether I/O is possible on any of them. It is meant to replace the older POSIX `select(2)` and `poll(2)` system calls, to achieve better performance in more demanding applications, where the number of watched file descriptors is large (unlike the older system calls, which operate in O(n) time, `epoll` operates in O(1) time).[2]

`epoll` is similar to FreeBSD's `kqueue`, in that it consists of a set of user-space functions, each taking a file descriptor argument denoting the configurable kernel object, against which they cooperatively operate. `epoll` uses a red–black tree (RB-tree) data structure to keep track of all file descriptors that are currently being monitored.[3]

## API

[edit]

int epoll_create1(int flags);

Creates an `epoll` object and returns its file descriptor. The `flags` parameter allows epoll behavior to be modified. It has only one valid value, `EPOLL_CLOEXEC`. `epoll_create()` is an older variant of `epoll_create1()` and is deprecated as of Linux kernel version 2.6.27 and glibc version 2.9.[4]

int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);

Controls (configures) which file descriptors are watched by this object, and for which events. `op` can be ADD, MODIFY or DELETE.

int epoll_wait(int epfd, struct epoll_event *events, int maxevents, int timeout);

Waits for any of the events registered for with `epoll_ctl`, until at least one occurs or the timeout elapses. Returns the occurred events in `events`, up to `maxevents` at once. `maxevents` is the maximum number of `epoll_event`/file descriptors to be monitored.[5][6] In most case, `maxevents` is set to the value of the size of `*events` argument (`struct epoll_event *events` array).

## Triggering modes

[edit]

`epoll` provides both edge-triggered and level-triggered modes. In edge-triggered mode, a call to `epoll_wait` will return only when a new event is enqueued with the `epoll` object, while in level-triggered mode, `epoll_wait` will return as long as the condition holds.

For instance, if a pipe registered with `epoll` has received data, a call to `epoll_wait` will return, signaling the presence of data to be read. Suppose, the reader only consumed part of data from the buffer. In level-triggered mode, further calls to `epoll_wait` will return immediately, as long as the pipe's buffer contains data to be read. In edge-triggered mode, however, `epoll_wait` will return only once new data is written to the pipe.[1]

## Bugs

[edit]

Bryan Cantrill pointed out that `epoll` had mistakes that could have been avoided, had it learned from its predecessors: input/output completion ports, event ports (Solaris) and kqueue.[7] However, a large part of his criticism was addressed by `epoll`'s `EPOLLONESHOT` and `EPOLLEXCLUSIVE` options. `EPOLLONESHOT` was added in version 2.6.2 of the Linux kernel mainline, released in February 2004. `EPOLLEXCLUSIVE` was added in version 4.5, released in March 2016.[8]

## See also

[edit]

* Linux portal

* Input/output completion port (IOCP)
* kqueue
* libevent

## References

[edit]

1. ^ a b "epoll(7) - Linux manual page". Man7.org. 2012-04-17. Retrieved 2014-03-01.
2. ^ Oleksiy Kovyrin (2006-04-13). "Using epoll() For Asynchronous Network Programming". Kovyrin.net. Retrieved 2014-03-01.
3. ^ "The Implementation of epoll (1)". idndx.com. September 2014.
4. ^ Love, Robert (2013). Linux System Programming (Second ed.). O’Reilly. pp. 97, 98. ISBN 978-1-449-33953-1.
5. ^ "epoll_wait: maxevents". Jun 3, 2010. Retrieved 2023-07-06.
6. ^ "epoll_wait(2) — Linux manual page". 2023-03-30. Retrieved 2023-07-06.
7. ^ Archived at Ghostarchive and the Wayback Machine: "Ubuntu Slaughters Kittens | BSD Now 103". YouTube. 20 August 2015.
8. ^ "Epoll is fundamentally broken 1/2". idea.popcount.org. 2017-02-20. Retrieved 2017-10-06.

## External links

[edit]

* epoll manpage
* epoll patch

* v
* t
* e

Linux kernel

Organization|

| Kernel|

* Linux Foundation
* Linux Mark Institute
* Linus's law
* Tanenbaum–Torvalds debate
* Tux
* SCO disputes
* Linaro
* GNU GPL v2
* menuconfig
* Supported computer architectures
* Version history
* Criticism

|

Support|

* Developers
* The Linux Programming Interface
* kernel.org
* LKML
* Linux conferences
* Users
* Linux User Group (LUG)

People|

* Werner Almesberger
* H. Peter Anvin
* Jens Axboe
* Moshe Bar
* Suparna Bhattacharya
* Andries Brouwer
* Rémy Card
* Alan Cox
* Matthew Garrett
* Avi Kivity
* Con Kolivas
* Greg Kroah-Hartman
* Benson Leung
* Robert Love
* David S. Miller
* Ingo Molnár
* Andrew Morton
* Hans Reiser
* Rusty Russell
* Shuah Khan
* Linus Torvalds
* Theodore Ts'o
* Stephen Tweedie
* Harald Welte
* Chris Wright

Technical|

| Debugging|

* CRIU
* ftrace
* kdump
* Linux kernel oops
* SystemTap
* BPF

|

Startup|

* vmlinux
* System.map
* dracut
* initrd
* initramfs

ABIs|

* Linux Standard Base
* x32 ABI

APIs|

| Kernel|

| System Call
Interface|

* POSIX
* ioctl
* select
* open
* read
* close
* sync
* …
* Linux-only
* futex
* epoll
* splice
* dnotify
* inotify
* readahead
* …

|

In-kernel|

* ALSA
* Crypto API
* io uring
* DRM
* kernfs
* Memory barrier
* New API
* RCU
* Video4Linux
* IIO

Userspace|

| Daemons,
File systems|

* bpffs
* configfs
* devfs
* devpts
* debugfs
* FUSE
* hugetlbfs
* pipefs
* procfs
* securityfs
* sockfs
* sysfs
* tmpfs
* systemd
* udev
* Kmscon
* binfmt_misc

|

Wrapper
libraries|

* C standard library
* glibc
* uClibc
* Bionic
* libhybris
* dietlibc
* EGLIBC
* klibc
* musl
* Newlib
* libcgroup
* libdrm
* libalsa
* libevdev
* libusb
* liburing

Components|

* Kernel modules
* BlueZ
* cgroups
* Console
* bcache
* Device mapper
* dm-cache
* dm-crypt
* DRM
* EDAC
* evdev
* Kernel same-page merging (KSM)
* LIO
* Framebuffer
* LVM
* KMS driver
* Netfilter
* Netlink
* nftables
* Network scheduler
* perf
* SLUB
* zram
* zswap

* Process and I/O schedulers:
* Brain Fuck Scheduler
* Completely Fair Scheduler (CFS)
* Earliest eligible virtual deadline first (EEVDF)
* Noop scheduler
* O(n) scheduler
* O(1) scheduler
* SCHED_DEADLINE
* SCHED_FIFO
* SCHED_RR

* Security Modules: AppArmor
* Exec Shield
* seccomp
* SELinux
* Smack
* Tomoyo Linux
* Linux PAM

* Device drivers
* 802.11
* graphics
* Raw device

* initramfs
* KernelCare
* kexec
* kGraft
* kpatch
* Ksplice

Variants|

* Mainline
* Linux kernel
* Linux-libre
* High-performance computing
* INK
* Compute Node Linux
* SLURM
* Real-time computing
* RTLinux
* RTAI
* Xenomai
* PREEMPT_RT
* MMU-less
* μClinux
* PSXLinux

| Virtualization|

* Hypervisor
* KVM
* Xen
* OS-level virtualization
* Linux-VServer
* Lguest
* LXC
* OpenVZ
* Other
* L4Linux
* User-mode Linux
* MkLinux
* coLinux

|

Adoption|

| Range
of use|

* Desktop
* Embedded
* Gaming
* Thin client:
* LTSP
* Server:
* LAMP
* LYME-LYCE
* Devices

|

Adopters|

* List of Linux adopters

* Linux portal
* Free and open-source software portal
* Category

*[v]: View this template
*[t]: Discuss this template
*[e]: Edit this template