EPOLL_WAIT(2) Linux Programmer's Manual EPOLL_WAIT(2)

NAME

epoll_wait, epoll_pwait - wait for an I/O event on an epoll file descriptor

SYNOPSIS

#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);

DESCRIPTION

• epoll_wait() 等待在epfd描述符注册事件，events返回可操作的事件， maxevents 作为返回值返回，必须大于0，timeout 参数 指定阻塞的毫秒数，发生下面中的一个事件会返回：
  
  • 其中一个描述符交付一个事件
  • 调用被其他信号打断
  • 时间到达.
• 注意timeout 会被折算成系统时间间隔(就是说并不准确), 指定-1将导致无限期阻塞, 指定0将不阻塞

       The struct epoll_event is defined as:

           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_ctl()注册时相同事件
• epoll_pwait()跟epoll_wait()和epoll_pwait()的关系就像select(2)和pselect(2):的关系 .epoll_pwait()允许应用安全的等待直到有事件被递交或被信号打断
• The following epoll_pwait() call:

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

is equivalent to atomically executing the following calls:

    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().

• 返回值：成功返回有事发生的描述符的个数或0，在等待期间如果发生错误，返回-1，并且errno被设置

• 错误值

  • EBADF epfd不是一个有效的文件描述符
  • EFAULT 没有写权限
  • EINTR 调用被信号打断
  • EINVAL epfd不是一个epoll文件描述符,或maxevents小于等于0

• NOTES

  • 当一个线程阻塞在epoll_pwait()调用时,另外一个线程在epfd增加一个文件描述符是可以的，如果新的文件描述符变为可读，将会导致 epoll_wait()不阻塞.
  • 关于在另一个线程取消一个描述符，这个线程会发生什么可以参考select(2).

• BUGS

  • In kernels before 2.6.37, a timeout value larger than approximately
    LONG_MAX / HZ milliseconds is treated as -1 (i.e., infinity). Thus,
    for example, on a system where the sizeof(long) is 4 and the kernel HZ
    value is 1000, this means that timeouts greater than 35.79 minutes are
    treated as infinity.

  C library/kernel differences
  The raw epoll_pwait() system call has a sixth argument, size_t sigset‐
  size, which specifies the size in bytes of the sigmask argument. The
  glibc epoll_pwait() wrapper function specifies this argument as a fixed
  value (equal to sizeof(sigset_t)).