poll(2)

poll(2) poll(2) is a POSIX-compatible system call and library interface for I/O multiplexing that allows a process to wait for events on multiple file descriptors. It provides a level-triggered, scalable alternative to older interfaces and is used in networking stacks, event-driven servers, and asynchronous frameworks across UNIX-like systems. Implementations differ between kernels and libc packages, and portability concerns involve standards like POSIX and the Single UNIX Specification.

Name and synopsis

The name and synopsis of the interface appear in standards and manual collections maintained by organizations such as POSIX, The Open Group, and implementations from GNU Project, NetBSD, FreeBSD, and Linux kernel. The typical C prototype is declared in headers provided by GNU C Library and other libc implementations; programs using poll often include symbols from unistd.h and poll.h when compiled with toolchains such as GCC or Clang. Shell-level documentation and manpages produced by projects like Debian and Red Hat distribute normative usage examples for administrators and developers.

Description

poll provides an array-based mechanism where each element associates a file descriptor with requested event masks and returned event indicators; applications commonly use it in servers developed by teams at Facebook, Google, Twitter, and Netflix to manage sockets and pipes. The interface scales differently from alternatives such as select(2) and edge-triggered facilities like epoll(7) and kqueue(2), and is discussed in literature from USENIX, ACM SIGCOMM, and textbooks by authors such as W. Richard Stevens and Michael Kerrisk. It supports waiting for readiness to read, readiness to write, and exceptional conditions on resources provided by implementations in Linux kernel networking and VFS subsystems, and is used in frameworks like libevent, libuv, Node.js, and libuv-based runtimes.

Flags and return values

Requested events are set using symbolic flags defined in headers originating from projects like POSIX and GNU Project; common flags include POLLIN, POLLOUT, and POLLERR, which are interpreted by kernels from NetBSD, OpenBSD, FreeBSD, and Linux kernel to signal readiness or errors on descriptors such as sockets created via socket(2) or pipes created via pipe(2). The function returns a count of descriptors with nonzero event fields on success, 0 on timeout, and -1 with errno set on error; errno values may include codes standardized by POSIX and defined in libc implementations like musl libc and GNU C Library. Certain flags and return semantics interact with nonblocking I/O models used in servers at Nginx and Apache HTTP Server, and with file descriptor operations defined by fcntl(2).

Examples

Common examples appear in documentation and source trees maintained by projects like GitLab, GitHub, and vendor distributions such as Ubuntu and CentOS. Typical usage shows constructing an array of pollfd structures, setting events for descriptors obtained from accept(2) or connect(2), calling poll with a timeout measured in milliseconds, and then handling POLLIN/POLLOUT results to perform read(2) or write(2) operations. Event loops in stacks used by OpenSSH, Postfix, Sendmail, and Dovecot illustrate practical patterns, and sample code appears in tutorials affiliated with Linux Foundation training and university courses from institutions like MIT and Stanford.

Standards and portability

poll is specified by POSIX and referenced by the Single UNIX Specification; portability notes appear in portability guides from The Open Group and in compatibility layers implemented by projects like Cygwin and WSL. Behavior differences across Linux kernel, FreeBSD, NetBSD, and Solaris include handling of file descriptor ranges, support for large descriptor values, and exact semantics for edge versus level notifications, which are documented in manpages packaged by Debian maintainers and clarified in standards discussions involving IEEE working groups. Language bindings in Python, Ruby, Perl, and Java adapt the interface to runtime libraries maintained by projects such as CPython and OpenJDK.

Implementation and kernel interaction

Kernel-side implementations within the Linux kernel and BSD families implement poll by mapping user-space pollfd arrays into kernel structures and registering interest with scheduler and I/O subsystems; drivers for network stacks such as Netfilter or storage subsystems for NVMe devices expose readiness through the kernel's wait queues and event notification layers. The interaction with asynchronous I/O subsystems used by io_uring and traditional event mechanisms such as select(2) and epoll(7) is relevant for high-performance servers like HAProxy and Lighttpd. Implementations in embedded or unikernel projects such as FreeRTOS ports and seL4-based systems either emulate poll in libc or provide alternative primitives suited to constrained environments.

Security and corner cases

Security considerations include race conditions and descriptor reuse issues documented in advisories from organizations like CVE trackers and mitigations recommended by projects such as OpenSSL and GnuTLS when integrating network I/O. Corner cases include handling of invalid file descriptors, POLLHUP and POLLERR semantics when peers close sockets abruptly as seen in bugs reported in Git and kernel.org issue trackers, and behavior under heavy load or malicious input that may trigger descriptor exhaustion or denial-of-service conditions observed in services run by Amazon Web Services and Cloudflare. Hardened deployments reference guidance from CERT Coordination Center and use sandboxing approaches provided by SELinux and AppArmor to limit impact of misuse.

Category:Unix system calls