original/man2/migrate_pages.2

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