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