draft/man2/move_pages.2

   1 .\" Hey Emacs! This file is -*- nroff -*- source.
   2 .\"
   3 .\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc.
   4 .\"                               Christoph Lameter
   5 .\"
   6 .\" Permission is granted to make and distribute verbatim copies of this
   7 .\" manual provided the copyright notice and this permission notice are
   8 .\" preserved on all copies.
   9 .\"
  10 .\" Permission is granted to copy and distribute modified versions of this
  11 .\" manual under the conditions for verbatim copying, provided that the
  12 .\" entire resulting derived work is distributed under the terms of a
  13 .\" permission notice identical to this one.
  14 .\"
  15 .\" FIXME Should programs normally be using this API directly, or should
  16 .\" they rather be using interfaces in the numactl package?
  17 .\" (e.g., compare with recommendation in mbind(2)).
  18 .\"
  19 .\" Japanese Version Copyright (c) 2008  Akihiro MOTOKI
  20 .\"         all rights reserved.
  21 .\" Translated 2008-10-26, Akihiro MOTOKI <amotoki@dd.iij4u.or.jp>
  22 .\"
  23 .TH MOVE_PAGES 2 2010-06-11 "Linux" "Linux Programmer's Manual"
  24 .\"O .SH NAME
  25 .SH 名前
  26 .\"O move_pages \- move individual pages of a process to another node
  27 move_pages \- あるプロセスの個々のページを別のノードに移動する
  28 .\"O .SH SYNOPSIS
  29 .SH 書式
  30 .nf
  31 .B #include <numaif.h>
  32 .sp
  33 .BI "long move_pages(int " pid ", unsigned long count, void **" pages ,
  34 .BI "                const int *" nodes ", int *" status ", int " flags );
  35 .fi
  36 .sp
  37 .\"O Link with \fI\-lnuma\fP.
  38 \fI\-lnuma\fP とリンクする。
  39 .\"O .SH DESCRIPTION
  40 .SH 説明
  41 .\"O .BR move_pages ()
  42 .\"O moves the specified
  43 .\"O .I pages
  44 .\"O of the process
  45 .\"O .I pid
  46 .\"O to the memory nodes specified by
  47 .\"O .IR nodes .
  48 .\"O The result of the move is reflected in
  49 .\"O .IR status .
  50 .\"O The
  51 .\"O .I flags
  52 .\"O indicate constraints on the pages to be moved.
  53 .BR move_pages ()
  54 は、プロセス
  55 .I pid
  56 の指定されたページ
  57 .I pages
  58 を
  59 .I nodes
  60 で指定されたメモリノードに移動する。
  61 移動の結果は
  62 .I status
  63 に反映される。
  64 .I flags
  65 では移動されるページに関する制約を指定する。
  66
  67 .\"O .I pid
  68 .\"O is the ID of the process in which pages are to be moved.
  69 .\"O To move pages in another process,
  70 .\"O the caller must be privileged
  71 .\"O .RB ( CAP_SYS_NICE )
  72 .\"O or the real or effective user ID of the calling process must match the
  73 .\"O real or saved-set user ID of the target process.
  74 .\"O If
  75 .\"O .I pid
  76 .\"O is 0, then
  77 .\"O .BR move_pages ()
  78 .\"O moves pages of the calling process.
  79 .I pid
  80 は、移動されるページが属するプロセスの ID である。
  81 別のプロセスのページを移動するためには、呼び出し元が特権
  82 .RB ( CAP_SYS_NICE )
  83 を持っているか、呼び出したプロセスの実ユーザ ID か実効ユーザ ID が
  84 ページ移動対象のプロセスの実ユーザ ID か保存 set-user-ID のどちらかと
  85 一致しなければならない。
  86 .I pid
  87 が 0 の場合、
  88 .BR move_pages ()
  89 は呼び出したプロセスのページを移動する。
  90
  91 .\"O .I count
  92 .\"O is the number of pages to move.
  93 .\"O It defines the size of the three arrays
  94 .\"O .IR pages ,
  95 .\"O .IR nodes ,
  96 .\"O and
  97 .\"O .IR status .
  98 .I count
  99 は移動するページ数である。
 100 .I count
 101 により
 102 .IR pages ,
 103 .IR nodes ,
 104 .I status
 105 の 3 つの配列の大きさが定義される。
 106
 107 .\"O .I pages
 108 .\"O is an array of pointers to the pages that should be moved.
 109 .\"O These are pointers that should be aligned to page boundaries.
 110 .I pages
 111 は、移動すべきページへのポインタの配列であり、
 112 各ポインタはページ境界に揃えた値を指定すべきである。
 113 .\" FIXME what if they are not aligned?
 114 .\"O Addresses are specified as seen by the process specified by
 115 .\"O .IR pid .
 116 .I pid
 117 で指定されたプロセスで見えるアドレスを指定する。
 118
 119 .\"O .I nodes
 120 .\"O is an array of integers that specify the desired location for each page.
 121 .\"O Each element in the array is a node number.
 122 .\"O .I nodes
 123 .\"O can also be NULL, in which case
 124 .\"O .BR move_pages ()
 125 .\"O does not move any pages but instead will return the node
 126 .\"O where each page currently resides, in the
 127 .\"O .I status
 128 .\"O array.
 129 .\"O Obtaining the status of each page may be necessary to determine
 130 .\"O pages that need to be moved.
 131 .I nodes
 132 は、各ページの希望の移動場所を示す整数値の配列であり、
 133 配列の各要素はノード番号である。
 134 .I nodes
 135 には NULL を指定することもでき、この場合には
 136 .BR move_pages ()
 137 はどのページも移動しないが、各ページが現在配置されているノードを配列
 138 .I status
 139 に格納して返す。どのページを移動する必要があるかを判断するために、
 140 各ページの状態の取得が必要な場合もある。
 141
 142 .\"O .I status
 143 .\"O is an array of integers that return the status of each page.
 144 .\"O The array only contains valid values if
 145 .\"O .BR move_pages ()
 146 .\"O did not return an error.
 147 .I status
 148 は、各ページの状態を表す整数値の配列である。
 149 この配列に有効な値が格納されるのは、
 150 .BR move_pages ()
 151 がエラーを返さなかった場合だけである。
 152
 153 .\"O .I flags
 154 .\"O specify what types of pages to move.
 155 .\"O .B MPOL_MF_MOVE
 156 .\"O means that only pages that are in exclusive use by the process
 157 .\"O are to be moved.
 158 .\"O .B MPOL_MF_MOVE_ALL
 159 .\"O means that pages shared between multiple processes can also be moved.
 160 .\"O The process must be privileged
 161 .\"O .RB ( CAP_SYS_NICE )
 162 .\"O to use
 163 .\"O .BR MPOL_MF_MOVE_ALL .
 164 .I flags
 165 には、どの種類のページを移動するかを指定する。
 166 .B MPOL_MF_MOVE
 167 は、そのプロセスが排他的に使用しているページだけを移動することを意味する。
 168 .B MPOL_MF_MOVE_ALL
 169 は、複数のプロセス間で共有されているページも移動できることを意味する。
 170 .B MPOL_MF_MOVE_ALL
 171 を使用するためには、そのプロセスが特権
 172 .RB ( CAP_SYS_NICE )
 173 を持っていなければならない。
 174 .\"O .SH Page states in the status array
 175 .SH status 配列に格納されるページ状態
 176 .\"O The following values can be returned in each element of the
 177 .\"O .I status
 178 .\"O array.
 179 .I status
 180 配列の各要素として、以下の値が返される。
 181 .TP
 182 .B 0..MAX_NUMNODES
 183 .\"O Identifies the node on which the page resides.
 184 そのページが配置されているノードを示す。
 185 .TP
 186 .B -EACCES
 187 .\"O The page is mapped by multiple processes and can only be moved if
 188 .\"O .B MPOL_MF_MOVE_ALL
 189 .\"O is specified.
 190 そのページは複数のプロセスによりマップされており、
 191 .B MPOL_MF_MOVE_ALL
 192 が指定された場合にのみ移動できる。
 193 .TP
 194 .B -EBUSY
 195 .\"O The page is currently busy and cannot be moved.
 196 .\"O Try again later.
 197 .\"O This occurs if a page is undergoing I/O or another kernel subsystem
 198 .\"O is holding a reference to the page.
 199 そのページが現在ビジーであり、移動できない。後でもう一度試すこと。
 200 この状況は、ページが I/O の実行中であったり、カーネルの他のサブシステム
 201 がそのページへの参照を保持している場合に発生する。
 202 .TP
 203 .B -EFAULT
 204 .\"O This is a zero page or the memory area is not mapped by the process.
 205 そのページが zero page であるか、そのメモリ領域はそのプロセスにより
 206 マップされていない。
 207 .TP
 208 .B -EIO
 209 .\"O Unable to write back a page.
 210 .\"O The page has to be written back
 211 .\"O in order to move it since the page is dirty and the file system
 212 .\"O does not provide a migration function that would allow the move
 213 .\"O of dirty pages.
 214 ページを書き戻す (write back) ことができない。
 215 ページが dirty で、ファイルシステムが dirty なページを移動できるような
 216 移動機能を提供していないため、そのページを移動するためにはページを
 217 書き戻さなければならない。
 218 .TP
 219 .B -EINVAL
 220 .\"O A dirty page cannot be moved.
 221 .\"O The file system does not
 222 .\"O provide a migration function and has no ability to write back pages.
 223 dirty なページを移動できない。
 224 ファイルシステムが dirty なページを移動するための機能を提供しておらず、
 225 ページを書き戻す能力もない。
 226 .TP
 227 .B -ENOENT
 228 .\"O The page is not present.
 229 ページが存在しない。
 230 .TP
 231 .B -ENOMEM
 232 .\"O Unable to allocate memory on target node.
 233 移動先のノードでメモリを確保することができない。
 234 .\"O .SH "RETURN VALUE"
 235 .SH 返り値
 236 .\"O On success
 237 .\"O .BR move_pages ()
 238 .\"O returns zero.
 239 成功すると、
 240 .BR move_pages ()
 241 は 0 を返す。
 242 .\" FIXME Is the following quite true: does the wrapper in numactl
 243 .\" do the right thing?
 244 .\"O On error, it returns \-1, and sets
 245 .\"O .I errno
 246 .\"O to indicate the error.
 247 エラーの場合、\-1 を返し、
 248 .I errno
 249 にエラーを示す値を設定する。
 250 .\"O .SH ERRORS
 251 .SH エラー
 252 .TP
 253 .B E2BIG
 254 .\"O Too many pages to move.
 255 移動すべきページが多過ぎる。
 256 .TP
 257 .B EACCES
 258 .\" FIXME Clarify "current cpuset".  Is that the cpuset of the caller
 259 .\" or the target?
 260 .\"O One of the target nodes is not allowed by the current cpuset.
 261 移動先のノードのいずれかが現在の CPU 集合では許可されていない。
 262 .TP
 263 .B EFAULT
 264 .\"O Parameter array could not be accessed.
 265 パラメータ配列にアクセスできなかった。
 266 .TP
 267 .B EINVAL
 268 .\"O Flags other than
 269 .\"O .B MPOL_MF_MOVE
 270 .\"O and
 271 .\"O .B MPOL_MF_MOVE_ALL
 272 .\"O was specified or an attempt was made to migrate pages of a kernel thread.
 273 .I flags
 274 に
 275 .B MPOL_MF_MOVE
 276 でも
 277 .B MPOL_MF_MOVE_ALL
 278 でもない値が指定されたか、カーネルスレッドのページを移動させようとした。
 279 .TP
 280 .B ENODEV
 281 .\"O One of the target nodes is not online.
 282 移動先のノードのいずれかがオンラインでない。
 283 .TP
 284 .B ENOENT
 285 .\"O No pages were found that require moving.
 286 .\"O All pages are either already
 287 .\"O on the target node, not present, had an invalid address or could not be
 288 .\"O moved because they were mapped by multiple processes.
 289 移動が必要なページが全く見つからなかった。
 290 指定された全てのページが、すでに移動先のノードに存在するか、存在しないか、
 291 無効なアドレスであったか、複数のプロセスによってマップされていて移動でき
 292 なかったか、のいずれかであった。
 293 .TP
 294 .B EPERM
 295 .\"O The caller specified
 296 .\"O .B MPOL_MF_MOVE_ALL
 297 .\"O without sufficient privileges
 298 .\"O .RB ( CAP_SYS_NICE ).
 299 .\"O Or, the caller attempted to move pages of a process belonging
 300 .\"O to another user but did not have privilege to do so
 301 .\"O .RB ( CAP_SYS_NICE ).
 302 呼び出し元は
 303 .B MPOL_MF_MOVE_ALL
 304 を指定したが、十分な特権
 305 .RB ( CAP_SYS_NICE )
 306 を持っていない。
 307 または、呼び出し元が他のユーザに属するプロセスのページを移動しようとしたが、
 308 それを行えるだけの特権
 309 .RB ( CAP_SYS_NICE )
 310 を持っていなかった。
 311 .TP
 312 .B ESRCH
 313 .\"O Process does not exist.
 314 プロセスが存在しない。
 315 .\"O .SH VERSIONS
 316 .SH バージョン
 317 .\"O .BR move_pages ()
 318 .\"O first appeared on Linux in version 2.6.18.
 319 .BR move_pages ()
 320 は、バージョン 2.6.18 で初めて Linux に登場した。
 321 .\"O .SH CONFORMING TO
 322 .SH 準拠
 323 .\"O This system call is Linux-specific.
 324 このシステムコールは Linux 固有である。
 325 .\"O .SH "NOTES"
 326 .SH 注意
 327 .\"O For information on library support, see
 328 .\"O .BR numa (7).
 329 ライブラリによるサポートについては
 330 .BR numa (7)
 331 を参照。
 332
 333 .\"O Use
 334 .\"O .BR get_mempolicy (2)
 335 .\"O with the
 336 .\"O .B MPOL_F_MEMS_ALLOWED
 337 .\"O flag to obtain the set of nodes that are allowed by
 338 .\" FIXME Clarify "current cpuset".  Is that the cpuset of the caller
 339 .\" or the target?
 340 .\"O the current cpuset.
 341 .\"O Note that this information is subject to change at any
 342 .\"O time by manual or automatic reconfiguration of the cpuset.
 343 現在の CPU 集合で許可されているノードの集合を取得するには、フラグ
 344 .B MPOL_F_MEMS_ALLOWED
 345 を指定して
 346 .BR get_mempolicy (2)
 347 を使用すればよい。
 348 取得した情報は、CPU 集合の手動または自動での再構成により
 349 いつ何時変化してしまうか分からない。
 350
 351 .\"O Use of this function may result in pages whose location
 352 .\"O (node) violates the memory policy established for the
 353 .\"O specified addresses (See
 354 .\"O .BR mbind (2))
 355 .\"O and/or the specified process (See
 356 .\"O .BR set_mempolicy (2)).
 357 .\"O That is, memory policy does not constrain the destination
 358 .\"O nodes used by
 359 .\"O .BR move_pages ().
 360 この関数を使用すると、ページの位置 (ノード) が
 361 指定されたアドレスに対して設定されたメモリポリシー
 362 .RB ( mbind (2)
 363 参照) や指定されたプロセスに対して設定されたメモリポリシー
 364 .RB ( set_mempolicy (2)
 365 参照) に違反してしまう可能性がある。
 366 つまり、メモリポリシーは
 367 .BR move_pages ()
 368 で使われる移動先ノードを制限しないということである。
 369
 370 .\"O The
 371 .\"O .I <numaif.h>
 372 .\"O header is not included with glibc, but requires installing
 373 .\"O .I libnuma-devel
 374 .\"O or a similar package.
 375 ヘッダファイル
 376 .I <numaif.h>
 377 は glibc には含まれておらず、
 378 .I libnuma-devel
 379 か同様のパッケージをインストールする必要がある。
 380 .\"O .SH "SEE ALSO"
 381 .SH 関連項目
 382 .BR get_mempolicy (2),
 383 .BR mbind (2),
 384 .BR set_mempolicy (2),
 385 .BR numa (3),
 386 .BR numa_maps (5),
 387 .BR cpuset (7),
 388 .BR numa (7),
 389 .BR migratepages (8),
 390 .BR numa_stat (8)