epoll_wait()

Purpose

Waits for events on an epoll instance.

Header

#include <sys/epoll.h>

Prototype

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

Parameters

• epfd: epoll instance fd.
• events: output event array.
• maxevents: number of entries in events; must be greater than 0.
• timeout: timeout in milliseconds; -1 waits forever, 0 polls immediately.

Return Value

• Success: returns the number of ready events.
• Timeout: returns 0.
• Failure: returns -1 and sets errno.

Minimal Example

struct epoll_event events[16];
int n = epoll_wait(epfd, events, 16, -1);
if (n < 0 && errno != EINTR) {
    perror("epoll_wait");
}

Common Pitfalls

• EINTR is not fatal; retry or handle shutdown logic.
• Always loop over all returned events.
• For edge-triggered mode, drain the fd until EAGAIN.

Related Topics

• Event Loop