#include <sys/epoll.h>

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

/* Returns:
   - number of ready fds (>0) on success
   - 0 if timeout expired before any event
   - -1 on error (check errno)
*/

You allocate the evlist array yourself. The kernel fills it with ready events. Each entry in evlist is an epoll_event struct:

• evlist[i].events — which events occurred (EPOLLIN, EPOLLHUP, etc.)
• evlist[i].data — the user data you set when calling epoll_ctl()

Important: The data field in each returned event is the same value you stored when calling epoll_ctl(). This is how you know which fd fired — epoll does not give you the fd directly, only your stored data.

These are the bit values used in ev.events when calling epoll_ctl(), and returned in evlist[i].events by epoll_wait(). They mirror the poll() event bits with an “E” prefix added.

Note: EPOLLERR and EPOLLHUP are always monitored by the kernel even if you don’t set them. You do not need to add them when calling epoll_ctl(). You should still check for them in your event loop.

By default, once you register an fd with EPOLL_CTL_ADD, epoll keeps notifying you every time it becomes ready. Sometimes you want to be notified only once — process the event, then decide if you want to watch again. That is what EPOLLONESHOT does.

/* Register fd with EPOLLONESHOT */
ev.events  = EPOLLIN | EPOLLONESHOT;
ev.data.fd = sockfd;
epoll_ctl(epfd, EPOLL_CTL_ADD, sockfd, &ev);

/* After handling the event, re-arm it */
ev.events  = EPOLLIN | EPOLLONESHOT;
ev.data.fd = sockfd;
epoll_ctl(epfd, EPOLL_CTL_MOD, sockfd, &ev);
/* Use MOD, not ADD — the fd is still in the list */

EPOLLONESHOT is very useful in multi-threaded servers: once a thread picks up an event, you disable that fd so no other thread accidentally processes the same connection simultaneously.

One key strength of epoll over select/poll is thread safety. In a multithreaded server:

• One thread can call epoll_wait() while another thread calls epoll_ctl() to add new fds
• Changes to the interest list take effect immediately — epoll_wait() in the other thread sees them right away
• This is the foundation for the “one epoll, many worker threads” server design pattern

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <string.h>
#include <errno.h>
#include <sys/epoll.h>

#define MAX_EVENTS  10
#define BUF_SIZE   256

int main(void)
{
    int epfd, nready, i, fd;
    struct epoll_event ev, evlist[MAX_EVENTS];
    char buf[BUF_SIZE];

    /* Create epoll instance */
    epfd = epoll_create1(0);
    if (epfd == -1) { perror("epoll_create1"); exit(1); }

    /* Watch stdin (fd=0) for incoming data */
    ev.events  = EPOLLIN;
    ev.data.fd = 0;
    if (epoll_ctl(epfd, EPOLL_CTL_ADD, 0, &ev) == -1) {
        perror("epoll_ctl"); exit(1);
    }

    printf("Watching stdin. Type something and press Enter.\n");
    printf("Press Ctrl+D to quit.\n\n");

    for (;;) {
        /* Block until at least one event (timeout=-1 means forever) */
        nready = epoll_wait(epfd, evlist, MAX_EVENTS, -1);
        if (nready == -1) {
            if (errno == EINTR)
                continue;    /* interrupted by signal, retry */
            perror("epoll_wait");
            exit(1);
        }

        /* Process each ready fd */
        for (i = 0; i < nready; i++) {

            fd = evlist[i].data.fd;

            if (evlist[i].events & EPOLLIN) {
                ssize_t n = read(fd, buf, BUF_SIZE - 1);
                if (n <= 0) {
                    /* EOF or error */
                    printf("EOF on fd %d, removing\n", fd);
                    epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL);
                } else {
                    buf[n] = '\0';
                    printf("Read from fd %d: %s", fd, buf);
                }
            }

            if (evlist[i].events & (EPOLLHUP | EPOLLERR)) {
                printf("HUP/ERR on fd %d\n", fd);
                epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL);
                close(fd);
            }
        }
    }

    close(epfd);
    return 0;
}

Compile: gcc epoll_wait_demo.c -o epoll_wait_demo && ./epoll_wait_demo