manual/LDP_man-pages/original/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 .TH MOVE_PAGES 2 2008-10-06 "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 .SH DESCRIPTION
  29 .BR move_pages ()
  30 moves the specified
  31 .I pages
  32 of the process
  33 .I pid
  34 to the memory nodes specified by
  35 .IR nodes .
  36 The result of the move is reflected in
  37 .IR status .
  38 The
  39 .I flags
  40 indicate constraints on the pages to be moved.
  41
  42 .I pid
  43 is the ID of the process in which pages are to be moved.
  44 To move pages in another process,
  45 the caller must be privileged
  46 .RB ( CAP_SYS_NICE )
  47 or the real or effective user ID of the calling process must match the
  48 real or saved-set user ID of the target process.
  49 If
  50 .I pid
  51 is 0 then
  52 .BR move_pages ()
  53 moves pages of the calling process.
  54
  55 .I count
  56 is the number of pages to move.
  57 It defines the size of the three arrays
  58 .IR pages ,
  59 .IR nodes ,
  60 and
  61 .IR status .
  62
  63 .I pages
  64 is an array of pointers to the pages that should be moved.
  65 These are pointers that should be aligned to page boundaries.
  66 .\" FIXME what if they are not aligned?
  67 Addresses are specified as seen by the process specified by
  68 .IR pid .
  69
  70 .I nodes
  71 is an array of integers that specify the desired location for each page.
  72 Each element in the array is a node number.
  73 .I nodes
  74 can also be NULL, in which case
  75 .BR move_pages ()
  76 does not move any pages but instead will return the node
  77 where each page currently resides, in the
  78 .I status
  79 array.
  80 Obtaining the status of each page may be necessary to determine
  81 pages that need to be moved.
  82
  83 .I status
  84 is an array of integers that return the status of each page.
  85 The array only contains valid values if
  86 .BR move_pages ()
  87 did not return an error.
  88
  89 .I flags
  90 specify what types of pages to move.
  91 .B MPOL_MF_MOVE
  92 means that only pages that are in exclusive use by the process
  93 are to be moved.
  94 .B MPOL_MF_MOVE_ALL
  95 means that pages shared between multiple processes can also be moved.
  96 The process must be privileged
  97 .RB ( CAP_SYS_NICE )
  98 to use
  99 .BR MPOL_MF_MOVE_ALL .
 100 .SH Page states in the status array
 101 The following values can be returned in each element of the
 102 .I status
 103 array.
 104 .TP
 105 .B 0..MAX_NUMNODES
 106 Identifies the node on which the page resides.
 107 .TP
 108 .B -EACCES
 109 The page is mapped by multiple processes and can only be moved if
 110 .B MPOL_MF_MOVE_ALL
 111 is specified.
 112 .TP
 113 .B -EBUSY
 114 The page is currently busy and cannot be moved.
 115 Try again later.
 116 This occurs if a page is undergoing I/O or another kernel subsystem
 117 is holding a reference to the page.
 118 .TP
 119 .B -EFAULT
 120 This is a zero page or the memory area is not mapped by the process.
 121 .TP
 122 .B -EIO
 123 Unable to write back a page.
 124 The page has to be written back
 125 in order to move it since the page is dirty and the file system
 126 does not provide a migration function that would allow the move
 127 of dirty pages.
 128 .TP
 129 .B -EINVAL
 130 A dirty page cannot be moved.
 131 The file system does not
 132 provide a migration function and has no ability to write back pages.
 133 .TP
 134 .B -ENOENT
 135 The page is not present.
 136 .TP
 137 .B -ENOMEM
 138 Unable to allocate memory on target node.
 139 .SH "RETURN VALUE"
 140 On success
 141 .BR move_pages ()
 142 returns zero.
 143 .\" FIXME Is the following quite true: does the wrapper in numactl
 144 .\" do the right thing?
 145 On error, it returns \-1, and sets
 146 .I errno
 147 to indicate the error.
 148 .SH ERRORS
 149 .TP
 150 .B E2BIG
 151 Too many pages to move.
 152 .TP
 153 .B EACCES
 154 .\" FIXME Clarify "current cpuset".  Is that the cpuset of the caller
 155 .\" or the target?
 156 One of the target nodes is not allowed by the current cpuset.
 157 .TP
 158 .B EFAULT
 159 Parameter array could not be accessed.
 160 .TP
 161 .B EINVAL
 162 Flags other than
 163 .B MPOL_MF_MOVE
 164 and
 165 .B MPOL_MF_MOVE_ALL
 166 was specified or an attempt was made to migrate pages of a kernel thread.
 167 .TP
 168 .B ENODEV
 169 One of the target nodes is not online.
 170 .TP
 171 .B ENOENT
 172 No pages were found that require moving.
 173 All pages are either already
 174 on the target node, not present, had an invalid address or could not be
 175 moved because they were mapped by multiple processes.
 176 .TP
 177 .B EPERM
 178 The caller specified
 179 .B MPOL_MF_MOVE_ALL
 180 without sufficient privileges
 181 .RB ( CAP_SYS_NICE ).
 182 Or, the caller attempted to move pages of a process belonging
 183 to another user but did not have privilege to do so
 184 .RB ( CAP_SYS_NICE ).
 185 .TP
 186 .B ESRCH
 187 Process does not exist.
 188 .SH VERSIONS
 189 .BR move_pages ()
 190 first appeared on Linux in version 2.6.18.
 191 .SH CONFORMING TO
 192 This system call is Linux-specific.
 193 .SH "NOTES"
 194 For information on library support, see
 195 .BR numa (7).
 196
 197 Use
 198 .BR get_mempolicy (2)
 199 with the
 200 .B MPOL_F_MEMS_ALLOWED
 201 flag to obtain the set of nodes that are allowed by
 202 .\" FIXME Clarify "current cpuset".  Is that the cpuset of the caller
 203 .\" or the target?
 204 the current cpuset.
 205 Note that this information is subject to change at any
 206 time by manual or automatic reconfiguration of the cpuset.
 207
 208 Use of this function may result in pages whose location
 209 (node) violates the memory policy established for the
 210 specified addresses (See
 211 .BR mbind (2)]
 212 and/or the specified process [See
 213 .BR set_mempolicy (2)).
 214 That is, memory policy does not constrain the destination
 215 nodes used by
 216 .BR move_pages ().
 217 .SH "SEE ALSO"
 218 .BR get_mempolicy (2),
 219 .BR mbind (2),
 220 .BR set_mempolicy (2),
 221 .BR numa (3),
 222 .BR numa_maps (5),
 223 .BR cpuset (7),
 224 .BR numa (7),
 225 .BR migratepages (8),
 226 .BR numa_stat (8)