Linux程序员手册 第2部分
更新日期： 2020-04-11

名称

epoll_wait，epoll_pwait-等待epoll文件描述符上的I / O事件

语法

#include <sys/epoll.h>

int epoll_wait(int epfd, struct epoll_event *events,
               int maxevents, int timeout);
int epoll_pwait(int epfd, struct epoll_event *events,
               int maxevents, int timeout,
               const sigset_t *sigmask);

说明

epoll_wait()系统调用在文件描述符epfd引用的epoll(7)实例上等待事件。事件所指向的缓冲区用于从就绪列表中返回有关兴趣列表中具有某些可用事件的文件描述符的信息。 epoll_wait()最多返回最大事件。 maxevents参数必须大于零。

timeout参数指定epoll_wait()将阻止的毫秒数。时间是根据CLOCK_MONOTONIC时钟测量的。

对epoll_wait()的调用将阻塞，直到发生以下任何一种情况：

*

文件描述符传递一个事件；

*

呼叫被信号处理器中断；要么

*

超时到期。

请注意，超时间隔将四舍五入为系统时钟的粒度，内核调度延迟意味着阻塞间隔可能会少量溢出。将超时指定为-1将导致epoll_wait()无限期阻塞，而将超时指定为零将导致epoll_wait()立即返回，即使没有可用事件。

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 */
};

每个返回的epoll_event结构的数据字段包含的数据与相应打开文件描述符对epoll_ctl(2)的最新调用中指定的数据相同(EPOLL_CTL_ADD，EPOLL_CTL_MOD)。

事件字段是一个位掩码，指示相应的打开文件描述中已发生的事件。有关此掩码中可能出现的位的列表，请参见epoll_ctl(2)。

epoll_pwait()

epoll_wait()和epoll_pwait()之间的关系类似于select(2)和pselect(2)之间的关系：像pselect(2)一样，epoll_pwait()允许应用程序安全地等待，直到文件描述符准备就绪或直到信号被捕获。

以下epoll_pwait()调用：

ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);

等效于原子执行以下调用：

sigset_t origmask;

pthread_sigmask(SIG_SETMASK, &sigmask, &origmask);
ready = epoll_wait(epfd, &events, maxevents, timeout);
pthread_sigmask(SIG_SETMASK, &origmask, NULL);

sigmask参数可以指定为NULL，在这种情况下epoll_pwait()等同于epoll_wait()。

返回值

成功时，epoll_wait()返回为请求的I / O准备就绪的文件描述符的数量；如果在请求的超时毫秒内没有文件描述符准备就绪，则返回零。发生错误时，epoll_wait()返回-1并正确设置errno。

错误说明

EBADF

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

EFAULT

使用写入权限无法访问事件指向的存储区。

EINTR

在(1)任何请求的事件发生或(2)超时到期之前，信号处理程序中断了该调用。参见signal(7)。

EINVAL

epfd不是epoll文件描述符，或者maxevents小于或等于零。

版本

epoll_wait()已在2.6版中添加到内核中。从版本2.3.2开始，glibc提供了库支持。

epoll_pwait()已添加到内核2.6.19中的Linux中。从2.6版开始，glibc中提供了库支持。

遵循规范

epoll_wait()是特定于Linux的。

备注

当一个线程在对epoll_wait()的调用中被阻塞时，另一个线程有可能向等待的epoll实例添加文件描述符。如果新文件描述符准备就绪，它将导致epoll_wait()调用解除阻塞。

如果在调用epoll_wait()时已准备好多个maxevents文件描述符，则连续的epoll_wait()调用将在准备好的文件描述符集中进行循环。此行为有助于避免出现饥饿的情况，在该情况下，由于进程集中在一组已知的准备好文件描述符上而无法注意到其他文件描述符已准备就绪。

请注意，可以在兴趣列表当前为空的epoll实例上调用epoll_wait()(或者由于文件描述符已关闭或从另一个线程的兴趣中删除了，其兴趣列表变为空)。该调用将阻塞，直到稍后将某个文件描述符添加到关注列表(在另一个线程中)并且该文件描述符准备就绪。

BUGS

在2.6.37之前的内核中，大于大约LONG_MAX / HZ毫秒的超时值被视为-1(即无穷大)。因此，例如，在sizeof(long)为4且内核HZ值为1000的系统上，这意味着将大于35.79分钟的超时视为无穷大。

C library/kernel differences

原始epoll_pwait()系统调用具有第六个参数size_t sigsetsize，它指定sigmask参数的字节大小。 glibc epoll_pwait()包装函数将此参数指定为固定值(等于sizeof(sigset_t))。

另外参见

epoll_create(2)，epoll_ctl(2)，epoll(7)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本，请访问https://www.kernel.org/doc/man-pages/。