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