release/man2/futex.2

   1 .\" Page by b.hubert - may be freely modified and distributed
   2 .\"
   3 .\" Niki A. Rahimi (LTC Security Development, narahimi@us.ibm.com)
   4 .\" added ERRORS section.
   5 .\"
   6 .\" Modified 2004-06-17 mtk
   7 .\" Modified 2004-10-07 aeb, added FUTEX_REQUEUE, FUTEX_CMP_REQUEUE
   8 .\"
   9 .\" FIXME See also https://bugzilla.kernel.org/show_bug.cgi?id=14303
  10 .\" 2.6.14 adds FUTEX_WAKE_OP
  11 .\" 2.6.18 adds (Ingo Molnar) priority inheritance support:
  12 .\" FUTEX_LOCK_PI, FUTEX_UNLOCK_PI, and FUTEX_TRYLOCK_PI.  These need
  13 .\" to be documented in the manual page.  Probably there is sufficient
  14 .\" material in the kernel source file Documentation/pi-futex.txt.
  15 .\" 2.6.25 adds FUTEX_WAKE_BITSET, FUTEX_WAIT_BITSET
  16 .\"
  17 .\" Japanese Version Copyright(C) 2003 Suzuki Takashi
  18 .\"         all rights reserved.
  19 .\" Translated Fri Oct 24 10:37:10 JST 2003
  20 .\"         by Suzuki Takashi.
  21 .\" Updated & Modified Sat Feb  5 14:28:53 JST 2005
  22 .\"         by Yuichi SATO <ysato444@yahoo.co.jp>, LDP v2.01
  23 .\" Updated & Modified Wed Jan  3 04:51:22 JST 2007 by Yuichi SATO, LDP v2.43
  24 .\"
  25 .\"WORD: integer                int 型変数
  26 .\"WORD: sleep                  起床待ちする
  27 .\"WORD: wake                   起床する
  28 .\"WORD: wake up                起床する
  29 .\"
  30 .TH FUTEX 2 2010-08-29 "Linux" "Linux Programmer's Manual"
  31 .SH 名前
  32 futex \- 高速ユーザ空間ロック機構のシステムコール
  33 .SH 書式
  34 .nf
  35 .sp
  36 .B "#include <linux/futex.h>"
  37 .B "#include <sys/time.h>"
  38 .sp
  39 .BI "int futex(int *" uaddr ", int " op ", int " val \
  40 ", const struct timespec *" timeout ,
  41 .br
  42 .BI "          int *" uaddr2 ", int " val3 );
  43 .\" int *? void *? u32 *?
  44 .fi
  45 .SH 説明
  46 .PP
  47 .BR futex ()
  48 システムコールは、
  49 指定したアドレスの値が変更されるのをプログラムが待つ手段や
  50 特定のアドレスに対して待機中のプロセスを wake (起床) させる手段を提供する
  51 (プロセスが異なれば同じメモリに対するアドレスも同じではないかもしれないが、
  52 カーネルは異なる位置にマップされた同じメモリを
  53 .BR futex ()
  54 で使えるよう内部でマップする)。
  55 通常は、このシステムコールは
  56 .BR futex (7)
  57 に書かれているように、
  58 共有メモリ中のロックが競合する場合の処理を実装するのに用いられる。
  59 .PP
  60 .BR futex (7)
  61 の操作がユーザ空間で競合なく完了しなかった場合、
  62 カーネルに仲裁させるためにシステムコールを呼ぶ必要がある。
  63 仲裁というのは、呼び出しプロセスを sleep (起床待ち) させたり、反対に
  64 待ちプロセスを wake させたりすることを意味する。
  65 .PP
  66 この関数を呼び出すプロセスは
  67 .BR futex (7)
  68 に記述されているセマンティクスに忠実であることが要求される。
  69 このセマンティクスには移植不可能なアセンブリ命令を書くことが含まれる。
  70 このことは言い換えると futex のユーザのほとんどは実際はライブラリの作者であり、
  71 一般アプリケーションの開発者ではないということである。
  72 .PP
  73 .I uaddr
  74 引き数は、カウンタを格納する、
  75 アラインメントの揃った int 型変数を指している必要がある。
  76 実行する操作は
  77 .I op
  78 引き数を介して、値
  79 .I val
  80 とともに渡される。
  81 .PP
  82 現在のところ 5 つの操作が定義されている:
  83 .TP
  84 .B FUTEX_WAIT
  85 この操作は futex アドレス
  86 .I uaddr
  87 に指定された値
  88 .I val
  89 がまだ格納されているかどうかを不可分操作で検証し、
  90 sleep 状態で
  91 この futex アドレスに対して
  92 .B FUTEX_WAKE
  93 が実行されるのを待つ。
  94 .I timeout
  95 引き数が NULL でない場合、その内容は
  96 待ち時間の最大値を表す。NULL の場合は無限大を表す。
  97 引き数
  98 .I uaddr2
  99 と
 100 .I val3
 101 は無視される。
 102
 103 .BR futex (7)
 104 に照らし合わせると、この呼び出しは
 105 カウントのデクリメントで負の値 (競合を表す) になった場合に実行され、
 106 別のプロセスがその futex を解放し
 107 .B FUTEX_WAKE
 108 の操作を実行するまで sleep する。
 109 .TP
 110 .B FUTEX_WAKE
 111 この操作では指定した futex アドレスに対して待ち状態の
 112 (すなわち
 113 .B FUTEX_WAIT
 114 中の) 最大 \fIval\fP 個のプロセスを wake させる。
 115 引き数
 116 .IR timeout ,
 117 .IR uaddr2 ,
 118 .I val3
 119 は無視される。
 120
 121 \fBfutex\fR(4) に照らし合わせると、
 122 この操作は
 123 カウントのインクリメントで待ちプロセスがあると判明し、
 124 futex 値が 1 に設定された (利用可能であることを表す) 場合に実行される。
 125 .TP
 126 .BR FUTEX_FD " (Linux 2.6.25 以前)"
 127 非同期の wake に対応するため、この操作はファイルディスクリプタを futex に
 128 関連づける。
 129 .\" .BR poll (2)
 130 .\" に適している。
 131 別のプロセスが
 132 .B FUTEX_WAKE
 133 を実行すると、プロセスは
 134 .I val
 135 で渡されたシグナル番号のシグナルを受信する。
 136 呼び出しプロセスは使用後、返されたファイルディスクリプタを
 137 クローズしなければならない。
 138 引き数
 139 .IR timeout ,
 140 .IR uaddr2 ,
 141 .I val3
 142 は無視される。
 143
 144 競合状態を防止するため、呼び出しプロセスは
 145 .B FUTEX_FD
 146 が返ったあと
 147 futex が up されたかどうかを確認しなければならない。
 148
 149 .\" FIXME . Check that this flag does eventually get removed.
 150 .B FUTEX_FD
 151 はもともと競合が起きやすかったため、
 152 Linux 2.6.26 以降で削除されている。
 153 .TP
 154 .BR FUTEX_REQUEUE " (Linux 2.5.70 以降)"
 155 この操作は、
 156 .B FUTEX_WAKE
 157 が使われていて、かつ wake されている全てのプロセスが
 158 他の futex を取得する必要がある場合に、
 159 「獣の群れの暴走 (thundering herd)」効果を避けるために導入された。
 160 この呼び出しは
 161 .I val
 162 個のプロセスを wake し、アドレス
 163 .I uaddr2
 164 で futex を待っている他の全てのプロセスを再度キューにいれる。
 165 引き数
 166 .I timeout
 167 と
 168 .I val3
 169 は無視される。
 170 .TP
 171 .BR FUTEX_CMP_REQUEUE " (Linux 2.6.7 以降)"
 172 故意に
 173 .B FUTEX_REQUEUE
 174 を使う場合に競合が起こるため、
 175 .B FUTEX_CMP_REQUEUE
 176 が導入された。これは
 177 .B FUTEX_REQUEUE
 178 と似ているが、場所
 179 .I uaddr
 180 に値
 181 .I val3
 182 がまだ保持されているかを最初にチェックする。
 183 保持されていない場合、操作はエラー
 184 .B EAGAIN
 185 で失敗する。引き数
 186 .I timeout
 187 は無視される。
 188 .SH 返り値
 189 .PP
 190 どの操作が実行されたかによって、
 191 成功時の返り値の意味が変わる。
 192 .TP
 193 .B FUTEX_WAIT
 194 プロセスが
 195 .B FUTEX_WAKE
 196 の呼び出しで wake すると 0 を返す。
 197 タイムアウトの場合、操作はエラー
 198 .B ETIMEOUT
 199 で失敗する。
 200 futex が指定された値と等しくない場合、
 201 エラー
 202 .B EWOULDBLOCK
 203 で失敗する。
 204 シグナルを受信するか
 205 .RB ( signal (7)
 206 参照) 他の偽の wake があった場合には、エラー
 207 .B EINTR
 208 で失敗する。
 209 .TP
 210 .B FUTEX_WAKE
 211 wake したプロセスの数を返す。
 212 .TP
 213 .B FUTEX_FD
 214 futex に関連づけられた新たなファイルディスクリプタを返す。
 215 .TP
 216 .B FUTEX_REQUEUE
 217 wake したプロセスの数を返す。
 218 .TP
 219 .B FUTEX_CMP_REQUEUE
 220 wake したプロセスの数を返す。
 221 .PP
 222 エラーの場合、全ての操作で \-1 が返り、
 223 .I errno
 224 がエラーの内容を示す値に設定される。
 225 .SH エラー
 226 .TP
 227 .B EACCES
 228 futex メモリに読み込みアクセス権がなかった。
 229 .TP
 230 .B EAGAIN
 231 .B FUTEX_CMP_REQUEUE
 232 で予期しない futex 値が見つかった
 233 (これは競合を示しているかもしれない。
 234 この場合は安全な
 235 .B FUTEX_WAKE
 236 を使うこと)。
 237 .TP
 238 .B EFAULT
 239 ユーザ空間から
 240 .I timeout
 241 の情報を取得する際にエラーが発生した。
 242 .TP
 243 .B EINVAL
 244 操作が定義されていない。またはページ・アラインメントでエラーが発生した。
 245 .TP
 246 .B ENFILE
 247 オープンされているファイルの総数がシステムの制限に達した。
 248 .TP
 249 .B ENOSYS
 250 .I op
 251 に無効な操作が指定された。
 252 .SH バージョン
 253 .PP
 254 最初の futex 対応は Linux 2.5.7 で組み込まれたが、
 255 上記のセマンティクスとは異なる。
 256 4 つの引き数のここに書かれているセマンティクスを持つ
 257 システムコールは、Linux 2.5.40 で導入された。
 258 Linux 2.5.70 では 1 つの引き数が追加された。
 259 Linux 2.6.7 では 6 番目の引き数が追加された。
 260 これは汚く、s390 アーキテクチャ上の特別のものである。
 261 .SH 準拠
 262 このシステムコールは Linux 独自である。
 263 .SH 注意
 264 .PP
 265 繰り返すが、裸の futex はエンドユーザが容易に使うことのできる概念として
 266 意図されたものではない
 267 (glibc にはこのシステムコールに対するラッパー関数はない)。
 268 実装者は、アセンブリ言語に慣れており、以下に挙げる futex ユーザ空間ライブラリの
 269 ソースを読み終えていることが要求される。
 270 .\" .SH 著者
 271 .\" .PP
 272 .\" futex は Hubertus Franke (IBM Thomas J. Watson Research Center),
 273 .\" Matthew Kirkwood, Ingo Molnar (Red Hat),
 274 .\" Rusty Russell (IBM Linux Technology Center) が設計し、作成した。
 275 .\" このページは bert hubert が記した。
 276 .SH 関連項目
 277 .BR futex (7)
 278 .PP
 279 \fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP
 280 (proceedings of the Ottawa Linux Symposium 2002), online at
 281 .br
 282 http://kernel.org/doc/ols/2002/ols2002-pages-479-495.pdf
 283 .PP
 284 futex の使用例ライブラリ, futex-*.tar.bz2
 285 .br
 286 ftp://ftp.nl.kernel.org/pub/linux/kernel/people/rusty/.