draft/man7/epoll.7

   1 .\"  Copyright (C) 2003  Davide Libenzi
   2 .\"
   3 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
   4 .\"  This program is free software; you can redistribute it and/or modify
   5 .\"  it under the terms of the GNU General Public License as published by
   6 .\"  the Free Software Foundation; either version 2 of the License, or
   7 .\"  (at your option) any later version.
   8 .\"
   9 .\"  This program is distributed in the hope that it will be useful,
  10 .\"  but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 .\"  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 .\"  GNU General Public License for more details.
  13 .\"
  14 .\" You should have received a copy of the GNU General Public
  15 .\" License along with this manual; if not, see
  16 .\" <http://www.gnu.org/licenses/>.
  17 .\" %%%LICENSE_END
  18 .\"
  19 .\"  Davide Libenzi <davidel@xmailserver.org>
  20 .\"
  21 .\"*******************************************************************
  22 .\"
  23 .\" This file was generated with po4a. Translate the source file.
  24 .\"
  25 .\"*******************************************************************
  26 .\"
  27 .\" Japanese Version Copyright (c) 2004-2005 Yuichi SATO
  28 .\"         all rights reserved.
  29 .\" Translated Sat Jun 19 07:50:04 JST 2004
  30 .\"         by Yuichi SATO <ysato444@yahoo.co.jp>
  31 .\" Updated & Modified 2005-01-18, Yuichi SATO
  32 .\" Updated 2006-07-14, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  33 .\"         Catch up to LDP v2.34. epoll.4 is renamed to epoll.7.
  34 .\" Updated 2007-09-07, Akihiro MOTOKI, LDP v2.64
  35 .\" Updated 2008-04-08, Akihiro MOTOKI, LDP v2.79
  36 .\" Updated 2009-02-23, Akihiro MOTOKI, LDP v3.19
  37 .\"
  38 .TH EPOLL 7 2015\-01\-10 Linux "Linux Programmer's Manual"
  39 .SH 名前
  40 epoll \- I/O イベント通知機能
  41 .SH 書式
  42 \fB#include <sys/epoll.h>\fP
  43 .SH 説明
  44 \fBepoll\fP API は \fBpoll\fP(2) と同様の処理を行う、つまり、複数のファイルディスク
  45 リプタを監視し、その中のいずれかが入出力可能な状態であるかを確認する。
  46 \fBepoll\fP API は、エッジトリガインタフェースとレベルトリガインタフェースの
  47 いずれとしても使用することができ、監視するファイルディスクリプタの数が多い
  48 場合にも使用できる。 \fBepoll\fP インスタンスの作成や管理を行うために
  49 以下のシステムコールが提供されている:
  50 .IP * 3
  51 \fBepoll_create\fP(2) は \fBepoll\fP インスタンスを作成し、そのインスタンスを参照する
  52 ファイルディスクリプタを返す。(もっと新しい \fBepoll_create1\fP(2) では、
  53 \fBepoll_create\fP(2) の機能が拡張されている)。
  54 .IP *
  55 特定のファイルディスクリプタに対する監視内容を \fBepoll_ctl\fP(2)  で登録する。 \fBepoll\fP
  56 インスタンスに現在登録されているファイルディスクリプタの集合は \fIepoll\fP 集合と呼ばれることもある。
  57 .IP *
  58 \fBepoll_wait\fP(2) は I/O イベントを待つ。
  59 現在利用可能な状態のイベントがなければ、呼び出したスレッドを停止する。
  60 .SS レベルトリガとエッジトリガ
  61 \fBepoll\fP イベント配送 (distribution) インタフェースは、 エッジトリガ (ET) としてもレベルトリガ (LT)
  62 としても動作させることができる。 二つの配送機構の違いは、次のように説明できる。 このようなシナリオが起こったとしよう:
  63 .IP 1. 3
  64 パイプの読み込み側を表すファイルディスクリプタ (\fIrfd\fP)  が \fBepoll\fP インスタンスに登録される。
  65 .IP 2.
  66 パイプへ書き込むプログラムが 2 kB のデータをパイプの書き込み側へ書き込む。
  67 .IP 3.
  68 \fBepoll_wait\fP(2)  を呼び出すと、読み込み可能 (ready) なファイルディスクリプタとして \fIrfd\fP が返る。
  69 .IP 4.
  70 パイプから読み出すプログラムが、1 kB のデータを \fIrfd\fP から読み出す。
  71 .IP 5.
  72 \fBepoll_wait\fP(2)  の呼び出しが行われる。
  73 .PP
  74 \fIrfd\fP ファイルディスクリプタが \fBEPOLLET\fP フラグ (エッジトリガ) を使って \fBepoll\fP に追加されていると、
  75 利用可能なデータがファイル入力バッファにまだ存在するにもかかわらず ステップ \fB5\fP の \fBepoll_wait\fP(2)
  76 の呼び出しでハングする可能性がある。 その一方で、リモートの接続先 (peer) は既に送られたデータに 基づいて応答を期待しているかもしれない。
  77 このようなことが起こる理由は、エッジトリガイベント配送では、 モニタしているファイルでイベントが起ったときにのみイベントが 配送されるためである。
  78 したがって、ステップ \fB5\fP では、呼び出し側は結果的に 入力バッファ内にすで存在するデータを待つことになるかもしれない。 上記の例では、 \fB2\fP
  79 で行われた書き込みによって \fIrfd\fP に関するイベントが生成され、 \fB3\fP でイベントが消費 (consume) される。 \fB4\fP
  80 で行われる読み込み操作では、全部のバッファデータを消費しないので、 ステップ \fB5\fP で行われる \fBepoll_wait\fP(2)  の呼び出しが
  81 無期限に停止 (block) するかもしれない。
  82
  83 \fBEPOLLET\fP フラグを採用するアプリケーションでは、 インタフェースはブロックしない (nonblocking) ファイルディスクリプタを
  84 使うべきである。 これは、ブロックされる読み込みや書き込みによって、 複数のファイルディスクリプタを扱うタスクが 停止してしまうのを避けるためである。
  85 \fBepoll\fP をエッジトリガ (\fBEPOLLET\fP)  インタフェースとして使うために提案される方法は以下の通りである。
  86 .RS
  87 .TP  4
  88 \fBi\fP
  89 ブロックしないファイルディスクリプタと共に使う。
  90 .TP
  91 \fBii\fP
  92 \fBread\fP(2)  または \fBwrite\fP(2)  が \fBEAGAIN\fP を返した後でのみ、イベントを待つ。
  93 .RE
  94 .PP
  95 一方、レベルトリガインタフェースとして使う場合
  96  (こちらがデフォルトである、
  97 \fBEPOLLET\fP が指定されなかった場合)、
  98 \fBepoll\fP は単に高速な \fBpoll\fP(2) であり、使い方が同じなので、
  99 \fBpoll\fP(2) が使われているところではどこでも使用することができる。
 100
 101 エッジトリガを使った場合でも、複数のデータを受信すると複数の \fBepoll\fP イベントが生成されるので、 呼び出し側には
 102 \fBEPOLLONESHOT\fP フラグを指定するオプションがある。 このフラグは \fBepoll\fP に対して、 \fBepoll_wait\fP(2)
 103 によるイベントを受信した後で、関連するファイルディスクリプタを無効にさせる。 \fBEPOLLONESHOT\fP フラグが指定された場合、
 104 \fBepoll_ctl\fP(2)  に \fBEPOLL_CTL_MOD\fP を指定してファイルディスクリプタを再度使用できるようにするのは、
 105 呼び出し側の責任である。
 106 .SS "autosleep との関係"
 107 システムが \fI/sys/power/autosleep\fP 経由で \fBautosleep\fP モードになっていて、
 108 デバイスをスリープ状態から起こすイベントが発生した場合、
 109 そのイベントがキューに入るまでは、デバイスドライバーはデバイスを起こしたままにしておくだけである。
 110 イベントが処理されるまでデバイスを起こしたままにしておくには、 \fBepoll\fP(7) \fBEPOLLWAKEUP\fP フラグを使う必要がある。
 111
 112 \fBEPOLLWAKEUP\fP フラグが \fIstruct epoll_event\fP の \fBevents\fP フィールドでセットされた場合、
 113 イベントがキューに入った瞬間から、\fBepoll_wait\fP(2) がそのイベントを返し次の \fBepoll_wait\fP(2)
 114 の呼び出しが行われるまでの間、システムは起きたままの状態になる。
 115 イベントが上記の時間の範囲を超えてシステムを起きたままの状態にしておく必要がある場合は、 2 番目の \fBepoll_wait\fP(2)
 116 の呼び出しの前に別の \fIwake_lock\fP を取る必要がある。
 117 .SS "/proc インタフェース"
 118 .\" Following was added in 2.6.28, but them removed in 2.6.29
 119 .\" .TP
 120 .\" .IR /proc/sys/fs/epoll/max_user_instances " (since Linux 2.6.28)"
 121 .\" This specifies an upper limit on the number of epoll instances
 122 .\" that can be created per real user ID.
 123 epoll が消費するカーネルメモリの量を制限するために、 以下のインタフェースを使用することができる。
 124 .TP
 125 \fI/proc/sys/fs/epoll/max_user_watches\fP (Linux 2.6.28 以降)
 126 .\" 2.6.29 (in 2.6.28, the default was 1/32 of lowmem)
 127 このファイルは、あるユーザがシステム上の全ての epoll インスタンスに 登録できるファイルディスクリプタの総数の上限を規定する。 この上限は実ユーザ
 128 ID 単位である。 登録されたファイルディスクリプタ 1 つが消費するメモリ量は、 32 ビットカーネルでおよそ 90 バイト、 64
 129 ビットカーネルでおよそ 160 バイトである。 現在のところ、 \fImax_user_watches\fP のデフォルト値は、利用可能なメモリ下限の
 130 1/25 (4%) であり、 登録で消費されるメモリ量 (バイト単位) で割った値となる。
 131 .SS おすすめな使用例
 132 レベルトリガインタフェースとして使用するときの \fBepoll\fP の使い方は \fBpoll\fP(2)  と同じである。
 133 しかしエッジトリガとして使う場合は、 アプリケーションのイベントループでストール (stall) しないように、 使い方をより明確にしておく必要がある。
 134 この例では、リスナはブロックしないソケットであり、 \fBlisten\fP(2)  が呼ばれている。 関数 \fIdo_use_fd()\fP は、
 135 \fBread\fP(2)  または \fBwrite\fP(2)  によって \fBEAGAIN\fP が返されるまでは、新しい準備済みのファイルディスクリプタを使う。
 136 イベント駆動ステートマシンアプリケーションは、 \fBEAGAIN\fP を受信した後、カレントの状態を記録しておくべきである。 これにより、次の
 137 \fIdo_use_fd()\fP 呼び出しのときに、以前に停止したところから \fBread\fP(2)  または \fBwrite\fP(2)
 138 を継続することができる。
 139
 140 .in +4n
 141 .nf
 142 #define MAX_EVENTS 10
 143 struct epoll_event ev, events[MAX_EVENTS];
 144 int listen_sock, conn_sock, nfds, epollfd;
 145
 146 /* Code to set up listening socket, \(aqlisten_sock\(aq,
 147    (socket(), bind(), listen()) omitted */
 148
 149 epollfd = epoll_create1(0);
 150 if (epollfd == \-1) {
 151     perror("epoll_create1");
 152     exit(EXIT_FAILURE);
 153 }
 154
 155 ev.events = EPOLLIN;
 156 ev.data.fd = listen_sock;
 157 if (epoll_ctl(epollfd, EPOLL_CTL_ADD, listen_sock, &ev) == \-1) {
 158     perror("epoll_ctl: listen_sock");
 159     exit(EXIT_FAILURE);
 160 }
 161
 162 for (;;) {
 163     nfds = epoll_wait(epollfd, events, MAX_EVENTS, \-1);
 164     if (nfds == \-1) {
 165         perror("epoll_pwait");
 166         exit(EXIT_FAILURE);
 167     }
 168
 169     for (n = 0; n < nfds; ++n) {
 170         if (events[n].data.fd == listen_sock) {
 171             conn_sock = accept(listen_sock,
 172                             (struct sockaddr *) &local, &addrlen);
 173             if (conn_sock == \-1) {
 174                 perror("accept");
 175                 exit(EXIT_FAILURE);
 176             }
 177             setnonblocking(conn_sock);
 178             ev.events = EPOLLIN | EPOLLET;
 179             ev.data.fd = conn_sock;
 180             if (epoll_ctl(epollfd, EPOLL_CTL_ADD, conn_sock,
 181                         &ev) == \-1) {
 182                 perror("epoll_ctl: conn_sock");
 183                 exit(EXIT_FAILURE);
 184             }
 185         } else {
 186             do_use_fd(events[n].data.fd);
 187         }
 188     }
 189 }
 190 .fi
 191 .in
 192
 193 エッジトリガインタフェースとして使う場合、性能上の理由により、 一度 (\fBEPOLLIN\fP|\fBEPOLLOUT\fP)  を指定してから
 194 (\fBEPOLL_CTL_ADD\fP で) ファイルディスクリプタを \fBepoll\fP インタフェースに追加することができる。 これにより、
 195 \fBepoll_ctl\fP(2)  に \fBEPOLL_CTL_MOD\fP を指定して呼び出すことで \fBEPOLLIN\fP と \fBEPOLLOUT\fP
 196 の連続的な切り替えが避けられる。
 197 .SS 質問と解答
 198 .TP  4
 199 \fBQ0\fP
 200 \fBepoll\fP 集合内の登録されたファイルディスクリプタを区別するには、 何をキーとして使えばよいか？
 201 .TP
 202 \fBA0\fP
 203 キーはファイルディスクリプタ番号とオープンファイル記述 (open file description) の組である (オープンファイル記述は "open
 204 file handle" とも 呼ばれ、オープンされたファイルのカーネルの内部表現である)。
 205 .TP
 206 \fBQ1\fP
 207 1 つの \fBepoll\fP インスタンスに同じファイルディスクリプタを 2 回登録するとどうなるか？
 208 .TP
 209 \fBA1\fP
 210 .\" But a descriptor duplicated by fork(2) can't be added to the
 211 .\" set, because the [file *, fd] pair is already in the epoll set.
 212 .\" That is a somewhat ugly inconsistency.  On the one hand, a child process
 213 .\" cannot add the duplicate file descriptor to the epoll set.  (In every
 214 .\" other case that I can think of, descriptors duplicated by fork have
 215 .\" similar semantics to descriptors duplicated by dup() and friends.)  On
 216 .\" the other hand, the very fact that the child has a duplicate of the
 217 .\" descriptor means that even if the parent closes its descriptor, then
 218 .\" epoll_wait() in the parent will continue to receive notifications for
 219 .\" that descriptor because of the duplicated descriptor in the child.
 220 .\"
 221 .\" See http://thread.gmane.org/gmane.linux.kernel/596462/
 222 .\" "epoll design problems with common fork/exec patterns"
 223 .\"
 224 .\" mtk, Feb 2008
 225 たぶん \fBEEXIST\fP を受け取るだろう。 しかしながら、同じ \fBepoll\fP
 226 インスタンスに対して複製されたディスクリプタを追加することは可能である (\fBdup\fP(2), \fBdup2\fP(2), \fBfcntl\fP(2)
 227 \fBF_DUPFD\fP など)。 複製したファイルディスクリプタを異なる \fIevents\fP マスクで登録すれば、イベントをフィルタリングするのに
 228 この機能は有用な手法である。
 229 .TP
 230 \fBQ2\fP
 231 2 つの \fBepoll\fP インスタンスが同じファイルディスクリプタを待ち受けることは可能か？ もし可能であれば、イベントは両方の \fBepoll\fP
 232 ファイルディスクリプタに報告されるか？
 233 .TP
 234 \fBA2\fP
 235 イベントは両方に報告される。 しかしながら、これを正しく扱うには注意深くプログラミングする必要が あるかもしれない。
 236 .TP
 237 \fBQ3\fP
 238 \fBepoll\fP ファイルディスクリプタ自身は poll/epoll/select が可能か？
 239 .TP
 240 \fBA3\fP
 241 可能である。 \fBepoll\fP ファイルディスクリプタに処理待ちのイベントがある場合は、 読み出し可能だと通知されることだろう。
 242 .TP
 243 \fBQ4\fP
 244 \fBepoll\fP ファイルディスクリプタを自身のファイルディスクリプタ集合に 入れようとするとどうなるか？
 245 .TP
 246 \fBA4\fP
 247 \fBepoll_ctl\fP(2)  の呼び出しは (\fBEINVAL\fP で) 失敗するだろう。 ただし \fBepoll\fP ファイルディスクリプタを他の
 248 \fBepoll\fP ファイルディスクリプタ集合の内部に追加することは可能である。
 249 .TP
 250 \fBQ5\fP
 251 \fBepoll\fP ファイルディスクリプタを UNIX ドメインソケットで他のプロセスに送ることは可能か？
 252 .TP
 253 \fBA5\fP
 254 可能だが、これをすることに意味はない。 なぜなら、受信側のプロセスが \fBepoll\fP 集合内のファイルディスクリプタのコピーを持っていないからである。
 255 .TP
 256 \fBQ6\fP
 257 ファイルディスクリプタをクローズすると、そのファイルディスクリプタは全ての \fBepoll\fP 集合から自動的に削除されるか？
 258 .TP
 259 \fBA6\fP
 260 削除されるが、以下の点に注意が必要である。 ファイルディスクリプタはオープンファイル記述 (\fBopen\fP(2)  参照) への参照である。
 261 ディスクリプタの複製を \fBdup\fP(2), \fBdup2\fP(2), \fBfcntl\fP(2)  の \fBF_DUPFD\fP や \fBfork\fP(2)
 262 経由で行う度に、同じオープンファイル記述を参照する新規のファイル ディスクリプタが生成される。
 263 オープンファイル記述自体は、自身を参照する全てのファイルディスクリプタ がクローズされるまで存在し続ける。 ファイルディスクリプタが \fBepoll\fP
 264 集合から削除されるのは、対応するオープンファイル記述を参照している 全てのファイルディスクリプタがクローズされた後である
 265 (\fBepoll_ctl\fP(2)  \fBEPOLL_CTL_DEL\fP を使ってそのディスクリプタを明示的に削除した場合にも削除される)。 このことは、
 266 \fBepoll\fP 集合に属しているあるファイルディスクリプタをクローズした後であっても、
 267 同じファイル記述を参照する他のファイルディスクリプタがオープンされている間は、 クローズしたファイルディスクリプタ宛にイベントが報告される可能性があると
 268 いうことを意味する。
 269 .TP
 270 \fBQ7\fP
 271 2 つ以上のイベントが \fBepoll_wait\fP(2)  コールの間に発生した場合、それらはまとめて報告されるか、 それとも別々に報告されるか？
 272 .TP
 273 \fBA7\fP
 274 まとめて報告されるだろう。
 275 .TP
 276 \fBQ8\fP
 277 ファイルディスクリプタに対する操作は、 既に集められているがまだ報告されていないイベントに影響するか？
 278 .TP
 279 \fBA8\fP
 280 既存のファイルディスクリプタに対して 2 つの操作を行うことができる。 この場合、削除には意味がない。 変更すると、使用可能な I/O
 281 が再び読み込まれる。
 282 .TP
 283 \fBQ9\fP
 284 \fBEPOLLET\fP フラグ (エッジトリガ動作) を使っている場合、 \fBEAGAIN\fP を受け取るまで、
 285 継続してファイルディスクリプタを読み書きする必要があるか？
 286 .TP
 287 \fBA9\fP
 288 \fBepoll_wait\fP(2)  からイベントを受け取ることは、 そのファイルディスクリプタが要求された I/O 操作に対して準備済みである、
 289 ということをユーザに示すものである。 次の (ブロックしない) read/write で \fBEAGAIN\fP
 290 を受け取るまではファイルディスクリプタは準備済みであると 考えなければならない。 そのファイルディスクリプタをいつどのように使うかは、
 291 全くユーザに任されてる。
 292 .sp
 293 パケット指向やトークン指向のファイル (例えば、データグラムソケット、 canonical モードの端末) では、 読み込み用 / 書き込み用の I/O
 294 空間の末尾を検知する唯一の方法は \fBEAGAIN\fP になるまで read/write を行うことである。
 295 .sp
 296 ストリーム指向のファイル (例えば、パイプ、FIFO、ストリームソケット) では、 読み込み用 / 書き込み用の I/O 空間が使い尽くされた状態は、
 297 対象となるファイルディスクリプタから読み込んだデータ量または 書き込んだデータ量をチェックすることでも検知できる。
 298 例えば、ある特定の量のデータを読み込むために \fBread\fP(2)  を呼んだときに、 \fBread\fP(2)
 299 が返したバイト数がそれより少なかった場合、 そのファイルディスクリプタの読み込み用 I/O 空間が 使い尽くされたことが分かる。 \fBwrite\fP(2)
 300 を使って書き込みをするときも、同じことが言える (監視しているファイルディスクリプタが常にストリーム指向のファイルを
 301 参照していることを保証できない場合には、後者の手法の使用を避けること)。
 302 .SS ありがちな落とし穴と回避方法
 303 .TP
 304 \fBo 飢餓 (starvation) (エッジトリガ)\fP
 305 .PP
 306 大きな I/O 空間がある場合、 その I/O 空間のデータを全て処理 (drain) しようとすると、
 307 他のファイルが処理されず、飢餓を発生させることがある (この問題は \fBepoll\fP に固有のものではない)。
 308 .PP
 309 この問題の解決法は、準備済み状態のリストを管理して、 関連する data 構造体の中でファイルディスクリプタが 利用可能であるとマークすることである。
 310 それによって、利用可能なすべてのファイルの中で どのファイルを処理する必要があるかを憶えることができ、 しかも順番に処理 (round robin)
 311 することができる。 既に利用可能であるファイルディスクリプタに対して それ以後に受け取るイベントを無視することもできる。
 312 .TP
 313 \fBo イベントキャッシュを使っている場合\fP
 314 .PP
 315 イベントキャッシュを使っている場合、 または \fBepoll_wait\fP(2)  から返された全てのファイルディスクリプタを格納している場合、
 316 クローズされたことを動的にマークする (つまり前のイベントの処理によってマークされる) 方法を提供すべきである。 \fBepoll_wait\fP(2)
 317 から 100 個のイベントを受け取り、 イベント #47 ではある条件でイベント #13 が閉じられると仮定する。 イベント #13
 318 の構造体を削除しファイルディスクリプタを \fBclose\fP(2)  すると、イベントキャッシュはそのファイルディスクリプタを待つイベントが
 319 存在するといって、混乱が起きる。
 320 .PP
 321 この問題を解決する 1 つの方法は、イベント 47 の処理をしている間に、 ファイルディスクリプタ 13 を削除して \fBclose\fP(2)
 322 するために \fBepoll_ctl\fP(\fBEPOLL_CTL_DEL\fP)  を呼び出し、関連付けられた data 構造体を削除済みとマークして、
 323 クリーンアップリストにリンクすることである。 バッチ処理の中でファイルディスクリプタ 13 についての 他のイベントを見つけた場合、
 324 そのファイルディスクリプタが以前に削除されたものであると分かるので、 混乱は起きない。
 325 .SH バージョン
 326 .\" Its interface should be finalized in Linux kernel 2.5.66.
 327 \fBepoll\fP API は Linux カーネル 2.5.44 に導入された。 glibc でのサポートはバージョン 2.3.2 で追加された。
 328 .SH 準拠
 329 \fBepoll\fP API は Linux 固有である。 他のシステムでも同様の機構が提供されている場合がある。 例えば、FreeBSD の
 330 \fIkqueue\fP や Solaris の \fI/dev/poll\fP などである。
 331 .SH 関連項目
 332 \fBepoll_create\fP(2), \fBepoll_create1\fP(2), \fBepoll_ctl\fP(2), \fBepoll_wait\fP(2)
 333 .SH この文書について
 334 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.77 の一部
 335 である。プロジェクトの説明とバグ報告に関する情報は
 336 http://www.kernel.org/doc/man\-pages/ に書かれている。