draft/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 .\"O .SH NAME
  32 .SH 名前
  33 .\"O futex \- Fast Userspace Locking system call
  34 futex \- 高速ユーザ空間ロック機構のシステムコール
  35 .\"O .SH SYNOPSIS
  36 .SH 書式
  37 .nf
  38 .sp
  39 .B "#include <linux/futex.h>"
  40 .B "#include <sys/time.h>"
  41 .sp
  42 .BI "int futex(int *" uaddr ", int " op ", int " val \
  43 ", const struct timespec *" timeout ,
  44 .br
  45 .BI "          int *" uaddr2 ", int " val3 );
  46 .\" int *? void *? u32 *?
  47 .fi
  48 .\"O .SH "DESCRIPTION"
  49 .SH 説明
  50 .PP
  51 .\"O The
  52 .\"O .BR futex ()
  53 .\"O system call provides a method for
  54 .\"O a program to wait for a value at a given address to change, and a
  55 .\"O method to wake up anyone waiting on a particular address (while the
  56 .\"O addresses for the same memory in separate processes may not be
  57 .\"O equal, the kernel maps them internally so the same memory mapped in
  58 .\"O different locations will correspond for
  59 .\"O .BR futex ()
  60 .\"O calls).
  61 .\"O This system call is typically used to
  62 .\"O implement the contended case of a lock in shared memory, as
  63 .\"O described in
  64 .\"O .BR futex (7).
  65 .BR futex ()
  66 システムコールは、
  67 指定したアドレスの値が変更されるのをプログラムが待つ手段や
  68 特定のアドレスに対して待機中のプロセスを wake (起床) させる手段を提供する
  69 (プロセスが異なれば同じメモリに対するアドレスも同じではないかもしれないが、
  70 カーネルは異なる位置にマップされた同じメモリを
  71 .BR futex ()
  72 で使えるよう内部でマップする)。
  73 通常は、このシステムコールは
  74 .BR futex (7)
  75 に書かれているように、
  76 共有メモリ中のロックが競合する場合の処理を実装するのに用いられる。
  77 .PP
  78 .\"O When a
  79 .\"O .BR futex (7)
  80 .\"O operation did not finish uncontended in userspace, a call needs to be made
  81 .\"O to the kernel to arbitrate.
  82 .\"O Arbitration can either mean putting the calling
  83 .\"O process to sleep or, conversely, waking a waiting process.
  84 .BR futex (7)
  85 の操作がユーザ空間で競合なく完了しなかった場合、
  86 カーネルに仲裁させるためにシステムコールを呼ぶ必要がある。
  87 仲裁というのは、呼び出しプロセスを sleep (起床待ち) させたり、反対に
  88 待ちプロセスを wake させたりすることを意味する。
  89 .PP
  90 .\"O Callers of this function are expected to adhere to the semantics as set out in
  91 .\"O .BR futex (7).
  92 .\"O As these
  93 .\"O semantics involve writing nonportable assembly instructions, this in turn
  94 .\"O probably means that most users will in fact be library authors and not
  95 .\"O general application developers.
  96 この関数を呼び出すプロセスは
  97 .BR futex (7)
  98 に記述されているセマンティクスに忠実であることが要求される。
  99 このセマンティクスには移植不可能なアセンブリ命令を書くことが含まれる。
 100 このことは言い換えると futex のユーザのほとんどは実際はライブラリの作者であり、
 101 一般アプリケーションの開発者ではないということである。
 102 .PP
 103 .\"O The
 104 .\"O .I uaddr
 105 .\"O argument needs to point to an aligned integer which stores the counter.
 106 .\"O The operation to execute is passed via the
 107 .\"O .I op
 108 .\"O argument, along with a value
 109 .\"O .IR val .
 110 .I uaddr
 111 引き数は、カウンタを格納する、
 112 アラインメントの揃った int 型変数を指している必要がある。
 113 実行する操作は
 114 .I op
 115 引き数を介して、値
 116 .I val
 117 とともに渡される。
 118 .PP
 119 .\"O Five operations are currently defined:
 120 現在のところ 5 つの操作が定義されている:
 121 .TP
 122 .B FUTEX_WAIT
 123 .\"O This operation atomically verifies that the futex address
 124 .\"O .I uaddr
 125 .\"O still contains the value
 126 .\"O .IR val ,
 127 .\"O and sleeps awaiting
 128 .\"O .B FUTEX_WAKE
 129 .\"O on this futex address.
 130 .\"O If the
 131 .\"O .I timeout
 132 .\"O argument is non-NULL, its contents describe the maximum
 133 .\"O duration of the wait, which is infinite otherwise.
 134 .\"O The arguments
 135 .\"O .I uaddr2
 136 .\"O and
 137 .\"O .I val3
 138 .\"O are ignored.
 139 この操作は futex アドレス
 140 .I uaddr
 141 に指定された値
 142 .I val
 143 がまだ格納されているかどうかを不可分操作で検証し、
 144 sleep 状態で
 145 この futex アドレスに対して
 146 .B FUTEX_WAKE
 147 が実行されるのを待つ。
 148 .I timeout
 149 引き数が NULL でない場合、その内容は
 150 待ち時間の最大値を表す。NULL の場合は無限大を表す。
 151 引き数
 152 .I uaddr2
 153 と
 154 .I val3
 155 は無視される。
 156
 157 .\"O For
 158 .\"O .BR futex (7),
 159 .\"O this call is executed if decrementing the count gave a negative value
 160 .\"O (indicating contention), and will sleep until another process releases
 161 .\"O the futex and executes the
 162 .\"O .B FUTEX_WAKE
 163 .\"O operation.
 164 .BR futex (7)
 165 に照らし合わせると、この呼び出しは
 166 カウントのデクリメントで負の値 (競合を表す) になった場合に実行され、
 167 別のプロセスがその futex を解放し
 168 .B FUTEX_WAKE
 169 の操作を実行するまで sleep する。
 170 .TP
 171 .B FUTEX_WAKE
 172 .\"O This operation wakes at most \fIval\fP
 173 .\"O processes waiting on this futex address (i.e., inside
 174 .\"O .BR FUTEX_WAIT ).
 175 この操作では指定した futex アドレスに対して待ち状態の
 176 (すなわち
 177 .B FUTEX_WAIT
 178 中の) 最大 \fIval\fP 個のプロセスを wake させる。
 179 .\"O The arguments
 180 .\"O .IR timeout ,
 181 .\"O .I uaddr2
 182 .\"O and
 183 .\"O .I val3
 184 .\"O are ignored.
 185 引き数
 186 .IR timeout ,
 187 .IR uaddr2 ,
 188 .I val3
 189 は無視される。
 190
 191 .\"O For
 192 .\"O .BR futex (7),
 193 .\"O this is executed if incrementing
 194 .\"O the count showed that there were waiters, once the futex value has been set
 195 .\"O to 1 (indicating that it is available).
 196 \fBfutex\fR(4) に照らし合わせると、
 197 この操作は
 198 カウントのインクリメントで待ちプロセスがあると判明し、
 199 futex 値が 1 に設定された (利用可能であることを表す) 場合に実行される。
 200 .TP
 201 .\"O .BR FUTEX_FD " (present up to and including Linux 2.6.25)"
 202 .BR FUTEX_FD " (Linux 2.6.25 以前)"
 203 .\"O To support asynchronous wakeups, this operation associates a file descriptor
 204 .\"O with a futex.
 205 .\"O .\" , suitable for .BR poll (2).
 206 .\"O If another process executes a
 207 .\"O .BR FUTEX_WAKE ,
 208 .\"O the process will receive the signal number that was passed in
 209 .\"O number that was passed in
 210 .\"O .IR val .
 211 .\"O The calling process must close the returned file descriptor after use.
 212 非同期の wake に対応するため、この操作はファイルディスクリプタを futex に
 213 関連づける。
 214 .\" .BR poll (2)
 215 .\" に適している。
 216 別のプロセスが
 217 .B FUTEX_WAKE
 218 を実行すると、プロセスは
 219 .I val
 220 で渡されたシグナル番号のシグナルを受信する。
 221 呼び出しプロセスは使用後、返されたファイルディスクリプタを
 222 クローズしなければならない。
 223 .\"O The arguments
 224 .\"O .IR timeout ,
 225 .\"O .I uaddr2
 226 .\"O and
 227 .\"O .I val3
 228 .\"O are ignored.
 229 引き数
 230 .IR timeout ,
 231 .IR uaddr2 ,
 232 .I val3
 233 は無視される。
 234
 235 .\"O To prevent race conditions, the caller should test if the futex has
 236 .\"O been upped after
 237 .\"O .B FUTEX_FD
 238 .\"O returns.
 239 競合状態を防止するため、呼び出しプロセスは
 240 .B FUTEX_FD
 241 が返ったあと
 242 futex が up されたかどうかを確認しなければならない。
 243
 244 .\" FIXME . Check that this flag does eventually get removed.
 245 .\"O Because it was inherently racy,
 246 .\"O .B FUTEX_FD
 247 .\"O has been removed from Linux 2.6.26 onward.
 248 .B FUTEX_FD
 249 はもともと競合が起きやすかったため、
 250 Linux 2.6.26 以降で削除されている。
 251 .TP
 252 .\"O .BR FUTEX_REQUEUE " (since Linux 2.5.70)"
 253 .BR FUTEX_REQUEUE " (Linux 2.5.70 以降)"
 254 .\"O This operation was introduced in order to avoid a "thundering herd" effect
 255 .\"O when
 256 .\"O .B FUTEX_WAKE
 257 .\"O is used and all processes woken up need to acquire another
 258 .\"O futex.
 259 .\"O This call wakes up
 260 .\"O .I val
 261 .\"O processes, and requeues all other waiters on the futex at address
 262 .\"O .IR uaddr2 .
 263 この操作は、
 264 .B FUTEX_WAKE
 265 が使われていて、かつ wake されている全てのプロセスが
 266 他の futex を取得する必要がある場合に、
 267 「獣の群れの暴走 (thundering herd)」効果を避けるために導入された。
 268 この呼び出しは
 269 .I val
 270 個のプロセスを wake し、アドレス
 271 .I uaddr2
 272 で futex を待っている他の全てのプロセスを再度キューにいれる。
 273 .\"O The arguments
 274 .\"O .I timeout
 275 .\"O and
 276 .\"O .I val3
 277 .\"O are ignored.
 278 引き数
 279 .I timeout
 280 と
 281 .I val3
 282 は無視される。
 283 .TP
 284 .\"O .BR FUTEX_CMP_REQUEUE " (since Linux 2.6.7)"
 285 .BR FUTEX_CMP_REQUEUE " (Linux 2.6.7 以降)"
 286 .\"O There was a race in the intended use of
 287 .\"O .BR FUTEX_REQUEUE ,
 288 .\"O so
 289 .\"O .B FUTEX_CMP_REQUEUE
 290 .\"O was introduced.
 291 .\"O This is similar to
 292 .\"O .BR FUTEX_REQUEUE ,
 293 .\"O but first checks whether the location
 294 .\"O .I uaddr
 295 .\"O still contains the value
 296 .\"O .IR val3 .
 297 .\"Osato:
 298 .\"Osato: intended がよく分からない。
 299 .\"Osato:
 300 故意に
 301 .B FUTEX_REQUEUE
 302 を使う場合に競合が起こるため、
 303 .B FUTEX_CMP_REQUEUE
 304 が導入された。これは
 305 .B FUTEX_REQUEUE
 306 と似ているが、場所
 307 .I uaddr
 308 に値
 309 .I val3
 310 がまだ保持されているかを最初にチェックする。
 311 .\"O If not, the operation fails with the error
 312 .\"O .BR EAGAIN .
 313 .\"O The argument
 314 .\"O .I timeout
 315 .\"O is ignored.
 316 保持されていない場合、操作はエラー
 317 .B EAGAIN
 318 で失敗する。引き数
 319 .I timeout
 320 は無視される。
 321 .\"O .SH "RETURN VALUE"
 322 .SH 返り値
 323 .PP
 324 .\"O Depending on which operation was executed,
 325 .\"O the returned value for a successful call can have differing meanings.
 326 どの操作が実行されたかによって、
 327 成功時の返り値の意味が変わる。
 328 .TP
 329 .B FUTEX_WAIT
 330 .\"O Returns 0 if the process was woken by a
 331 .\"O .B FUTEX_WAKE
 332 .\"O call.
 333 .\"O In case of timeout,
 334 .\"O the operation fails with the error
 335 .\"O .BR ETIMEDOUT .
 336 .\"O If the futex was not equal to the expected value,
 337 .\"O the operation fails with the error
 338 .\"O .BR EWOULDBLOCK .
 339 .\"O Signals (see
 340 .\"O .BR signal (7))
 341 .\"O or other spurious wakeups cause
 342 .\"O .B FUTEX_WAIT
 343 .\"O to fail with the error
 344 .\"O .BR EINTR .
 345 プロセスが
 346 .B FUTEX_WAKE
 347 の呼び出しで wake すると 0 を返す。
 348 タイムアウトの場合、操作はエラー
 349 .B ETIMEOUT
 350 で失敗する。
 351 futex が指定された値と等しくない場合、
 352 エラー
 353 .B EWOULDBLOCK
 354 で失敗する。
 355 シグナルを受信するか
 356 .RB ( signal (7)
 357 参照) 他の偽の wake があった場合には、エラー
 358 .B EINTR
 359 で失敗する。
 360 .TP
 361 .B FUTEX_WAKE
 362 .\"O Returns the number of processes woken up.
 363 wake したプロセスの数を返す。
 364 .TP
 365 .B FUTEX_FD
 366 .\"O Returns the new file descriptor associated with the futex.
 367 futex に関連づけられた新たなファイルディスクリプタを返す。
 368 .TP
 369 .B FUTEX_REQUEUE
 370 .\"O Returns the number of processes woken up.
 371 wake したプロセスの数を返す。
 372 .TP
 373 .B FUTEX_CMP_REQUEUE
 374 .\"O Returns the number of processes woken up.
 375 wake したプロセスの数を返す。
 376 .PP
 377 .\"O In the event of an error, all operations return \-1, and set
 378 .\"O .I errno
 379 .\"O to indicate the error.
 380 エラーの場合、全ての操作で \-1 が返り、
 381 .I errno
 382 がエラーの内容を示す値に設定される。
 383 .\"O .SH ERRORS
 384 .SH エラー
 385 .TP
 386 .B EACCES
 387 .\"O No read access to futex memory.
 388 futex メモリに読み込みアクセス権がなかった。
 389 .TP
 390 .B EAGAIN
 391 .\"O .B FUTEX_CMP_REQUEUE
 392 .\"O found an unexpected futex value.
 393 .\"O (This probably indicates a race;
 394 .\"O use the safe
 395 .\"O .B FUTEX_WAKE
 396 .\"O now.)
 397 .B FUTEX_CMP_REQUEUE
 398 で予期しない futex 値が見つかった
 399 (これは競合を示しているかもしれない。
 400 この場合は安全な
 401 .B FUTEX_WAKE
 402 を使うこと)。
 403 .TP
 404 .B EFAULT
 405 .\"O Error in getting
 406 .\"O .I timeout
 407 .\"O information from userspace.
 408 ユーザ空間から
 409 .I timeout
 410 の情報を取得する際にエラーが発生した。
 411 .TP
 412 .B EINVAL
 413 .\"O An operation was not defined or error in page alignment.
 414 操作が定義されていない。またはページ・アラインメントでエラーが発生した。
 415 .TP
 416 .B ENFILE
 417 .\"O The system limit on the total number of open files has been reached.
 418 オープンされているファイルの総数がシステムの制限に達した。
 419 .TP
 420 .B ENOSYS
 421 .\"O Invalid operation specified in
 422 .\"O .IR op .
 423 .I op
 424 に無効な操作が指定された。
 425 .\"O .SH "VERSIONS"
 426 .SH バージョン
 427 .PP
 428 .\"O Initial futex support was merged in Linux 2.5.7 but with different semantics
 429 .\"O from what was described above.
 430 .\"O A 4-argument system call with the semantics
 431 .\"O described in this page was introduced in Linux 2.5.40.
 432 .\"O In Linux 2.5.70 one argument
 433 .\"O was added.
 434 .\"O In Linux 2.6.7 a sixth argument was added\(emmessy, especially
 435 .\"O on the s390 architecture.
 436 最初の futex 対応は Linux 2.5.7 で組み込まれたが、
 437 上記のセマンティクスとは異なる。
 438 4 つの引き数のここに書かれているセマンティクスを持つ
 439 システムコールは、Linux 2.5.40 で導入された。
 440 Linux 2.5.70 では 1 つの引き数が追加された。
 441 Linux 2.6.7 では 6 番目の引き数が追加された。
 442 これは汚く、s390 アーキテクチャ上の特別のものである。
 443 .\"O .SH "CONFORMING TO"
 444 .SH 準拠
 445 .\"O This system call is Linux-specific.
 446 このシステムコールは Linux 独自である。
 447 .\"O .SH "NOTES"
 448 .SH 注意
 449 .PP
 450 .\"O To reiterate, bare futexes are not intended as an easy-to-use abstraction
 451 .\"O for end-users.
 452 .\"O (There is no wrapper function for this system call in glibc.)
 453 .\"O Implementors are expected to be assembly literate and to have
 454 .\"O read the sources of the futex userspace library referenced below.
 455 繰り返すが、裸の futex はエンドユーザが容易に使うことのできる概念として
 456 意図されたものではない
 457 (glibc にはこのシステムコールに対するラッパー関数はない)。
 458 実装者は、アセンブリ言語に慣れており、以下に挙げる futex ユーザ空間ライブラリの
 459 ソースを読み終えていることが要求される。
 460 .\"O .\" .SH "AUTHORS"
 461 .\" .SH 著者
 462 .\" .PP
 463 .\"O .\" Futexes were designed and worked on by
 464 .\"O .\" Hubertus Franke (IBM Thomas J. Watson Research Center),
 465 .\"O .\" Matthew Kirkwood, Ingo Molnar (Red Hat)
 466 .\"O .\" and Rusty Russell (IBM Linux Technology Center).
 467 .\"O .\" This page written by bert hubert.
 468 .\" futex は Hubertus Franke (IBM Thomas J. Watson Research Center),
 469 .\" Matthew Kirkwood, Ingo Molnar (Red Hat),
 470 .\" Rusty Russell (IBM Linux Technology Center) が設計し、作成した。
 471 .\" このページは bert hubert が記した。
 472 .\"O .SH SEE ALSO
 473 .SH 関連項目
 474 .BR futex (7)
 475 .PP
 476 \fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP
 477 (proceedings of the Ottawa Linux Symposium 2002), online at
 478 .br
 479 http://kernel.org/doc/ols/2002/ols2002-pages-479-495.pdf
 480 .PP
 481 .\"O Futex example library, futex-*.tar.bz2 at
 482 futex の使用例ライブラリ, futex-*.tar.bz2
 483 .br
 484 ftp://ftp.nl.kernel.org/pub/linux/kernel/people/rusty/.