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_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
- 要求されたどのイベントも発生せず、かつ
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_create(2),
epoll_ctl(2),
epoll(7)
この文書について¶
この man ページは Linux
man-pages
プロジェクトのリリース
3.41 の一部
である。プロジェクトの説明とバグ報告に関する情報は
http://www.kernel.org/doc/man-pages/
に書かれている。