SIMPLE SOLUTIONS

EPOLL_WAIT(2) - Linux manual

Epoll ファイルディスクリプターの I/O イベントを待つ.

2014-08-19
EPOLL_WAIT(2) Linux Programmer's Manual EPOLL_WAIT(2)

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) インスタンスに対するイベントを待つ。 events が指すメモリー領域には、 呼び出し側が利用可能なイベントが格納される。最大 maxevents 個のイベントが epoll_wait() によって返される。 maxevents 引き数は 0 より大きくなければならない。 timeout 引き数は epoll_wait() が停止する時間をミリ秒で指定する。 epoll_wait() の呼び出しは以下のいずれかになるまで停止する。 * ファイルディスクリプターがイベントを配送した * 呼び出しがシグナルハンドラーにより割り込まれた * タイムアウトが満了する 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; /* ユーザーデータ変数 */ }; 返される構造体の data メンバには、ユーザーが epoll_ctl(2) (EPOLL_CTL_ADD, EPOLL_CTL_MOD) で指定したデータが格納される。 一方、 events メンバには返された利用可能なイベントのビットフィールドが格納される。 epoll_pwait() epoll_wait() と epoll_pwait() の関係は、 select(2)pselect(2) の関係と同様である。 pselect(2) 同様、 epoll_pwait() を使うと、アプリケーションは、ファイルディスクリプターが準備できた状態になるか、 シグナルが捕捉されるまで、安全に待つことができる。 以下の epoll_pwait() の呼び出しは、 ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask); 次の呼び出しを atomic に実行するのと等価である。 sigset_t origmask; sigprocmask(SIG_SETMASK, &sigmask, &origmask); ready = epoll_wait(epfd, &events, maxevents, timeout); sigprocmask(SIG_SETMASK, &origmask, NULL); sigmask 引き数には NULL を指定してもよい。 その場合には、 epoll_pwait() は epoll_wait() と等価となる。

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

EBADF epfd が有効なファイルディスクリプターでない。 EFAULT events で指されるメモリー領域に書き込み権限でアクセスできない。 EINTR (1) 要求されたどのイベントも発生せず、かつ (2) timeout の期限が切れる前に、システムコールがシグナルハンドラーによって割り込まれた。 sig‐ nal(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_pwait() を呼び出して停止されている間に、 別のスレッドが wait 中の epoll インストールにファイルディスクリプターを 追加することがある。新しいファイルディスクリプターでイベントが発生すると、 epoll_wait() の呼び出しによる停止が解除されることになる。 epoll_wait() で監視中の epoll インスタンス内のファイルディスクリプターが別のスレッドによってクローズされた場合に何が起こるかの議論については、 select(2) を参照してほしい。

バージョン 2.6.37 より前のカーネルでは、おおよそ LONG_MAX / HZ ミリ秒より大きい timeout 値は -1 (つまり無限大) として扱われる。したがって、例えば、sizeof(long) が 4 で、カーネルの HZ の値が 1000 のシステムでは、 35.79 分よりも大きなタイムアウトは無限大として扱われるということである。 C ラ 素の epoll_pwait() システムコールは 6 番目の引き数 size_t sigsetsize を取る。 この引き数は sigmask 引き数のバイト単位のサイズを指定する。 glibc の epoll_pwait() ラッパー関数は、この引き数に固定値 (sizeof(sigset_t) と同じ) を指定する。

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

この man ページは Linux man-pages プロジェクトのリリース 3.79 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。
Linux 2014-08-19 EPOLL_WAIT(2)
epoll_wait(2).txt (日本語 / Japanese)
Index English version of epoll_wait(2)
Go top