EPOLLCTLADD

EPOLL_CTL_ADD is a command used with the epoll_ctl system call to register a new file descriptor with an epoll instance so the application can monitor events on that descriptor.

Prototype and purpose: int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event); when op is EPOLL_CTL_ADD, the function adds the specified file descriptor (fd) to the interest list of the epoll instance identified by epfd. The event pointer references a struct epoll_event that describes the events to monitor and can carry user data.

Event structure and usage: struct epoll_event includes a field events, a bitmask of event types (for example EPOLLIN, EPOLLOUT, EPOLLERR, EPOLLHUP) and the data field, which can store user data either as data.ptr or data.fd. It is common to set data.ptr to point to a per-connection state object and use data.fd when you simply want the file descriptor value. The events field may also include edge-triggered EPOLLET behavior if desired.

Notes on behavior and constraints: If the fd is already registered with the epoll instance, EPOLL_CTL_ADD will fail with EEXIST; in that case use EPOLL_CTL_MOD to modify the existing registration or EPOLL_CTL_DEL to remove it. The target file descriptor should remain valid while registered. While non-blocking mode is commonly used for sockets in an epoll loop, it is not a requirement of EPOLL_CTL_ADD itself. When closing a descriptor, it is typical to remove it from epoll with EPOLL_CTL_DEL before closing to avoid stale references. Return value is 0 on success; on error, -1 is returned and errno is set (for example EEXIST, EINVAL, EBADF, ENOMEM).