release/man2/futex.2

   1 .\" Page by b.hubert
   2 .\"
   3 .\" %%%LICENSE_START(FREELY_REDISTRIBUTABLE)
   4 .\" may be freely modified and distributed
   5 .\" %%%LICENSE_END
   6 .\"
   7 .\" Niki A. Rahimi (LTC Security Development, narahimi@us.ibm.com)
   8 .\" added ERRORS section.
   9 .\"
  10 .\" Modified 2004-06-17 mtk
  11 .\" Modified 2004-10-07 aeb, added FUTEX_REQUEUE, FUTEX_CMP_REQUEUE
  12 .\"
  13 .\" FIXME
  14 .\" See also https://bugzilla.kernel.org/show_bug.cgi?id=14303
  15 .\" 2.6.14 adds FUTEX_WAKE_OP
  16 .\"     commit 4732efbeb997189d9f9b04708dc26bf8613ed721
  17 .\"     Author: Jakub Jelinek <jakub@redhat.com>
  18 .\"     Date:   Tue Sep 6 15:16:25 2005 -0700
  19 .\"
  20 .\" FIXME
  21 .\" 2.6.18 adds (Ingo Molnar) priority inheritance support:
  22 .\" FUTEX_LOCK_PI, FUTEX_UNLOCK_PI, and FUTEX_TRYLOCK_PI.  These need
  23 .\" to be documented in the manual page.  Probably there is sufficient
  24 .\" material in the kernel source file Documentation/pi-futex.txt.
  25 .\"     commit c87e2837be82df479a6bae9f155c43516d2feebc
  26 .\"     Author: Ingo Molnar <mingo@elte.hu>
  27 .\"     Date:   Tue Jun 27 02:54:58 2006 -0700
  28 .\"
  29 .\"     commit e2970f2fb6950183a34e8545faa093eb49d186e1
  30 .\"     Author: Ingo Molnar <mingo@elte.hu>
  31 .\"     Date:   Tue Jun 27 02:54:47 2006 -0700
  32 .\"
  33 .\"     See Documentation/futex-requeue-pi.txt
  34 .\"
  35 .\" FIXME
  36 .\" 2.6.25 adds FUTEX_WAKE_BITSET, FUTEX_WAIT_BITSET
  37 .\"     commit cd689985cf49f6ff5c8eddc48d98b9d581d9475d
  38 .\"     Author: Thomas Gleixner <tglx@linutronix.de>
  39 .\"     Date:   Fri Feb 1 17:45:14 2008 +0100
  40 .\"
  41 .\" FIXME
  42 .\" 2.6.31 adds FUTEX_WAIT_REQUEUE_PI, FUTEX_CMP_REQUEUE_PI
  43 .\"     commit 52400ba946759af28442dee6265c5c0180ac7122
  44 .\"     Author: Darren Hart <dvhltc@us.ibm.com>
  45 .\"     Date:   Fri Apr 3 13:40:49 2009 -0700
  46 .\"
  47 .\"     commit ba9c22f2c01cf5c88beed5a6b9e07d42e10bd358
  48 .\"     Author: Darren Hart <dvhltc@us.ibm.com>
  49 .\"     Date:   Mon Apr 20 22:22:22 2009 -0700
  50 .\"
  51 .\"     See Documentation/futex-requeue-pi.txt
  52 .\"
  53 .\"*******************************************************************
  54 .\"
  55 .\" This file was generated with po4a. Translate the source file.
  56 .\"
  57 .\"*******************************************************************
  58 .\"
  59 .\" Japanese Version Copyright(C) 2003 Suzuki Takashi
  60 .\"         all rights reserved.
  61 .\" Translated Fri Oct 24 10:37:10 JST 2003
  62 .\"         by Suzuki Takashi.
  63 .\" Updated & Modified Sat Feb  5 14:28:53 JST 2005
  64 .\"         by Yuichi SATO <ysato444@yahoo.co.jp>, LDP v2.01
  65 .\" Updated & Modified Wed Jan  3 04:51:22 JST 2007 by Yuichi SATO, LDP v2.43
  66 .\" Updated 2013-05-01, Akihiro MOTOKI <amotoki@gmail.com>, LDP v3.51
  67 .\" Updated 2013-05-06, Akihiro MOTOKI <amotoki@gmail.com>
  68 .\"
  69 .TH FUTEX 2 2013\-12\-12 Linux "Linux Programmer's Manual"
  70 .SH 名前
  71 futex \- 高速ユーザ空間ロック
  72 .SH 書式
  73 .nf
  74 .sp
  75 \fB#include <linux/futex.h>\fP
  76 \fB#include <sys/time.h>\fP
  77 .sp
  78 \fBint futex(int *\fP\fIuaddr\fP\fB, int \fP\fIop\fP\fB, int \fP\fIval\fP\fB, const struct timespec *\fP\fItimeout\fP\fB,\fP
  79 .br
  80 .\" int *? void *? u32 *?
  81 \fB          int *\fP\fIuaddr2\fP\fB, int \fP\fIval3\fP\fB);\fP
  82 .fi
  83 .SH 説明
  84 .PP
  85 \fBfutex\fP()  システムコールは、 指定したアドレスの値が変更されるのをプログラムが待つ手段や 特定のアドレスに対して待機中のプロセスを
  86 wake (起床) させる手段を提供する (プロセスが異なれば同じメモリに対するアドレスも同じではないかもしれないが、
  87 カーネルは異なる位置にマップされた同じメモリを \fBfutex\fP()  で使えるよう内部でマップする)。 通常は、このシステムコールは
  88 \fBfutex\fP(7)  に書かれているように、 共有メモリ中のロックが競合する場合の処理を実装するのに用いられる。
  89 .PP
  90 \fBfutex\fP(7)  の操作がユーザ空間で競合なく完了しなかった場合、 カーネルに仲裁させるためにシステムコールを呼ぶ必要がある。
  91 仲裁というのは、呼び出しプロセスを sleep (起床待ち) させたり、反対に 待ちプロセスを wake させたりすることを意味する。
  92 .PP
  93 この関数を呼び出すプロセスは \fBfutex\fP(7)  に記述されているセマンティクスに忠実であることが要求される。
  94 このセマンティクスには移植不可能なアセンブリ命令を書くことが含まれる。 このことは言い換えると futex
  95 のユーザのほとんどは実際はライブラリの作者であり、 一般アプリケーションの開発者ではないということである。
  96 .PP
  97 \fIuaddr\fP 引き数は、カウンタを格納する、 アラインメントの揃った int 型変数を指している必要がある。 実行する操作は \fIop\fP
  98 引き数を介して、値 \fIval\fP とともに渡される。
  99 .PP
 100 現在のところ 5 つの操作が定義されている:
 101 .TP
 102 \fBFUTEX_WAIT\fP
 103 この操作は futex アドレス \fIuaddr\fP に指定された値 \fIval\fP がまだ格納されているかどうかを不可分操作で検証し、 sleep 状態で
 104 この futex アドレスに対して \fBFUTEX_WAKE\fP が実行されるのを待つ。 \fItimeout\fP 引き数が NULL
 105 でない場合、その内容は待ち時間の最大値を表す (この停止時間はシステムクロックの粒度に切り上げられ、
 106 カーネルのスケジューリング遅延により少しだけ長くなる可能性がある)。 NULL の場合、 呼び出しは無限に停止する。 引き数 \fIuaddr2\fP と
 107 \fIval3\fP は無視される。
 108
 109 \fBfutex\fP(7)  に照らし合わせると、この呼び出しは カウントのデクリメントで負の値 (競合を表す) になった場合に実行され、
 110 別のプロセスがその futex を解放し \fBFUTEX_WAKE\fP の操作を実行するまで sleep する。
 111 .TP
 112 \fBFUTEX_WAKE\fP
 113 この操作では指定した futex アドレスに対して待ち状態の (すなわち \fBFUTEX_WAIT\fP 中の) 最大 \fIval\fP 個のプロセスを
 114 wake させる。 引き数 \fItimeout\fP, \fIuaddr2\fP, \fIval3\fP は無視される。
 115
 116 \fBfutex\fP(4) に照らし合わせると、 この操作は カウントのインクリメントで待ちプロセスがあると判明し、 futex 値が 1 に設定された
 117 (利用可能であることを表す) 場合に実行される。
 118 .TP
 119 \fBFUTEX_FD\fP (Linux 2.6.25 以前)
 120 .\" , suitable for .BR poll (2).
 121 非同期の wake に対応するため、この操作はファイルディスクリプタを futex に 関連づける。 別のプロセスが \fBFUTEX_WAKE\fP
 122 を実行すると、プロセスは \fIval\fP で渡されたシグナル番号のシグナルを受信する。 呼び出しプロセスは使用後、返されたファイルディスクリプタを
 123 クローズしなければならない。 引き数 \fItimeout\fP, \fIuaddr2\fP, \fIval3\fP は無視される。
 124
 125 競合状態を防止するため、呼び出しプロセスは \fBFUTEX_FD\fP が返ったあと futex が up されたかどうかを確認しなければならない。
 126
 127 \fBFUTEX_FD\fP はもともと競合が起きやすかったため、 Linux 2.6.26 以降で削除されている。
 128 .TP
 129 \fBFUTEX_REQUEUE\fP (Linux 2.5.70 以降)
 130 この操作は、 \fBFUTEX_WAKE\fP が使われていて、かつ wake されている全てのプロセスが 他の futex を取得する必要がある場合に、
 131 「獣の群れの暴走 (thundering herd)」効果を避けるために導入された。 この呼び出しは \fIval\fP 個のプロセスを wake
 132 し、アドレス \fIuaddr2\fP で futex を待っている他の全てのプロセスを再度キューにいれる。 引き数 \fItimeout\fP と \fIval3\fP
 133 は無視される。
 134 .TP
 135 \fBFUTEX_CMP_REQUEUE\fP (Linux 2.6.7 以降)
 136 故意に \fBFUTEX_REQUEUE\fP を使う場合に競合が起こるため、 \fBFUTEX_CMP_REQUEUE\fP が導入された。これは
 137 \fBFUTEX_REQUEUE\fP と似ているが、場所 \fIuaddr\fP に値 \fIval3\fP がまだ保持されているかを最初にチェックする。
 138 保持されていない場合、操作はエラー \fBEAGAIN\fP で失敗する。引き数 \fItimeout\fP は無視される。
 139 .SH 返り値
 140 .PP
 141 エラーの場合、全ての操作で \-1 が返り、 \fIerrno\fP
 142 がエラーの内容を示す値に設定される。成功時の返り値は操作によって異なり、以下のリストに書かれている通りである。
 143 .TP
 144 \fBFUTEX_WAIT\fP
 145 そのプロセスが \fBFUTEX_WAKE\fP により wake された場合 0 を返す。発生する可能性があるエラーについては「エラー」の節を参照。
 146 .TP
 147 \fBFUTEX_WAKE\fP
 148 wake したプロセスの数を返す。
 149 .TP
 150 \fBFUTEX_FD\fP
 151 futex に関連づけられた新たなファイルディスクリプタを返す。
 152 .TP
 153 \fBFUTEX_REQUEUE\fP
 154 wake したプロセスの数を返す。
 155 .TP
 156 \fBFUTEX_CMP_REQUEUE\fP
 157 wake したプロセスの数を返す。
 158 .SH エラー
 159 .TP
 160 \fBEACCES\fP
 161 futex メモリに読み込みアクセス権がなかった。
 162 .TP
 163 \fBEAGAIN\fP
 164 \fBFUTEX_CMP_REQUEUE\fP で、\fIuaddr\fP が指す値が期待値 \fIval3\fP と異なる状況が検出された。
 165 (これは競合を示しているかもしれない。この場合は安全な \fBFUTEX_WAKE\fP を使うこと。)
 166 .TP
 167 \fBEFAULT\fP
 168 ユーザ空間から \fItimeout\fP の情報を取得する際にエラーが発生した。
 169 .TP
 170 \fBEINTR\fP
 171 \fBFUTEX_WAIT\fP 操作がシグナル (\fBsignal\fP(7) 参照) もしくは偽の wakeup により中断された。
 172 .TP
 173 \fBEINVAL\fP
 174 無効な引き数。
 175 .TP
 176 \fBENFILE\fP
 177 オープンされているファイルの総数がシステムの制限に達した。
 178 .TP
 179 \fBENOSYS\fP
 180 \fIop\fP に無効な操作が指定された。
 181 .TP
 182 \fBETIMEDOUT\fP
 183 \fBFUTEX_WAIT\fP 操作でタイムアウトが発生した。
 184 .TP
 185 \fBEWOULDBLOCK\fP
 186 \fIop\fP が \fBFUTEX_WAIT\fP で、その呼び出しにおいて \fIuaddr\fP が指す値が期待値 \fIval\fP と異なっていた。
 187 .SH バージョン
 188 .PP
 189 最初の futex 対応は Linux 2.5.7 で組み込まれたが、 上記のセマンティクスとは異なる。 4
 190 つの引き数のここに書かれているセマンティクスを持つ システムコールは、Linux 2.5.40 で導入された。 Linux 2.5.70 では 1
 191 つの引き数が追加された。 Linux 2.6.7 では 6 番目の引き数が追加された。 これは汚く、s390 アーキテクチャ上の特別のものである。
 192 .SH 準拠
 193 このシステムコールは Linux 固有である。
 194 .SH 注意
 195 .PP
 196 .\" .SH "AUTHORS"
 197 .\" .PP
 198 .\" Futexes were designed and worked on by
 199 .\" Hubertus Franke (IBM Thomas J. Watson Research Center),
 200 .\" Matthew Kirkwood, Ingo Molnar (Red Hat)
 201 .\" and Rusty Russell (IBM Linux Technology Center).
 202 .\" This page written by bert hubert.
 203 繰り返すが、裸の futex はエンドユーザが容易に使うことのできる概念として 意図されたものではない (glibc
 204 にはこのシステムコールに対するラッパー関数はない)。 実装者は、アセンブリ言語に慣れており、以下に挙げる futex ユーザ空間ライブラリの
 205 ソースを読み終えていることが要求される。
 206 .SH 関連項目
 207 \fBrestart_syscall\fP(2), \fBfutex\fP(7)
 208 .PP
 209 \fIFuss, Futexes and Furwocks: Fast Userlevel Locking in Linux\fP (proceedings
 210 of the Ottawa Linux Symposium 2002), online at
 211 .br
 212 .UR http://kernel.org\:/doc\:/ols\:/2002\:/ols2002\-pages\-479\-495.pdf
 213 .UE
 214 .PP
 215 futex の使用例ライブラリ, futex\-*.tar.bz2
 216 .br
 217 .UR ftp://ftp.kernel.org\:/pub\:/linux\:/kernel\:/people\:/rusty/
 218 .UE
 219 .SH この文書について
 220 この man ページは Linux \fIman\-pages\fP プロジェクトのリリース 3.65 の一部
 221 である。プロジェクトの説明とバグ報告に関する情報は
 222 http://www.kernel.org/doc/man\-pages/ に書かれている。