名前

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() が停止する最小時間をミリ秒で指定する (この停止時間はシステムクロックの粒度に切り上げられ、カーネルのスケジューリング遅延により少しだけ長くなる可能性がある)。 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_wait() は要求された I/O に対して準備ができているファイルディスクリプタの数を返す。また要求された timeout ミリ秒の間にファイルディスクリプタが準備できない場合は、0 を返す。エラーが起こった場合、 epoll_wait() は-1 を返し、 errno を適切に設定する。

エラー

EBADF

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

EFAULT

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

EINTR

要求されたどのイベントも発生せず、かつ 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_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 分よりも大きなタイムアウトは無限大として扱われるということである。

関連項目

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

この文書について

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