original/man2/move_pages.2

   1 .\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc.
   2 .\"                               Christoph Lameter
   3 .\"
   4 .\" %%%LICENSE_START(VERBATIM_TWO_PARA)
   5 .\" Permission is granted to make and distribute verbatim copies of this
   6 .\" manual provided the copyright notice and this permission notice are
   7 .\" preserved on all copies.
   8 .\"
   9 .\" Permission is granted to copy and distribute modified versions of this
  10 .\" manual under the conditions for verbatim copying, provided that the
  11 .\" entire resulting derived work is distributed under the terms of a
  12 .\" permission notice identical to this one.
  13 .\" %%%LICENSE_END
  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 .TH MOVE_PAGES 2 2010-06-11 "Linux" "Linux Programmer's Manual"
  19 .SH NAME
  20 move_pages \- move individual pages of a process to another node
  21 .SH SYNOPSIS
  22 .nf
  23 .B #include <numaif.h>
  24 .sp
  25 .BI "long move_pages(int " pid ", unsigned long count, void **" pages ,
  26 .BI "                const int *" nodes ", int *" status ", int " flags );
  27 .fi
  28 .sp
  29 Link with \fI\-lnuma\fP.
  30 .SH DESCRIPTION
  31 .BR move_pages ()
  32 moves the specified
  33 .I pages
  34 of the process
  35 .I pid
  36 to the memory nodes specified by
  37 .IR nodes .
  38 The result of the move is reflected in
  39 .IR status .
  40 The
  41 .I flags
  42 indicate constraints on the pages to be moved.
  43
  44 .I pid
  45 is the ID of the process in which pages are to be moved.
  46 To move pages in another process,
  47 the caller must be privileged
  48 .RB ( CAP_SYS_NICE )
  49 or the real or effective user ID of the calling process must match the
  50 real or saved-set user ID of the target process.
  51 If
  52 .I pid
  53 is 0, then
  54 .BR move_pages ()
  55 moves pages of the calling process.
  56
  57 .I count
  58 is the number of pages to move.
  59 It defines the size of the three arrays
  60 .IR pages ,
  61 .IR nodes ,
  62 and
  63 .IR status .
  64
  65 .I pages
  66 is an array of pointers to the pages that should be moved.
  67 These are pointers that should be aligned to page boundaries.
  68 .\" FIXME what if they are not aligned?
  69 Addresses are specified as seen by the process specified by
  70 .IR pid .
  71
  72 .I nodes
  73 is an array of integers that specify the desired location for each page.
  74 Each element in the array is a node number.
  75 .I nodes
  76 can also be NULL, in which case
  77 .BR move_pages ()
  78 does not move any pages but instead will return the node
  79 where each page currently resides, in the
  80 .I status
  81 array.
  82 Obtaining the status of each page may be necessary to determine
  83 pages that need to be moved.
  84
  85 .I status
  86 is an array of integers that return the status of each page.
  87 The array contains valid values only if
  88 .BR move_pages ()
  89 did not return an error.
  90
  91 .I flags
  92 specify what types of pages to move.
  93 .B MPOL_MF_MOVE
  94 means that only pages that are in exclusive use by the process
  95 are to be moved.
  96 .B MPOL_MF_MOVE_ALL
  97 means that pages shared between multiple processes can also be moved.
  98 The process must be privileged
  99 .RB ( CAP_SYS_NICE )
 100 to use
 101 .BR MPOL_MF_MOVE_ALL .
 102 .SS Page states in the status array
 103 The following values can be returned in each element of the
 104 .I status
 105 array.
 106 .TP
 107 .B 0..MAX_NUMNODES
 108 Identifies the node on which the page resides.
 109 .TP
 110 .B -EACCES
 111 The page is mapped by multiple processes and can be moved only if
 112 .B MPOL_MF_MOVE_ALL
 113 is specified.
 114 .TP
 115 .B -EBUSY
 116 The page is currently busy and cannot be moved.
 117 Try again later.
 118 This occurs if a page is undergoing I/O or another kernel subsystem
 119 is holding a reference to the page.
 120 .TP
 121 .B -EFAULT
 122 This is a zero page or the memory area is not mapped by the process.
 123 .TP
 124 .B -EIO
 125 Unable to write back a page.
 126 The page has to be written back
 127 in order to move it since the page is dirty and the filesystem
 128 does not provide a migration function that would allow the move
 129 of dirty pages.
 130 .TP
 131 .B -EINVAL
 132 A dirty page cannot be moved.
 133 The filesystem does not
 134 provide a migration function and has no ability to write back pages.
 135 .TP
 136 .B -ENOENT
 137 The page is not present.
 138 .TP
 139 .B -ENOMEM
 140 Unable to allocate memory on target node.
 141 .SH RETURN VALUE
 142 On success
 143 .BR move_pages ()
 144 returns zero.
 145 .\" FIXME Is the following quite true: does the wrapper in numactl
 146 .\" do the right thing?
 147 On error, it returns \-1, and sets
 148 .I errno
 149 to indicate the error.
 150 .SH ERRORS
 151 .TP
 152 .B E2BIG
 153 Too many pages to move.
 154 .TP
 155 .B EACCES
 156 .\" FIXME Clarify "current cpuset".  Is that the cpuset of the caller
 157 .\" or the target?
 158 One of the target nodes is not allowed by the current cpuset.
 159 .TP
 160 .B EFAULT
 161 Parameter array could not be accessed.
 162 .TP
 163 .B EINVAL
 164 Flags other than
 165 .B MPOL_MF_MOVE
 166 and
 167 .B MPOL_MF_MOVE_ALL
 168 was specified or an attempt was made to migrate pages of a kernel thread.
 169 .TP
 170 .B ENODEV
 171 One of the target nodes is not online.
 172 .TP
 173 .B ENOENT
 174 No pages were found that require moving.
 175 All pages are either already
 176 on the target node, not present, had an invalid address or could not be
 177 moved because they were mapped by multiple processes.
 178 .TP
 179 .B EPERM
 180 The caller specified
 181 .B MPOL_MF_MOVE_ALL
 182 without sufficient privileges
 183 .RB ( CAP_SYS_NICE ).
 184 Or, the caller attempted to move pages of a process belonging
 185 to another user but did not have privilege to do so
 186 .RB ( CAP_SYS_NICE ).
 187 .TP
 188 .B ESRCH
 189 Process does not exist.
 190 .SH VERSIONS
 191 .BR move_pages ()
 192 first appeared on Linux in version 2.6.18.
 193 .SH CONFORMING TO
 194 This system call is Linux-specific.
 195 .SH NOTES
 196 For information on library support, see
 197 .BR numa (7).
 198
 199 Use
 200 .BR get_mempolicy (2)
 201 with the
 202 .B MPOL_F_MEMS_ALLOWED
 203 flag to obtain the set of nodes that are allowed by
 204 .\" FIXME Clarify "current cpuset".  Is that the cpuset of the caller
 205 .\" or the target?
 206 the current cpuset.
 207 Note that this information is subject to change at any
 208 time by manual or automatic reconfiguration of the cpuset.
 209
 210 Use of this function may result in pages whose location
 211 (node) violates the memory policy established for the
 212 specified addresses (See
 213 .BR mbind (2))
 214 and/or the specified process (See
 215 .BR set_mempolicy (2)).
 216 That is, memory policy does not constrain the destination
 217 nodes used by
 218 .BR move_pages ().
 219
 220 The
 221 .I <numaif.h>
 222 header is not included with glibc, but requires installing
 223 .I libnuma-devel
 224 or a similar package.
 225 .SH SEE ALSO
 226 .BR get_mempolicy (2),
 227 .BR mbind (2),
 228 .BR set_mempolicy (2),
 229 .BR numa (3),
 230 .BR numa_maps (5),
 231 .BR cpuset (7),
 232 .BR numa (7),
 233 .BR migratepages (8),
 234 .BR numastat (8)
 235 .SH COLOPHON
 236 This page is part of release 3.67 of the Linux
 237 .I man-pages
 238 project.
 239 A description of the project,
 240 information about reporting bugs,
 241 and the latest version of this page,
 242 can be found at
 243 \%http://www.kernel.org/doc/man\-pages/.