epollevent

epollevent, more commonly referred to as epoll_event, is a structure used with the Linux epoll API to describe a file descriptor and the events being monitored or returned. It plays a central role in the scalable, event-driven I/O model provided by epoll, suitable for handling many concurrent connections.

The canonical definition in the Linux headers is struct epoll_event { uint32_t events; epoll_data_t data; }; where events is a bit mask of requested or observed events (for example EPOLLIN, EPOLLOUT, EPOLLET, EPOLLERR, EPOLLHUP), and data is a user-defined payload. epoll_data_t is a union that can hold a pointer, a file descriptor, or a 64-bit value, allowing a program to associate a context with each monitored descriptor.

Usage flow typically involves creating an epoll instance with epoll_create or epoll_create1, then adding file descriptors via epoll_ctl with EPOLL_CTL_ADD, or modifying or removing them with EPOLL_CTL_MOD and EPOLL_CTL_DEL. Before calling epoll_ctl, a struct epoll_event is prepared: its events field specifies which conditions to monitor, and its data field stores a pointer or identifier for the associated object. The program then waits for events using epoll_wait, which fills an array of epoll_event structures with ready events. Each returned event provides both the events mask and the data payload for context.

epoll is Linux-specific and designed to be more scalable than poll or select, especially for large numbers of fds. It supports edge-triggered and level-triggered modes and is optimized to reduce system calls and wakeups. The term epollevent is not a formal API name; the formal type is epoll_event, defined in sys/epoll.h.