release/man2/eventfd.2

   1 .\" Copyright (C) 2008 Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\" starting from a version by Davide Libenzi <davidel@xmailserver.org>
   3 .\"
   4 .\" %%%LICENSE_START(GPLv2+_SW_3_PARA)
   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.
   9 .\"
  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.
  14 .\"
  15 .\" You should have received a copy of the GNU General Public
  16 .\" License along with this manual; if not, see
  17 .\" <http://www.gnu.org/licenses/>.
  18 .\" %%%LICENSE_END
  19 .\"
  20 .\" 2008-10-10, mtk: describe eventfd2(), and EFD_NONBLOCK and EFD_CLOEXEC
  21 .\"
  22 .\"*******************************************************************
  23 .\"
  24 .\" This file was generated with po4a. Translate the source file.
  25 .\"
  26 .\"*******************************************************************
  27 .TH EVENTFD 2 2010\-08\-30 Linux "Linux Programmer's Manual"
  28 .SH 名前
  29 eventfd \- イベント通知用のファイルディスクリプタを生成する
  30 .SH 書式
  31 \fB#include <sys/eventfd.h>\fP
  32 .sp
  33 \fBint eventfd(unsigned int \fP\fIinitval\fP\fB, int \fP\fIflags\fP\fB);\fP
  34 .SH 説明
  35 \fBeventfd\fP()  creates an "eventfd object" that can be used as an event
  36 wait/notify mechanism by user\-space applications, and by the kernel to
  37 notify user\-space applications of events.  The object contains an unsigned
  38 64\-bit integer (\fIuint64_t\fP)  counter that is maintained by the kernel.
  39 This counter is initialized with the value specified in the argument
  40 \fIinitval\fP.
  41
  42 以下の値のいくつかをビット単位の論理和 (OR) で指定することで、
  43 \fBeventfd\fP() の振舞いを変更することができる。
  44 .TP
  45 \fBEFD_CLOEXEC\fP (Linux 2.6.27 以降)
  46 新しいファイルディスクリプタに対して close\-on\-exec (\fBFD_CLOEXEC\fP)  フラグをセットする。
  47 このフラグが役に立つ理由については、 \fBopen\fP(2)  の \fBO_CLOEXEC\fP フラグの説明を参照のこと。
  48 .TP
  49 \fBEFD_NONBLOCK\fP (Linux 2.6.27 以降)
  50 新しく生成されるオープンファイル記述 (open file description) の \fBO_NONBLOCK\fP
  51 ファイルステータスフラグをセットする。 このフラグを使うことで、 \fBO_NONBLOCK\fP をセットするために \fBfcntl\fP(2)
  52 を追加で呼び出す必要がなくなる。
  53 .TP
  54 \fBEFD_SEMAPHORE\fP (Linux 2.6.30 以降)
  55 新しいファイルディスクリプタからの読み出しにおいて、セマフォ風の動作を行う。
  56 下記参照。
  57 .PP
  58 バージョン 2.6.26 以前の Linux では、 \fIflags\fP 引き数は未使用であり、0 を指定しなければならない。
  59
  60 \fBeventfd\fP()  は eventfd オブジェクトを参照するのに使用できる新しいファイルディスクリプタ
  61 を返す。返されたファイルディスクリプタに対しては以下の操作を実行できる。
  62 .TP
  63 \fBread\fP(2)
  64 \fBread\fP(2) は成功すると、8 バイトの整数を返す。
  65 渡されたバッファの大きさが 8 バイト未満の場合、
  66 \fBread\fP(2)  はエラー \fBEINVAL\fP で失敗する。
  67 .IP
  68 \fBread\fP(2) が返す値は、ホストバイトオーダ、つまり
  69 そのホストマシンにおける整数の通常のバイトオーダである。
  70 .IP
  71 \fBread\fP(2) の動作は、 eventfd カウンタの現在の値が 0 以外であるかと、
  72 eventfd ファイルディスクリプタを作成する際に \fBEFD_SEMAPHORE\fP フラグが
  73 指定されたか、により変化する。
  74 .RS
  75 .IP * 3
  76 \fBEFD_SEMAPHORE\fP が指定されておらず、eventfd カウンタが 0 以外の値
  77 の場合、 \fBread\fP(2) はカウンタ値を格納した 8 バイトの値を返し、
  78 カウンタ値は 0 にリセットされる。
  79 .IP *
  80 \fBEFD_SEMAPHORE\fP が指定されていて eventfd カウンタが 0 以外の値の場合、
  81 \fBread\fP(2) は値 1 の 8 バイト値を返し、カウンタ値は 1 減算される。
  82 .IP *
  83 \fBread\fP(2) を呼び出した時点で eventfd カウンタが 0 の場合、 \fBread\fP(2)
  84 はカウンタが 0 以外になるまで停止 (block) する (0 以外になった時点で
  85 \fBread\fP(2) は上記で述べた通り実行を再開する)、 もしくはファイルディスク
  86 リプタが非停止 (nonblocking) に設定されている場合はエラー \fBEAGAIN\fPで
  87 失敗する。
  88 .RE
  89 .TP
  90 \fBwrite\fP(2)
  91 \fBwrite\fP(2)  は、引き数のバッファで渡された 8 バイトの整数値をカウンタに加算する。 カウンタに格納可能な最大値は unsigned の
  92 64 ビット整数の最大値から 1 を引いた値 (すなわち 0xfffffffffffffffe) である。
  93 加算を行うとカウンタ値が最大値を超過する場合には、 そのファイルディスクリプタに対して \fBread\fP(2)  が実行されるまで、
  94 \fBwrite\fP(2)  は停止 (block) する、 もしくはファイルディスクリプタが非停止 (nonblocking)
  95 に設定されている場合はエラー \fBEAGAIN\fP で失敗する。
  96 .IP
  97 渡されたバッファの大きさが 8 バイト未満の場合、もしくは 値 0xffffffffffffffff を書き込もうとした場合、 \fBwrite\fP(2)
  98 はエラー \fBEINVAL\fP で失敗する。
  99 .TP
 100 \fBpoll\fP(2), \fBselect\fP(2) (と同様の操作)
 101 返されたファイルディスクリプタは、 \fBpoll\fP(2)  (\fBepoll\fP(7)  も同じ) や \fBselect\fP(2)
 102 をサポートしており、以下のような動作をする。
 103 .RS
 104 .IP * 3
 105 カウンタが 0 より大きい値の場合、 ファイルディスクリプタは読み出し可能となる (\fBselect\fP(2)  の \fIreadfds\fP 引き数や
 106 \fBpoll\fP(2)  の \fBPOLLIN\fP フラグ)。
 107 .IP *
 108 少なくとも値 "1" を、停止 (block) を伴わずに書き込める場合、 ファイルディスクリプタは書き込み可能となる (\fBselect\fP(2)  の
 109 \fIwritefds\fP 引き数や \fBpoll\fP(2)  の \fBPOLLOUT\fP フラグ)。
 110 .IP *
 111 カウンタ値のオーバーフローが検出された場合、 \fBselect\fP(2)  はファイルディスクリプタは読み出し可能と書き込み可能の両方を通知し、
 112 \fBpoll\fP(2)  は \fBPOLLERR\fP イベントを返す。 上述の通り、 \fBwrite\fP(2)
 113 でカウンタがオーバーフローすることは決してない。 しかしながら、 KAIO サブシステムによって 2^64 回の eventfd "signal
 114 posts" が 実行された場合にはオーバーフローが起こり得る (理論的にはあり得るが、実用的にはあり得ない)。 オーバーフローが発生した場合、
 115 \fBread\fP(2)  は \fIuint64_t\fP の最大値 (すなわち 0xffffffffffffffff) を返す。
 116 .RE
 117 .IP
 118 The eventfd file descriptor also supports the other file\-descriptor
 119 multiplexing APIs: \fBpselect\fP(2)  and \fBppoll\fP(2).
 120 .TP
 121 \fBclose\fP(2)
 122 ファイルディスクリプタがそれ以降は必要なくなった際には、クローズすべきである。 同じ eventfd
 123 オブジェクトに関連付けられたファイルディスクリプタが全て クローズされると、そのオブジェクト用の資源がカーネルにより解放される。
 124 .PP
 125 \fBfork\fP(2) で生成された子プロセスは、 \fBeventfd\fP() で生成されたファイル
 126 ディスクリプタのコピーを継承する。 複製されたファイルディスクリプタは同
 127 じ eventfd オブジェクトに関連付けられる。
 128 close\-on\-exec フラグが設定されていない場合、 \fBexecve\fP(2) の前後で
 129 \fBeventfd\fP() で生成されたファイルディスクリプタは保持される。
 130 .SH 返り値
 131 成功すると、 \fBeventfd\fP()  は新規の eventfd ファイルディスクリプタを返す。 エラーの場合、\-1 を返し、 \fIerrno\fP
 132 にエラーを示す値を設定する。
 133 .SH エラー
 134 .TP
 135 \fBEINVAL\fP
 136 \fIflags\fP にサポートされていない値が指定された。
 137 .TP
 138 \fBEMFILE\fP
 139 オープン済みのファイルディスクリプタの数がプロセスあたりの上限に 達していた。
 140 .TP
 141 \fBENFILE\fP
 142 オープン済みのファイル総数がシステム全体の上限に達していた。
 143 .TP
 144 \fBENODEV\fP
 145 .\" Note from Davide:
 146 .\" The ENODEV error is basically never going to happen if
 147 .\" the kernel boots correctly. That error happen only if during
 148 .\" the kernel initialization, some error occur in the anonymous
 149 .\" inode source initialization.
 150 (カーネル内の) 無名 inode デバイスをマウントできなかった。
 151 .TP
 152 \fBENOMEM\fP
 153 新しい eventfd ファイルディスクリプタを生成するのに十分なメモリがなかった。
 154 .SH バージョン
 155 .\" eventfd() is in glibc 2.7, but reportedly does not build
 156 \fBeventfd\fP()  はカーネル 2.6.22 以降の Linux で利用可能である。 正しく動作する glibc 側のサポートはバージョン
 157 2.8 以降で提供されている。 \fBeventfd2\fP()  システムコール (「注意」参照) は カーネル 2.6.27 以降の Linux
 158 で利用可能である。 バージョン 2.9 以降では、glibc の \fBeventfd\fP()  のラッパー関数は、カーネルが対応していれば
 159 \fBeventfd2\fP()  システムコールを利用する。
 160 .SH 準拠
 161 \fBeventfd\fP()  と \fBeventfd2\fP()  は Linux 固有である。
 162 .SH 注意
 163 アプリケーションは、パイプをイベントを通知するためだけに使用している 全ての場面において、パイプの代わりに eventfd ファイルディスクリプタを
 164 使用することができる。 eventfd ファイルディスクリプタを使う方が、パイプを使う場合に比べて
 165 カーネルでのオーバヘッドは比べるとずっと小さく、ファイルディスクリプタも 一つしか必要としない (パイプの場合は二つ必要である)。
 166
 167 .\" or eventually syslets/threadlets
 168 When used in the kernel, an eventfd file descriptor can provide a bridge
 169 from kernel to user space, allowing, for example, functionalities like KAIO
 170 (kernel AIO)  to signal to a file descriptor that some operation is
 171 complete.
 172
 173 eventfd ファイルディスクリプタの重要な点は、 eventfd ファイルディスクリプタが \fBselect\fP(2), \fBpoll\fP(2),
 174 \fBepoll\fP(7)  を使って他のファイルディスクリプタと全く同様に監視できる点である。 このことは、アプリケーションは「従来の
 175 (traditional)」 ファイルの状態変化と eventfd インタフェースをサポートする他のカーネル機構の状態変化を同時に監視
 176 できることを意味する (\fBeventfd\fP()  インタフェースがない時には、これらのカーネル機構は \fBselect\fP(2),
 177 \fBpoll\fP(2), \fBepoll\fP(7)  経由で多重することはできなかった)。
 178 .SS "下層にある Linux のシステムコール"
 179 下層にある Linux システムコールは二種類あり、 \fBeventfd\fP()  と、もっと新しい \fBeventfd2\fP()  である。
 180 \fBeventfd\fP()  は \fIflags\fP 引き数を実装していない。 \fBeventfd2\fP()  では上記の値の \fIflags\fP
 181 が実装されている。 glibc のラッパー関数は、 \fBeventfd2\fP()  が利用可能であれば、これを使用する。
 182 .SS "glibc の追加機能"
 183 GNU C ライブラリは、eventfd ファイルディスクリプタの読み出しと書き込みに
 184 を関する詳細のいくつか抽象化するために、一つの型と、二つの関数を追加で 定義している。
 185 .in +4n
 186 .nf
 187
 188 typedef uint64_t eventfd_t;
 189
 190 int eventfd_read(int fd, eventfd_t *value);
 191 int eventfd_write(int fd, eventfd_t value);
 192 .fi
 193 .in
 194
 195 これらの関数は、eventfd ファイルディスクリプタに対する読み出しと 書き込みの操作を実行し、正しいバイト数が転送された場合には 0
 196 を返し、そうでない場合は \-1 を返す。
 197 .SH 例
 198 .PP
 199 以下のプログラムは eventfd ファイルディスクリプタを生成し、 その後 fork を実行して子プロセスを生成する。 親プロセスが少しの間
 200 sleep する間に、子プロセスは プログラムのコマンドライン引き数で指定された整数(列)をそれぞれ eventfd ファイルディスクリプタに書き込む。
 201 親プロセスは sleep を完了すると eventfd ファイルディスクリプタから 読み出しを行う。
 202
 203 以下に示すシェルセッションにこのプログラムの使い方を示す。
 204 .in +4n
 205 .nf
 206
 207 $\fB ./a.out 1 2 4 7 14\fP
 208 Child writing 1 to efd
 209 Child writing 2 to efd
 210 Child writing 4 to efd
 211 Child writing 7 to efd
 212 Child writing 14 to efd
 213 Child completed write loop
 214 Parent about to read
 215 Parent read 28 (0x1c) from efd
 216 .fi
 217 .in
 218 .SS プログラムのソース
 219 \&
 220 .nf
 221 #include <sys/eventfd.h>
 222 #include <unistd.h>
 223 #include <stdlib.h>
 224 #include <stdio.h>
 225 #include <stdint.h>             /* Definition of uint64_t */
 226
 227 #define handle_error(msg) \e
 228     do { perror(msg); exit(EXIT_FAILURE); } while (0)
 229
 230 int
 231 main(int argc, char *argv[])
 232 {
 233     int efd, j;
 234     uint64_t u;
 235     ssize_t s;
 236
 237     if (argc < 2) {
 238         fprintf(stderr, "Usage: %s <num>...\en", argv[0]);
 239         exit(EXIT_FAILURE);
 240     }
 241
 242     efd = eventfd(0, 0);
 243     if (efd == \-1)
 244         handle_error("eventfd");
 245
 246     switch (fork()) {
 247     case 0:
 248         for (j = 1; j < argc; j++) {
 249             printf("Child writing %s to efd\en", argv[j]);
 250             u = strtoull(argv[j], NULL, 0);
 251                     /* strtoull() allows various bases */
 252             s = write(efd, &u, sizeof(uint64_t));
 253             if (s != sizeof(uint64_t))
 254                 handle_error("write");
 255         }
 256         printf("Child completed write loop\en");
 257
 258         exit(EXIT_SUCCESS);
 259
 260     default:
 261         sleep(2);
 262
 263         printf("Parent about to read\en");
 264         s = read(efd, &u, sizeof(uint64_t));
 265         if (s != sizeof(uint64_t))
 266             handle_error("read");
 267         printf("Parent read %llu (0x%llx) from efd\en",
 268                 (unsigned long long) u, (unsigned long long) u);
 269         exit(EXIT_SUCCESS);
 270
 271     case \-1:
 272         handle_error("fork");
 273     }
 274 }
 275 .fi
 276 .SH 関連項目
 277 \fBfutex\fP(2), \fBpipe\fP(2), \fBpoll\fP(2), \fBread\fP(2), \fBselect\fP(2),
 278 \fBsignalfd\fP(2), \fBtimerfd_create\fP(2), \fBwrite\fP(2), \fBepoll\fP(7),
 279 \fBsem_overview\fP(7)
 280 .SH この文書について
 281 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.50 の一部
 282 である。プロジェクトの説明とバグ報告に関する情報は
 283 http://www.kernel.org/doc/man\-pages/ に書かれている。