2 .\" epoll by Davide Libenzi ( efficient event notification retrieval )
3 .\" Copyright (C) 2003 Davide Libenzi
5 .\" This program is free software; you can redistribute it and/or modify
6 .\" it under the terms of the GNU General Public License as published by
7 .\" the Free Software Foundation; either version 2 of the License, or
8 .\" (at your option) any later version.
10 .\" This program is distributed in the hope that it will be useful,
11 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
12 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13 .\" GNU General Public License for more details.
15 .\" You should have received a copy of the GNU General Public License
16 .\" along with this program; if not, write to the Free Software
17 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
19 .\" Davide Libenzi <davidel@xmailserver.org>
21 .\" 2007-04-30: mtk, Added description of epoll_pwait()
23 .\"*******************************************************************
25 .\" This file was generated with po4a. Translate the source file.
27 .\"*******************************************************************
28 .TH EPOLL_WAIT 2 2012\-04\-17 Linux "Linux Programmer's Manual"
30 epoll_wait, epoll_pwait \- epoll ファイルディスクリプタの I/O イベントを待つ
33 \fB#include <sys/epoll.h>\fP
35 \fBint epoll_wait(int \fP\fIepfd\fP\fB, struct epoll_event *\fP\fIevents\fP\fB,\fP
36 \fB int \fP\fImaxevents\fP\fB, int \fP\fItimeout\fP\fB);\fP
37 \fBint epoll_pwait(int \fP\fIepfd\fP\fB, struct epoll_event *\fP\fIevents\fP\fB,\fP
38 \fB int \fP\fImaxevents\fP\fB, int \fP\fItimeout\fP\fB,\fP
39 \fB const sigset_t *\fP\fIsigmask\fP\fB);\fP
42 \fBepoll_wait\fP() システムコールは、ファイルディスクリプタ \fIepfd\fP で参照される
43 \fBepoll\fP(7) インスタンスに対するイベントを待つ。 \fIevents\fP が指すメモリ領域には、
44 呼び出し側が利用可能なイベントが格納される。最大 \fImaxevents\fP 個のイベントが
45 \fBepoll_wait\fP() によって返される。
46 \fImaxevents\fP 引き数は 0 より大きくなければならない。
48 最大で \fItimeout\fP ミリ秒間、呼び出したスレッドを停止させる。
49 \fItimeout\fP を \-1 に指定すると、 \fBepoll_wait\fP() は無限に停止する。
50 \fItimeout\fP を 0 に指定すると、 \fBepoll_wait\fP() は利用可能なイベントが
53 \fIstruct epoll_event\fP は以下のように定義される:
57 typedef union epoll_data {
65 uint32_t events; /* epoll イベント */
66 epoll_data_t data; /* ユーザデータ変数 */
71 返される構造体の \fIdata\fP メンバには、ユーザが \fBepoll_ctl\fP(2) (\fBEPOLL_CTL_ADD\fP,
72 \fBEPOLL_CTL_MOD\fP) で指定したデータが格納される。 一方、 \fIevents\fP
73 メンバには返された利用可能なイベントのビットフィールドが格納される。
75 \fBepoll_wait\fP() と \fBepoll_pwait\fP() の関係は、 \fBselect\fP(2) と \fBpselect\fP(2)
76 の関係と同様である。 \fBpselect\fP(2) 同様、 \fBepoll_pwait\fP()
77 を使うと、アプリケーションは、ファイルディスクリプタが準備できた状態になるか、 シグナルが捕捉されるまで、安全に待つことができる。
79 以下の \fBepoll_pwait\fP() の呼び出しは、
82 ready = epoll_pwait(epfd, &events, maxevents, timeout, &sigmask);
85 次の呼び出しを \fIatomic\fP に実行するのと等価である。
90 sigprocmask(SIG_SETMASK, &sigmask, &origmask);
91 ready = epoll_wait(epfd, &events, maxevents, timeout);
92 sigprocmask(SIG_SETMASK, &origmask, NULL);
95 \fIsigmask\fP 引き数には NULL を指定してもよい。 その場合には、 \fBepoll_pwait\fP() は \fBepoll_wait\fP()
98 成功した場合、 \fBepoll_wait\fP() は要求された I/O に対して準備ができているファイルディスクリプタの数を返す。 また要求された
99 \fItimeout\fP ミリ秒の間にファイルディスクリプタが準備できない場合は、0 を返す。 エラーが起こった場合、 \fBepoll_wait\fP() は
100 \-1 を返し、 \fIerrno\fP を適切に設定する。
104 \fIepfd\fP が有効なファイルディスクリプタでない。
107 \fIevents\fP で指されるメモリ領域に書き込み権限でアクセスできない。
110 要求されたどのイベントも発生せず、かつ \fItimeout\fP の期限が切れる前に、システムコールがシグナルハンドラによって割り込まれた。
114 \fIepfd\fP が \fBepoll\fP ファイルディスクリプタでない。 または \fImaxevents\fP が 0 以下である。
116 .\" To be precise: kernel 2.5.44.
117 .\" The interface should be finalized by Linux kernel 2.5.66.
118 \fBepoll_wait\fP() はカーネル 2.6 で追加された。
119 ライブラリによるサポートは glibc バージョン 2.3.2 以降で提供されている。
121 \fBepoll_pwait\fP() はカーネル 2.6.19 で Linux に追加された。
122 ライブラリによるサポートは glibc バージョン 2.6 以降で提供されている。
124 \fBepoll_wait\fP() は Linux 独自である。
126 あるスレッドが \fBepoll_pwait\fP() を呼び出して停止されている間に、
127 別のスレッドが wait 中の \fBepoll\fP インストールにファイルディスクリプタを
128 追加することがある。新しいファイルディスクリプタでイベントが発生すると、
129 \fBepoll_wait\fP() の呼び出しによる停止が解除されることになる。
131 \fBepoll_create\fP(2), \fBepoll_ctl\fP(2), \fBepoll\fP(7)