epoll_ctl 是 Linux 系统中 I/O 多路复用机制 epoll 的核心函数之一，用于管理 epoll 实例监控的文件描述符（File Descriptor, FD）。它负责向 epoll 实例注册、修改或删除需要监控的 FD 及其事件类型，是实现高性能网络编程（如高并发服务器）的关键工具。

---

函数原型

#include <sys/epoll.h>int epoll_ctl(int epfd, int op, int fd, struct epoll_event *event);

参数说明

参数	说明
epfd	epoll 实例的文件描述符（由 epoll_create 创建）
op	操作类型：EPOLL_CTL_ADD（添加）、EPOLL_CTL_MOD（修改）、EPOLL_CTL_DEL（删除）
fd	需要操作的目标文件描述符（如 socket）
event	指向 epoll_event 结构体的指针，定义监控的事件类型和用户数据

返回值

• 成功返回 0，失败返回 -1，错误信息通过 errno 获取。

---

epoll_event 结构体

struct epoll_event {uint32_t     events;   // 监控的事件类型（位掩码形式）epoll_data_t data;     // 用户数据（通常保存 FD 或关联的指针）
};typedef union epoll_data {void    *ptr;int      fd;uint32_t u32;uint64_t u64;
} epoll_data_t;

常用事件类型

事件类型	说明
EPOLLIN	文件描述符可读（例如 socket 接收缓冲区有数据）
EPOLLOUT	文件描述符可写（例如 socket 发送缓冲区有空闲）
EPOLLERR	发生错误（自动监控，无需显式设置）
EPOLLHUP	对端关闭连接或挂起（自动监控）
EPOLLET	边缘触发模式（Edge-Triggered），默认为水平触发（Level-Triggered）

---

使用场景案例：TCP 服务器监控 Socket

以下是一个简化的 TCP 服务器代码片段，展示 epoll_ctl 的典型用法：

1. 创建 epoll 实例

int epfd = epoll_create1(0);  // 创建 epoll 实例
if (epfd == -1) {perror("epoll_create1");exit(EXIT_FAILURE);
}

2. 注册监听 Socket 到 epoll

int listen_sock = socket(AF_INET, SOCK_STREAM, 0);  // 创建监听 socket
struct sockaddr_in addr = {/* 绑定 IP 和端口 */};
bind(listen_sock, (struct sockaddr*)&addr, sizeof(addr));
listen(listen_sock, SOMAXCONN);  // 开始监听// 定义 epoll_event 结构体
struct epoll_event ev;
ev.events = EPOLLIN | EPOLLET;  // 监控可读事件，边缘触发模式
ev.data.fd = listen_sock;       // 保存 socket FD 到用户数据// 将监听 socket 添加到 epoll
if (epoll_ctl(epfd, EPOLL_CTL_ADD, listen_sock, &ev) == -1) {perror("epoll_ctl: listen_sock");close(epfd);exit(EXIT_FAILURE);
}

3. 事件循环处理新连接

#define MAX_EVENTS 10
struct epoll_event events[MAX_EVENTS];while (1) {int n = epoll_wait(epfd, events, MAX_EVENTS, -1);  // 阻塞等待事件for (int i = 0; i < n; i++) {if (events[i].data.fd == listen_sock) {// 接受新连接int conn_sock = accept(listen_sock, NULL, NULL);if (conn_sock == -1) {perror("accept");continue;}// 将新连接的 socket 添加到 epollstruct epoll_event ev_conn;ev_conn.events = EPOLLIN | EPOLLET;  // 监控可读事件ev_conn.data.fd = conn_sock;if (epoll_ctl(epfd, EPOLL_CTL_ADD, conn_sock, &ev_conn) == -1) {perror("epoll_ctl: conn_sock");close(conn_sock);}} else {// 处理已连接的 socket 数据int conn_fd = events[i].data.fd;char buffer[1024];ssize_t n = read(conn_fd, buffer, sizeof(buffer));if (n > 0) {// 处理数据...} else if (n == 0 || errno == ECONNRESET) {// 对端关闭连接，从 epoll 中删除epoll_ctl(epfd, EPOLL_CTL_DEL, conn_fd, NULL);close(conn_fd);}}}
}

---

关键注意事项

1. 边缘触发（ET） vs 水平触发（LT）：

   • ET 模式：仅在 FD 状态变化时触发事件（需一次处理完所有数据，避免饥饿）。
   • LT 模式（默认）：只要满足条件，持续触发事件（编程更简单，但效率可能略低）。

2. 错误处理：

   • 检查 epoll_ctl 返回值，避免遗漏错误（如重复添加 FD 或操作已关闭的 FD）。

3. 资源管理：

   • 关闭 FD 前需从 epoll 中删除（EPOLL_CTL_DEL），否则可能导致未定义行为。

4. 高性能优化：

   • 结合非阻塞 IO 和 ET 模式实现高并发（例如 Nginx、Redis 的做法）。

---

总结

epoll_ctl 是 epoll 机制的核心函数，用于动态管理监控的 FD。通过合理使用 EPOLL_CTL_ADD、EPOLL_CTL_MOD 和 EPOLL_CTL_DEL 操作，可以实现高效的事件驱动网络编程，支撑数万甚至百万级的并发连接。