epoll_ctl(2) - Linux 手册页

名称

epoll_ctl - epoll 文件描述符的控制接口

概要

#include <sys/epoll.h>

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

描述

此系统调用对由文件描述符 epfd 引用的 epoll(7) 实例执行控制操作。它请求对目标文件描述符 fd 执行操作 op。

op 参数的有效值是

EPOLL_CTL_ADD

将目标文件描述符 fd 注册到由文件描述符 epfd 引用的 epoll 实例，并将事件 event 与与 fd 关联的内部文件关联。

EPOLL_CTL_MOD

更改与目标文件描述符 fd 关联的事件 event。

EPOLL_CTL_DEL

从由 epfd 引用的 epoll 实例中删除（取消注册）目标文件描述符 fd。event 可以忽略并且可以为 NULL（但请参阅下面的 BUGS）。

event 参数描述与文件描述符 fd 关联的对象。struct epoll_event 的定义如下

typedef union epoll_data {
    void        *ptr;
    int          fd;
    uint32_t     u32;
    uint64_t     u64;
} epoll_data_t;

struct epoll_event {
    uint32_t     events;      /* Epoll events */
    epoll_data_t data;        /* User data variable */
};

events 成员是一个位集，使用以下可用事件类型组成

EPOLLIN

关联的文件可用于 read(2) 操作。

EPOLLOUT

关联的文件可用于 write(2) 操作。

EPOLLRDHUP (自 Linux 2.6.17 起)

流套接字对等方关闭连接，或关闭连接的写入半部分。（此标志对于使用边缘触发监控编写简单的代码以检测对等方关闭特别有用。）

EPOLLPRI

有紧急数据可用于 read(2) 操作。

EPOLLERR

关联的文件描述符上发生错误条件。epoll_wait(2) 将始终等待此事件；无需在 events 中设置它。

EPOLLHUP

关联的文件描述符上发生挂断。epoll_wait(2) 将始终等待此事件；无需在 events 中设置它。

EPOLLET

为关联的文件描述符设置边缘触发行为。epoll 的默认行为是电平触发。有关边缘和电平触发事件分发架构的更多详细信息，请参阅 epoll(7)。

EPOLLONESHOT (自 Linux 2.6.2 起)

为关联的文件描述符设置一次性行为。这意味着在通过 epoll_wait(2) 提取事件后，关联的文件描述符将在内部禁用，并且 epoll 接口将不会报告任何其他事件。用户必须使用 epoll_ctl() 和 EPOLL_CTL_MOD 重新激活文件描述符，并使用新的事件掩码。

返回值

成功时，epoll_ctl() 返回零。如果发生错误，epoll_ctl() 返回 -1，并且 errno 将被适当地设置。

错误

EBADF

epfd 或 fd 不是有效的文件描述符。

EEXIST

op 是 EPOLL_CTL_ADD，并且提供的文件描述符 fd 已经使用此 epoll 实例注册。

EINVAL

epfd 不是 epoll 文件描述符，或者 fd 与 epfd 相同，或者请求的操作 op 不受此接口支持。

ENOENT

op 是 EPOLL_CTL_MOD 或 EPOLL_CTL_DEL，并且 fd 未与此 epoll 实例注册。

ENOMEM

请求的 op 控制操作处理内存不足。

ENOSPC

在尝试将新的文件描述符注册到 epoll 实例时，遇到了 /proc/sys/fs/epoll/max_user_watches 施加的限制。有关更多详细信息，请参阅 epoll(7)。

EPERM

目标文件 fd 不支持 epoll。

版本

epoll_ctl() 已添加到内核版本 2.6 中。

符合

epoll_ctl() 是 Linux 特有的。从版本 2.3.2 开始，glibc 中提供库支持。

说明

epoll 接口支持所有支持 poll(2) 的文件描述符。

错误

在内核版本 2.6.9 之前，EPOLL_CTL_DEL 操作需要 event 中的非 NULL 指针，即使忽略此参数。从 Linux 2.6.9 开始，在使用 EPOLL_CTL_DEL 时，可以将 event 指定为 NULL。需要可移植到内核版本 2.6.9 之前的应用程序应在 event 中指定非 NULL 指针。

参见

epoll_create(2), epoll_wait(2), poll(2), epoll(7)

引用自

epoll(4)