release/man2/mbind.2

   1 .\" Copyright 2003,2004 Andi Kleen, SuSE Labs.
   2 .\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.
  17 .\"
  18 .\" Formatted or processed versions of this manual, if unaccompanied by
  19 .\" the source, must acknowledge the copyright and authors of this work.
  20 .\"
  21 .\" 2006-02-03, mtk, substantial wording changes and other improvements
  22 .\" 2007-08-27, Lee Schermerhorn <Lee.Schermerhorn@hp.com>
  23 .\"     more precise specification of behavior.
  24 .\"
  25 .\" Japanese Version Copyright (c) 2006 Akihiro MOTOKI
  26 .\"         all rights reserved.
  27 .\" Translated 2006-07-25, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>, LDP v2.36
  28 .\" Updated 2008-08-21, Akihiro MOTOKI, LDP v3.07
  29 .\" Updated 2008-09-19, Akihiro MOTOKI, LDP v3.08
  30 .\"
  31 .TH MBIND 2 2008-08-15 Linux "Linux Programmer's Manual"
  32 .SH 名前
  33 mbind \- メモリ領域に対してメモリポリシーを設定する
  34 .SH 書式
  35 .nf
  36 .B "#include <numaif.h>"
  37 .sp
  38 .BI "int mbind(void *" addr ", unsigned long " len  ", int " mode ,
  39 .BI "          unsigned long *" nodemask  ", unsigned long " maxnode ,
  40 .BI "          unsigned " flags );
  41 .sp
  42 \fI\-lnuma\fP でリンクする。
  43 .fi
  44 .SH 説明
  45 .BR mbind ()
  46 は、
  47 .I addr
  48 から始まる長さ
  49 .I len
  50 バイトの範囲のメモリに NUMA メモリポリシーを設定する。
  51 NUMA ポリシーはポリシーモードと 0 個以上のノードから構成される。
  52 メモリポリシーはどのノードからメモリを割り当てるかを決定する。
  53
  54 .I addr
  55 と
  56 .I len
  57 で指定されたメモリ範囲に、
  58 メモリの「無名」領域 \(em
  59 .B MAP_ANONYMOUS
  60 付きの
  61 .BR mmap (2)
  62 システムコールを使って作成されたメモリ領域 \(em や
  63 .B MAP_PRIVATE
  64 付きの
  65 .BR mmap (2)
  66 を使ってマップされたメモリマップ・ファイルが含まれている場合、
  67 ページが指定されたポリシーに基づいて割り当てられるのは、アプリケーション
  68 がそのページへの書き込み (データの格納) を行った時だけである。
  69 無名領域の場合、最初の読み出しアクセスの際には
  70 カーネル内の全データが 0 である共有ページが使用される。
  71 .B MAP_PRIVATE
  72 でマップされたファイルの場合、最初の読み出しアクセスがあると、
  73 ページ割り当てが発生するきっかけとなったプロセスのデフォルトポリシー
  74 にしたがってページの割り当てが行われる。
  75 ページ割り当てのきっかけとなったプロセスは、
  76 .BR mbind ()
  77 を呼び出したプロセスと同じとは限らない。
  78
  79 指定されたメモリ範囲内にある
  80 .B MAP_SHARED
  81 のマッピングでは指定されたポリシーは無視され、
  82 ページ割り当てが発生するきっかけとなったプロセスのデフォルトポリシーに
  83 したがってページの割り当てが行われることになる。
  84 繰り返しになるが、ページ割り当てのきっかけとなったプロセスは、
  85 .BR mbind ()
  86 を呼び出したプロセスと同じとは限らない。
  87
  88 指定されたメモリ範囲に、
  89 .BR shmget (2)
  90 システムコールを使って作成されたり、
  91 .BR shmat (2)
  92 システムコールを使って付加 (attach) されたりした共有メモリ領域が
  93 含まれる場合、無名メモリ領域や共有メモリ領域に対するページ割り当ては、
  94 共有メモリセグメントへポリシーの設定を行ったプロセスがページ割り当て
  95 のきっかけとなったかに関わらず、指定されたポリシーにしたがって割り当て
  96 が行われる。
  97 しかしながら、共有メモリ領域が
  98 .B SHM_HUGETLB
  99 フラグを指定して作成された場合には、ヒュージページ (huge page) の割り当てが
 100 指定されたポリシーにしたがって行われるのは、その領域に対して
 101 .BR mbind ()
 102 を呼び出したプロセスがページ割り当てのきっかけとなった場合のみである。
 103
 104 デフォルトでは、
 105 .BR mbind ()
 106 は新規のメモリ割り当てに対してのみ効果を持つ。
 107 ポリシーが設定される前にすでに使用されている範囲内のページに対しては、
 108 ポリシーは影響しない。
 109 このデフォルトの動作は、以下で説明するフラグ
 110 .B MPOL_MF_MOVE
 111 や
 112 .B MPOL_MF_MOVE_ALL
 113 により上書きされる可能性がある。
 114
 115 .I mode
 116 引き数には、
 117 .BR MPOL_DEFAULT ,
 118 .BR MPOL_BIND ,
 119 .BR MPOL_INTERLEAVE ,
 120 .B MPOL_PREFERRED
 121 のいずれか一つを指定しなければならない。
 122 .B MPOL_DEFAULT
 123 以外のポリシーモードの場合、呼び出し元は
 124 .I nodemask
 125 引き数でそのポリシーモードを適用するノードを指定する必要がある。
 126
 127 .I mode
 128 引き数には、追加で
 129 .I "モードフラグ"
 130 を含めることもできる。
 131 サポートされている
 132 .I "モードフラグ"
 133 は以下の通りである。
 134 .TP
 135 .BR MPOL_F_STATIC_NODES " (Linux-2.6.26 以降)"
 136 空でない
 137 .I nodemask
 138 は、物理ノード ID である。
 139 Linux では、そのプロセスが異なる CPU 集合コンテキスト (cpuset context)
 140 に移動した場合でも、そのプロセスの現在の CPU 集合コンテキストで
 141 許可されているノード集合が変化した場合でも、
 142 .I nodemask
 143 をマッピングし直すことはない。
 144 .TP
 145 .BR MPOL_F_RELATIVE_NODES " (Linux-2.6.26 以降)"
 146 空でない
 147 .I nodemask
 148 は、そのプロセスの現在の CPU 集合で許可されているノード ID 集合
 149 における相対的なノード ID である。
 150 .PP
 151 .I nodemask
 152 は、最大で
 153 .I maxnode
 154 ビットから構成されるノードのビットマスクを指す。
 155 ビットマスクの大きさは、直近の
 156 .I sizeof(unsigned long)
 157 の倍数に切り上げられるが、カーネルが使用するのは
 158 .I maxnode
 159 個までのビットだけである。
 160 NULL 値の
 161 .I nodemask
 162 もしくは値が 0 の
 163 .I maxnode
 164 はノードの空集合を表す。
 165 .I maxnode
 166 の値が 0 の場合、
 167 .I nodemask
 168 引き数は無視される。
 169 .I nodemask
 170 が必須の場面では、
 171 .I nodemask
 172 に、オンラインで、そのプロセスの現在の CPU 集合コンテキストで
 173 許可されており
 174 .RB ( MPOL_F_STATIC_NODES
 175 モードフラグが指定されていない場合)、メモリがあるノードが
 176 少なくとも一つ入っていなければならない。
 177
 178 モード
 179 .B MPOL_DEFAULT
 180 はデフォルトではないプロセスのメモリポリシーを削除し、
 181 デフォルトの動作に戻すことを指定するものである。
 182 .BR mbind ()
 183 経由で、あるメモリ領域に対して
 184 .B MPOL_DEFAULT
 185 が適用された場合、プロセスのデフォルトポリシーを使用することを意味する。
 186 プロセスのデフォルトポリシーは、
 187 .BR set_mempolicy (2)
 188 で変更されているかもしれない。
 189 プロセスのポリシーのモードも
 190 .B MPOL_DEFAULT
 191 の場合、システム全体のデフォルトポリシーが使用される。
 192 システム全体のデフォルトポリシーでは、割り当てのきっかけとなった
 193 CPU のノードからページの割り当てを行う。
 194 .B MPOL_DEFAULT
 195 では、引き数
 196 .I nodemask
 197 と
 198 .I maxnode
 199 にノードの空集合を指定しなければならない。
 200
 201 .B MPOL_BIND
 202 は厳しいポリシーで、メモリ割り当ては
 203 .I nodemask
 204 に指定されたノードに限定される。
 205 他のノードへの割り当ては行われない。
 206 .I nodemask
 207 に 2 個以上のノードが指定された場合、ページの割り当ては
 208 ノード ID が数字として最小のノードから開始され、
 209 そのノードに空きメモリがなくなるまでそのノードから
 210 ページ割り当てが行われる。そのノードに空きメモリがなくなったら、
 211 .\"motoki: the next highest は the next lowest の間違い？
 212 次に小さなノード ID を持つノードからページ割り当てが行われる。
 213 これを、
 214 .I nodemask
 215 で指定された全てのノードで空きメモリがなくなるまで繰り返す。
 216 .I nodemask
 217 で指定された以外のノードからはページの割り当ては行われない。
 218
 219 .B MPOL_INTERLEAVE
 220 は、メモリ割り当てが
 221 .I nodemask
 222 に指定されたノード間で交互に行われることを指定するものである。
 223 このポリシーでは、複数のノードにページを広げて配置し、これらのページへの
 224 メモリアクセスを分散することで、遅延ではなく、帯域を最適化する。
 225 効果を得るには、メモリ領域をある程度大きくすべきであり、
 226 メモリアクセスのパターンがかなり均一な場合でも
 227 少なくとも 1MB 以上にすべきである。
 228 このモードでも、一つのページへのアクセスに関しては
 229 一つのノードのメモリ帯域が上限となることは変わりない。
 230
 231 .B MPOL_PREFERRED
 232 は、割り当て時に優先されるノードを設定する。
 233 カーネルはまず優先ノードにページ割り当てを行おうとし、
 234 優先ノードに空きメモリが少ない場合に他のノードに割り当てを行う。
 235 .I nodemask
 236 に複数のノード ID が指定された場合は、
 237 .I nodemask
 238 内の最初のノードが優先ノードとして選択される。
 239 引き数
 240 .IR nodemask ,
 241 .I maxnode
 242 で空集合が指定された場合は、割り当てのきっかけとなった CPU のノードに
 243 メモリ割り当てが行われる。
 244 .BR mbind (2)
 245 で、あるメモリ領域に対して「ローカルからの割り当て (local allocation)」を
 246 指定する方法はこれしかない。
 247
 248 .I flags
 249 に
 250 .B MPOL_MF_STRICT
 251 が
 252 指定され、
 253 .I mode
 254 が
 255 .B MPOL_DEFAULT
 256 でない場合、
 257 指定されたポリシーに従っていないメモリ領域にページが存在すると、
 258 .BR mbind ()
 259 はエラー
 260 .B EIO
 261 で失敗する。
 262 .\" According to the kernel code, the following is not true
 263 .\" --Lee Schermerhorn
 264 .\" .\"O In 2.6.16 or later the kernel will also try to move pages
 265 .\" .\"O to the requested node with this flag.
 266 .\" 2.6.16 以降のカーネルでは、このフラグで要求されたノードに
 267 .\" ページを移動しようとする。
 268
 269 .I flags
 270 に
 271 .B MPOL_MF_MOVE
 272 が指定されると、カーネルはそのメモリ領域内の既存の全てのページを移動し、
 273 指定されたポリシーに従うようにしようとする。
 274 他のプロセスと共有されているページは移動されない。
 275 .B MPOL_MF_STRICT
 276 も指定された場合、移動できなかったページがあると、
 277 .BR mbind ()
 278 はエラー
 279 .B EIO
 280 で失敗する。
 281
 282 .I flags
 283 に
 284 .B MPOL_MF_MOVE_ALL
 285 が指定されると、カーネルはそのメモリ領域内の既存の全てのページを、
 286 他のプロセスがページを使用しているかどうかに関わらず移動する。
 287 このフラグを使用するには、呼び出し元のプロセスは特権
 288 .RB ( CAP_SYS_NICE )
 289 を持っていなければならない。
 290 .B MPOL_MF_STRICT
 291 も指定された場合、移動できなかったページがあると、
 292 .BR mbind ()
 293 はエラー
 294 .B EIO
 295 で失敗する。
 296 .\" ---------------------------------------------------------------
 297 .SH 返り値
 298 成功すると、
 299 .BR mbind ()
 300 は 0 を返す。エラーの場合、\-1 を返し、
 301 .I errno
 302 にエラーを示す値を設定する。
 303 .\" ---------------------------------------------------------------
 304 .SH エラー
 305 .\"  I think I got all of the error returns.  --Lee Schermerhorn
 306 .TP
 307 .B EFAULT
 308 .I nodemask
 309 と
 310 .I maxnode
 311 で指定されたメモリ領域の一部または全部が、
 312 呼び出し元がアクセス可能なアドレス空間外を指している。
 313 もしくは指定されたメモリ領域にマップされていない部分 (unmapped hole)
 314 があった、
 315 .TP
 316 .B EINVAL
 317 .I flags
 318 や
 319 .I mode
 320 に不正な値が指定された。
 321 .I addr + len
 322 が
 323 .I addr
 324 より小さい。
 325 .I addr
 326 がシステムのページサイズの倍数になっていない。
 327 または
 328 .I mode
 329 が
 330 .B MPOL_DEFAULT
 331 で
 332 .I nodemask
 333 に空でない集合が指定された。
 334 .I mode
 335 が
 336 .B MPOL_BIND
 337 か
 338 .B MPOL_INTERLEAVE
 339 で
 340 .I nodemask
 341 が空であった。
 342 .I maxnode
 343 がカーネルに適用された上限を超えている。
 344 .\" As at 2.6.23, this limit is "a page worth of bits", e.g.,
 345 .\" 8 * 4096 bits, assuming a 4kB page size.
 346 .I nodemask
 347 に、サポートされている最大ノード ID より大きいノードが指定された。
 348 .I nodemask
 349 に、オンラインで、かつそのプロセスの現在の CPU 集合コンテキストで
 350 許可されているノードが一つも含まれていないか、
 351 メモリを含むノードが一つも指定されていない。
 352 .I mode
 353 引き数に
 354 .B MPOL_F_STATIC_NODES
 355 と
 356 .B MPOL_F_RELATIVE_NODES
 357 の両方が指定された。
 358 .TP
 359 .B EIO
 360 .B MPOL_MF_STRICT
 361 が指定されたが、このポリシーに従っていないノードに
 362 すでにページが存在していた。
 363 もしくは
 364 .B MPOL_MF_MOVE
 365 か
 366 .B MPOL_MF_MOVE_ALL
 367 が指定されたが、カーネルが指定された領域内の既存の全てのページを
 368 移動することができなかった。
 369 .TP
 370 .B ENOMEM
 371 利用可能なカーネルメモリが十分なかった。
 372 .TP
 373 .B EPERM
 374 .I flags
 375 引き数に
 376 .B MPOL_MF_MOVE_ALL
 377 フラグが含まれているが、呼び出し元が
 378 .B CAP_SYS_NICE
 379 特権を持たない。
 380 .\" ---------------------------------------------------------------
 381 .SH バージョン
 382 .BR mbind ()
 383 システムコールはバージョン 2.6.7 で Linux カーネルに追加された。
 384 .SH 準拠
 385 このシステムコールは Linux 独自である。
 386 .SH 注意
 387 ライブラリによるサポートについては
 388 .BR numa (7)
 389 を参照。
 390
 391 NUMA ポリシーは、
 392 .B MAP_SHARED
 393 フラグが指定されてマップされたメモリマップ・ファイルの領域では
 394 サポートされていない。
 395
 396 .B MPOL_DEFAULT
 397 モードは、
 398 .BR mbind ()
 399 と
 400 .BR set_mempolicy (2)
 401 で異なる効果を持つことができる。
 402 .BR set_mempolicy (2)
 403 で
 404 .B MPOL_DEFAULT
 405 が指定された場合、そのプロセスのポリシーはシステムの
 406 デフォルトポリシー、すなわちローカルからの割り当て、に戻る。
 407 .BR mbind ()
 408 を使ってメモリのある領域に
 409 .B MPOL_DEFAULT
 410 が指定された場合、その範囲に対してそれ以降に行われるページの割り当てでは、
 411 .BR set_mempolicy (2)
 412 で設定したのと同じように、そのプロセスのポリシーが適用される。
 413 .\"0motoki: possibly nondefault policy は default policy の間違い？
 414 これにより、特定のメモリ領域についてだけ明示的なポリシーを削除し、
 415 デフォルトのポリシーに「戻す」ことができる。
 416 あるメモリ領域に対して「ローカルからの割り当て」を明示的に設定するには、
 417 .I mode
 418 に
 419 .B MPOL_PREFERRED
 420 を指定し、
 421 .I nodemask
 422 に空集合のノードを指定すればよい。
 423 この方法は
 424 .BR set_mempolicy (2)
 425 でも通用する。
 426
 427 2.6.16 でヒュージページ・ポリシーへの対応が追加された。
 428 インターリーブ・ポリシーがヒュージページのマッピングで効果を持つには、
 429 ポリシーが適用されるメモリが数十メガバイト以上である必要がある。
 430
 431 .B MPOL_MF_STRICT
 432 はヒュージページのマッピングでは無視される。
 433
 434 .B MPOL_MF_MOVE
 435 と
 436 .B MPOL_MF_MOVE_ALL
 437 は Linux 2.6.16 以降でのみ利用可能である。
 438 .SH 関連項目
 439 .BR get_mempolicy (2),
 440 .BR getcpu (2),
 441 .BR mmap (2),
 442 .BR set_mempolicy (2),
 443 .BR shmat (2),
 444 .BR shmget (2),
 445 .BR numa (3),
 446 .BR cpuset (7),
 447 .BR numa (7),
 448 .BR numactl (8)