original/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 2012-08-01 "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 EPERM
  99 Insufficient privilege
 100 .RB ( CAP_SYS_NICE )
 101 to move pages of the process specified by
 102 .IR pid ,
 103 or insufficient privilege
 104 .RB ( CAP_SYS_NICE )
 105 to access the specified target nodes.
 106 .TP
 107 .B ESRCH
 108 No process matching
 109 .I pid
 110 could be found.
 111 .\" FIXME There are other errors
 112 .SH VERSIONS
 113 The
 114 .BR migrate_pages ()
 115 system call first appeared on Linux in version 2.6.16.
 116 .SH CONFORMING TO
 117 This system call is Linux-specific.
 118 .SH NOTES
 119 For information on library support, see
 120 .BR numa (7).
 121
 122 Use
 123 .BR get_mempolicy (2)
 124 with the
 125 .B MPOL_F_MEMS_ALLOWED
 126 flag to obtain the set of nodes that are allowed by
 127 the calling process's cpuset.
 128 Note that this information is subject to change at any
 129 time by manual or automatic reconfiguration of the cpuset.
 130
 131 Use of
 132 .BR migrate_pages ()
 133 may result in pages whose location
 134 (node) violates the memory policy established for the
 135 specified addresses (see
 136 .BR mbind (2))
 137 and/or the specified process (see
 138 .BR set_mempolicy (2)).
 139 That is, memory policy does not constrain the destination
 140 nodes used by
 141 .BR migrate_pages ().
 142
 143 The
 144 .I <numaif.h>
 145 header is not included with glibc, but requires installing
 146 .I libnuma-devel
 147 or a similar package.
 148 .SH SEE ALSO
 149 .BR get_mempolicy (2),
 150 .BR mbind (2),
 151 .BR set_mempolicy (2),
 152 .BR numa (3),
 153 .BR numa_maps (5),
 154 .BR cpuset (7),
 155 .BR numa (7),
 156 .BR migratepages (8),
 157 .BR numastat (8)
 158
 159 .IR Documentation/vm/page_migration
 160 in the Linux kernel source tree
 161 .SH COLOPHON
 162 This page is part of release 3.68 of the Linux
 163 .I man-pages
 164 project.
 165 A description of the project,
 166 information about reporting bugs,
 167 and the latest version of this page,
 168 can be found at
 169 \%http://www.kernel.org/doc/man\-pages/.