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