epoll_ctl()

Purpose

Adds, modifies, or removes a file descriptor from an epoll interest list.

Header

#include <sys/epoll.h>

Prototype

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

Parameters

• epfd: epoll instance fd.
• op: EPOLL_CTL_ADD, EPOLL_CTL_MOD, or EPOLL_CTL_DEL.
• fd: target fd to monitor.
• event: event mask and user data. Use NULL for EPOLL_CTL_DEL on Linux.

Return Value

• Success: returns 0.
• Failure: returns -1 and sets errno.

Minimal Example

struct epoll_event ev = {0};
ev.events = EPOLLIN;
ev.data.fd = fd;

if (epoll_ctl(epfd, EPOLL_CTL_ADD, fd, &ev) < 0) {
    perror("epoll_ctl");
}

Common Pitfalls

• Do not forget to initialize struct epoll_event.
• Use EPOLL_CTL_MOD instead of adding the same fd twice.
• Handle EPOLLERR and EPOLLHUP even if they are not explicitly requested.

Related Topics

• Event Loop