Before we can understand epoll semantics, we must understand how the Linux kernel represents open files. There are three layers:

The key point: fd 3 and fd 4 both point to OFD #1 (after a dup()). They are two different numbers in the fd table but they reference the same underlying open file.

The critical rule

epoll monitors open file descriptions (OFDs), not file descriptor numbers. When you call epoll_ctl(EPOLL_CTL_ADD, fd, ...), the kernel records both the fd number AND a reference to the OFD it points to. The kernel watches the OFD.

An OFD is removed from the epoll interest list only when all file descriptors that reference that OFD have been closed.

This is the example from the TLPI book. It shows behavior that catches many developers off guard.

/*
 * What happens when you close fd1 after calling dup() on it,
 * then call epoll_wait()?
 *
 * Spoiler: epoll still reports fd1 as ready even though fd1 is closed!
 */

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

#define MAX_EVENTS 5

int main(void)
{
    /* Open a FIFO (assume writer exists) */
    int fd1 = open("myfifo", O_RDONLY | O_NONBLOCK);
    if (fd1 == -1) { perror("open"); exit(1); }

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

    /* Add fd1 to the interest list */
    struct epoll_event ev;
    ev.events  = EPOLLIN;
    ev.data.fd = fd1;   /* we store fd1 here as a tag */

    if (epoll_ctl(epfd, EPOLL_CTL_ADD, fd1, &ev) == -1) {
        perror("epoll_ctl"); exit(1);
    }

    /* Suppose the FIFO now has data ready (a writer wrote something) */

    /* Create a duplicate of fd1 */
    int fd2 = dup(fd1);   /* fd2 points to the SAME open file description */
    printf("fd1=%d  fd2=%d\n", fd1, fd2);

    /* Close fd1 */
    close(fd1);
    /* At this point: fd1 is closed, but fd2 still refers to the same OFD.
       The OFD is NOT removed from epoll because fd2 still holds a reference. */

    /* Now call epoll_wait */
    struct epoll_event evlist[MAX_EVENTS];
    int ready = epoll_wait(epfd, evlist, MAX_EVENTS, 1000);  /* 1 sec timeout */

    if (ready > 0) {
        /* This WILL fire, reporting fd1 as ready — even though fd1 is closed! */
        printf("Ready: %d\n", ready);
        printf("Reported fd: %d\n", evlist[0].data.fd);  /* prints original fd1 value */
        printf("BUT fd1 is already closed. Reading via fd2 instead.\n");

        /* To actually read, you must use fd2 */
        char buf[64];
        int n = read(fd2, buf, sizeof(buf) - 1);
        if (n > 0) {
            buf[n] = '\0';
            printf("Read: %s\n", buf);
        }
    }

    close(fd2);   /* NOW the OFD has zero references — removed from epoll */
    close(epfd);
    return 0;
}

When a process calls fork(), the child gets a copy of the parent’s file descriptor table. Every fd in the parent is duplicated in the child. This includes the epoll fd itself.

Since the child’s epoll fd points to the same epoll open file description as the parent’s, they share the exact same interest list and ready list.

/*
 * fork_epoll.c
 * Shows that parent and child share the epoll interest list after fork().
 *
 * Compile: gcc -o fork_epoll fork_epoll.c
 */

#include <stdio.h>
#include <stdlib.h>
#include <unistd.h>
#include <sys/epoll.h>
#include <sys/wait.h>
#include <fcntl.h>

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

    /* Open a pipe */
    int pipefd[2];
    pipe(pipefd);   /* pipefd[0]=read end, pipefd[1]=write end */

    /* Add read end to epoll */
    struct epoll_event ev;
    ev.events  = EPOLLIN;
    ev.data.fd = pipefd[0];
    epoll_ctl(epfd, EPOLL_CTL_ADD, pipefd[0], &ev);

    pid_t pid = fork();

    if (pid == 0) {
        /* CHILD */
        /* Child inherits epfd and pipefd[0].
           Both parent and child now watch the SAME pipe read-end
           through the SAME epoll instance. */

        close(pipefd[1]);  /* child does not write */

        struct epoll_event evlist[5];
        printf("Child: waiting on epoll_wait...\n");

        int ready = epoll_wait(epfd, evlist, 5, 5000);
        if (ready > 0)
            printf("Child: got event on fd %d\n", evlist[0].data.fd);
        else
            printf("Child: timeout\n");

        close(epfd);
        close(pipefd[0]);
        exit(0);

    } else {
        /* PARENT */
        close(pipefd[0]);  /* parent does not read via epoll */

        sleep(1);  /* let child reach epoll_wait */

        /* Parent writes to the pipe — child's epoll_wait will wake up */
        write(pipefd[1], "hello", 5);
        printf("Parent: wrote to pipe\n");

        close(pipefd[1]);
        wait(NULL);
    }

    close(epfd);
    return 0;
}

Practical consequence of fork() + epoll

Both parent and child can call epoll_wait() on the same epoll instance. When an event occurs, only one of them will receive it (the kernel delivers to one waiter). This is actually used in some server designs where multiple worker processes share a listening socket’s epoll instance.

However, this sharing also means: if the child closes its epfd, the parent’s interest list is still intact (because the OFD still exists). The interest list disappears only when both parent and child close their copies of epfd.

