man2/migrate_pages.2

   1 .\" Copyright 2009 Intel Corporation
   2 .\"                Author: Andi Kleen
   3 .\" Based on the move_pages manpage which was
   4 .\" This manpage is Copyright (C) 2006 Silicon Graphics, Inc.
   5 .\"                               Christoph Lameter
   6 .\"
   7 .\" %%%LICENSE_START(VERBATIM_TWO_PARA)
   8 .\" Permission is granted to make and distribute verbatim copies of this
   9 .\" manual provided the copyright notice and this permission notice are
  10 .\" preserved on all copies.
  11 .\"
  12 .\" Permission is granted to copy and distribute modified versions of this
  13 .\" manual under the conditions for verbatim copying, provided that the
  14 .\" entire resulting derived work is distributed under the terms of a
  15 .\" permission notice identical to this one.
  16 .\" %%%LICENSE_END
  17 .\"
  18 .TH MIGRATE_PAGES 2 2015-02-21 "Linux" "Linux Programmer's Manual"
  19 .SH NAME
  20 migrate_pages \- move all pages in a process to another set of nodes
  21 .SH SYNOPSIS
  22 .nf
  23 .B #include <numaif.h>
  24 .sp
  25 .BI "long migrate_pages(int " pid ", unsigned long " maxnode,
  26 .BI "                   const unsigned long *" old_nodes,
  27 .BI "                   const unsigned long *" new_nodes );
  28 .fi
  29 .sp
  30 Link with \fI\-lnuma\fP.
  31 .SH DESCRIPTION
  32 .BR migrate_pages ()
  33 attempts to move all pages of the process
  34 .I pid
  35 that are in memory nodes
  36 .I old_nodes
  37 to the memory nodes in
  38 .IR new_nodes .
  39 Pages not located in any node in
  40 .I old_nodes
  41 will not be migrated.
  42 As far as possible,
  43 the kernel maintains the relative topology relationship inside
  44 .I old_nodes
  45 during the migration to
  46 .IR new_nodes .
  47
  48 The
  49 .I old_nodes
  50 and
  51 .I new_nodes
  52 arguments are pointers to bit masks of node numbers, with up to
  53 .I maxnode
  54 bits in each mask.
  55 These masks are maintained as arrays of unsigned
  56 .I long
  57 integers (in the last
  58 .I long
  59 integer, the bits beyond those specified by
  60 .I maxnode
  61 are ignored).
  62 The
  63 .I maxnode
  64 argument is the maximum node number in the bit mask plus one (this is the same
  65 as in
  66 .BR mbind (2),
  67 but different from
  68 .BR select (2)).
  69
  70 The
  71 .I pid
  72 argument is the ID of the process whose pages are to be moved.
  73 To move pages in another process,
  74 the caller must be privileged
  75 .RB ( CAP_SYS_NICE )
  76 or the real or effective user ID of the calling process must match the
  77 real or saved-set user ID of the target process.
  78 If
  79 .I pid
  80 is 0, then
  81 .BR migrate_pages ()
  82 moves pages of the calling process.
  83
  84 Pages shared with another process will be moved only if the initiating
  85 process has the
  86 .B CAP_SYS_NICE
  87 privilege.
  88 .SH RETURN VALUE
  89 On success
  90 .BR migrate_pages ()
  91 returns the number of pages that could not be moved
  92 (i.e., a return of zero means that all pages were successfully moved).
  93 On error, it returns \-1, and sets
  94 .I errno
  95 to indicate the error.
  96 .SH ERRORS
  97 .TP
  98 .B EFAULT
  99 Part or all of the memory range specified by
 100 .IR old_nodes / new_nodes
 101 and
 102 .I maxnode
 103 points outside your accessible address space.
 104 .TP
 105 .B EINVAL
 106 The value specified by
 107 .I maxnode
 108 exceeds a kernel-imposed limit.
 109 .\" As at 3.5, this limit is "a page worth of bits", e.g.,
 110 .\" 8 * 4096 bits, assuming a 4kB page size.
 111 Or,
 112 .I old_nodes
 113 or
 114 .I new_nodes
 115 specifies one or more node IDs that are
 116 greater than the maximum supported node ID.
 117 Or, none of the node IDs specified by
 118 .I new_nodes
 119 are on-line and allowed by the process's current cpuset context,
 120 or none of the specified nodes contain memory.
 121 .TP
 122 .B EPERM
 123 Insufficient privilege
 124 .RB ( CAP_SYS_NICE )
 125 to move pages of the process specified by
 126 .IR pid ,
 127 or insufficient privilege
 128 .RB ( CAP_SYS_NICE )
 129 to access the specified target nodes.
 130 .TP
 131 .B ESRCH
 132 No process matching
 133 .I pid
 134 could be found.
 135 .\" FIXME Document the other errors that can occur for migrate_pages()
 136 .SH VERSIONS
 137 The
 138 .BR migrate_pages ()
 139 system call first appeared on Linux in version 2.6.16.
 140 .SH CONFORMING TO
 141 This system call is Linux-specific.
 142 .SH NOTES
 143 For information on library support, see
 144 .BR numa (7).
 145
 146 Use
 147 .BR get_mempolicy (2)
 148 with the
 149 .B MPOL_F_MEMS_ALLOWED
 150 flag to obtain the set of nodes that are allowed by
 151 the calling process's cpuset.
 152 Note that this information is subject to change at any
 153 time by manual or automatic reconfiguration of the cpuset.
 154
 155 Use of
 156 .BR migrate_pages ()
 157 may result in pages whose location
 158 (node) violates the memory policy established for the
 159 specified addresses (see
 160 .BR mbind (2))
 161 and/or the specified process (see
 162 .BR set_mempolicy (2)).
 163 That is, memory policy does not constrain the destination
 164 nodes used by
 165 .BR migrate_pages ().
 166
 167 The
 168 .I <numaif.h>
 169 header is not included with glibc, but requires installing
 170 .I libnuma-devel
 171 or a similar package.
 172 .SH SEE ALSO
 173 .BR get_mempolicy (2),
 174 .BR mbind (2),
 175 .BR set_mempolicy (2),
 176 .BR numa (3),
 177 .BR numa_maps (5),
 178 .BR cpuset (7),
 179 .BR numa (7),
 180 .BR migratepages (8),
 181 .BR numastat (8)
 182
 183 .IR Documentation/vm/page_migration
 184 in the Linux kernel source tree