名前¶

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

説明¶

The epoll_wait() system call waits for events on the epoll(7) instance referred to by the file descriptor epfd. The buffer pointed to by events is used to return information from the ready list about file descriptors in the interest list that have some events available. Up to maxevents are returned by epoll_wait(). The maxevents argument must be greater than zero.

The timeout argument specifies the number of milliseconds that epoll_wait() will block. Time is measured against the CLOCK_MONOTONIC clock.

A call to epoll_wait() will block until either:

• ファイルディスクリプターがイベントを配送した
• 呼び出しがシグナルハンドラーにより割り込まれた
• タイムアウトが満了する

timeout 時間はシステムクロックの粒度に切り上げられ、カーネルのスケジューリング遅延により少しだけ長くなる可能性がある点に注意すること。 timeout を -1 に指定すると、 epoll_wait() は無限に停止する。 timeout を 0 に指定すると、 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 イベント */


    epoll_data_t data;      /* ユーザーデータ変数 */
};

The data field of each returned epoll_event structure contains the same data as was specified in the most recent call to epoll_ctl(2) (EPOLL_CTL_ADD, EPOLL_CTL_MOD) for the corresponding open file descriptor.

The events field is a bit mask that indicates the events that have occurred for the corresponding open file description. See epoll_ctl(2) for a list of the bits that may appear in this mask.

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

返り値¶

成功した場合、 epoll_wait() は要求された I/O に対して準備ができているファイルディスクリプターの数を返す。 また要求された timeout ミリ秒の間にファイルディスクリプターが準備できない場合は、0 を返す。 エラーが起こった場合、 epoll_wait() は -1 を返し、 errno を適切に設定する。

エラー¶

EBADF

epfd が有効なファイルディスクリプターでない。

EFAULT

events で指されるメモリー領域に書き込み権限でアクセスできない。

EINTR

(1) 要求されたどのイベントも発生せず、かつ (2) timeout の期限が切れる前に、システムコールがシグナルハンドラーによって割り込まれた。 signal(7) 参照。

EINVAL

epfd が epoll ファイルディスクリプターでない。 または maxevents が 0 以下である。

バージョン¶

epoll_wait() はカーネル 2.6 で追加された。 ライブラリによるサポートは glibc バージョン 2.3.2 以降で提供されている。

epoll_pwait() はカーネル 2.6.19 で Linux に追加された。 ライブラリによるサポートは glibc バージョン 2.6 以降で提供されている。

準拠¶

epoll_wait() は Linux 独自である。

注意¶

あるスレッドが epoll_wait() を呼び出して停止されている間に、別のスレッドが wait 中の epoll インストールにファイルディスクリプターを追加することがある。新しいファイルディスクリプターでイベントが発生すると、 epoll_wait() の呼び出しによる停止が解除されることになる。

If more than maxevents file descriptors are ready when epoll_wait() is called, then successive epoll_wait() calls will round robin through the set of ready file descriptors. This behavior helps avoid starvation scenarios, where a process fails to notice that additional file descriptors are ready because it focuses on a set of file descriptors that are already known to be ready.

Note that it is possible to call epoll_wait() on an epoll instance whose interest list is currently empty (or whose interest list becomes empty because file descriptors are closed or removed from the interest in another thread). The call will block until some file descriptor is later added to the interest list (in another thread) and that file descriptor becomes ready.

バグ¶

バージョン 2.6.37 より前のカーネルでは、おおよそ LONG_MAX / HZ ミリ秒より大きい timeout 値は -1 (つまり無限大) として扱われる。したがって、例えば、sizeof(long) が 4 で、カーネルの HZ の値が 1000 のシステムでは、 35.79 分よりも大きなタイムアウトは無限大として扱われるということである。

関連項目¶

epoll_create(2), epoll_ctl(2), epoll(7)

この文書について¶

この man ページは Linux man-pages プロジェクトのリリース 5.10 の一部である。プロジェクトの説明とバグ報告に関する情報は https://www.kernel.org/doc/man-pages/ に書かれている。