When you call epoll_create(), the kernel creates:

Because the interest list is tied to the OFD (not the fd number), if you dup() the epfd, both the original and the duplicate epfd give you access to the same interest list. You can call epoll_wait() using either.

/* Demonstrate that dup'd epfd shares the same interest list */

int epfd  = epoll_create1(0);
int epfd2 = dup(epfd);   /* duplicate the epoll fd */

/* Add a socket to the interest list using epfd */
struct epoll_event ev;
ev.events  = EPOLLIN;
ev.data.fd = sockfd;
epoll_ctl(epfd, EPOLL_CTL_ADD, sockfd, &ev);

/* Now wait using epfd2 — it sees the same interest list! */
struct epoll_event evlist[5];
int ready = epoll_wait(epfd2, evlist, 5, -1);
/* This will return when sockfd has data, even though we added it via epfd */

Similarly, you can modify or remove items from the interest list using either the original epfd or the duplicated epfd2. They are just two handles to the same underlying data structure.

The common misconception: “closing an fd removes it from epoll”. The truth is more nuanced.

/*
 * Illustrating when an OFD is truly removed from epoll
 */

int fd1 = open("myfile", O_RDONLY);

/* Add to epoll */
struct epoll_event ev = { .events = EPOLLIN, .data.fd = fd1 };
epoll_ctl(epfd, EPOLL_CTL_ADD, fd1, &ev);

/* Case 1: No dup — closing fd1 removes OFD from epoll */
close(fd1);  /* OFD refcount goes to 0 → removed from epoll */

/* ================================================================ */

int fd1 = open("myfile", O_RDONLY);
int fd2 = dup(fd1);

epoll_ctl(epfd, EPOLL_CTL_ADD, fd1, &ev);

/* Case 2: fd2 still open — closing fd1 does NOT remove OFD */
close(fd1);  /* OFD refcount drops from 2 to 1 → still in epoll */
             /* epoll_wait() can still fire for this OFD! */

/* To actually remove from epoll: first use EPOLL_CTL_DEL */
epoll_ctl(epfd, EPOLL_CTL_DEL, fd2, NULL);  /* or fd1 while still open */
close(fd2);  /* now OFD refcount = 0 */

Best practice: Always call epoll_ctl(EPOLL_CTL_DEL, ...) explicitly before closing an fd, especially in programs that use dup() or fork(). Do not rely on close() to clean up epoll entries.

This shows the recommended way to remove an fd from epoll before closing it, even when you are not using dup().

/*
 * safe_epoll_remove.c
 * Best practice: always EPOLL_CTL_DEL before closing an fd.
 *
 * Compile: gcc -o safe_epoll_remove safe_epoll_remove.c
 */

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

#define MAX_FDS    64
#define MAX_EVENTS 16

/* Wrapper to safely remove an fd from epoll and close it */
void remove_and_close(int epfd, int fd)
{
    /* Remove from epoll first */
    if (epoll_ctl(epfd, EPOLL_CTL_DEL, fd, NULL) == -1)
        perror("epoll_ctl DEL");   /* log but continue */

    /* Now close the fd */
    if (close(fd) == -1)
        perror("close");

    printf("  Removed and closed fd %d\n", fd);
}

int main(int argc, char *argv[])
{
    if (argc < 2) {
        fprintf(stderr, "Usage: %s file1 [file2 ...]\n", argv[0]);
        return 1;
    }

    int epfd = epoll_create1(EPOLL_CLOEXEC);
    if (epfd == -1) { perror("epoll_create1"); return 1; }

    int numFds = 0;

    for (int i = 1; i < argc && numFds < MAX_FDS; i++) {
        int fd = open(argv[i], O_RDONLY | O_NONBLOCK);
        if (fd == -1) { perror("open"); continue; }

        struct epoll_event ev;
        ev.events  = EPOLLIN | EPOLLHUP | EPOLLERR;
        ev.data.fd = fd;

        if (epoll_ctl(epfd, EPOLL_CTL_ADD, fd, &ev) == -1) {
            perror("epoll_ctl ADD");
            close(fd);
            continue;
        }

        printf("Watching fd %d (%s)\n", fd, argv[i]);
        numFds++;
    }

    struct epoll_event evlist[MAX_EVENTS];
    char buf[512];

    while (numFds > 0) {
        int ready = epoll_wait(epfd, evlist, MAX_EVENTS, 5000);

        if (ready == -1) {
            perror("epoll_wait");
            break;
        }
        if (ready == 0) {
            printf("Timeout — no events in 5 seconds\n");
            break;
        }

        for (int j = 0; j < ready; j++) {
            int cur_fd = evlist[j].data.fd;

            if (evlist[j].events & EPOLLIN) {
                ssize_t n = read(cur_fd, buf, sizeof(buf) - 1);
                if (n > 0) {
                    buf[n] = '\0';
                    printf("fd=%d: read %zd bytes: %s\n", cur_fd, n, buf);
                }
            }

            if (evlist[j].events & (EPOLLHUP | EPOLLERR)) {
                printf("fd=%d: hangup or error\n", cur_fd);
                remove_and_close(epfd, cur_fd);
                numFds--;
            }
        }
    }

    close(epfd);
    printf("Done.\n");
    return 0;
}