]>
Commit | Line | Data |
---|---|---|
5aa2ee80 | 1 | .\" Copyright 2009 Intel Corporation |
f01470e6 AK |
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 | .\" | |
89b25c0f | 7 | .\" %%%LICENSE_START(VERBATIM_TWO_PARA) |
f01470e6 AK |
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. | |
8ff7380d | 16 | .\" %%%LICENSE_END |
89b25c0f | 17 | .\" |
45186a5d | 18 | .TH MIGRATE_PAGES 2 2021-03-22 "Linux man-pages (unreleased)" |
f01470e6 AK |
19 | .SH NAME |
20 | migrate_pages \- move all pages in a process to another set of nodes | |
53ebda45 AC |
21 | .SH LIBRARY |
22 | NUMA (Non-Uniform Memory Access) policy library | |
8fc3b2cf | 23 | .RI ( libnuma ", " \-lnuma ) |
f01470e6 AK |
24 | .SH SYNOPSIS |
25 | .nf | |
26 | .B #include <numaif.h> | |
68e4db0a | 27 | .PP |
f01470e6 | 28 | .BI "long migrate_pages(int " pid ", unsigned long " maxnode, |
55d56b71 | 29 | .BI " const unsigned long *" old_nodes, |
8d5c0a3d | 30 | .BI " const unsigned long *" new_nodes ); |
f01470e6 | 31 | .fi |
f01470e6 AK |
32 | .SH DESCRIPTION |
33 | .BR migrate_pages () | |
41a65f12 | 34 | attempts to move all pages of the process |
f01470e6 AK |
35 | .I pid |
36 | that are in memory nodes | |
37 | .I old_nodes | |
38 | to the memory nodes in | |
cad2c516 | 39 | .IR new_nodes . |
f01470e6 AK |
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 . | |
efeece04 | 48 | .PP |
b911dcb0 | 49 | The |
f01470e6 AK |
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 | |
cad2c516 | 69 | .BR select (2)). |
efeece04 | 70 | .PP |
f01470e6 AK |
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. | |
efeece04 | 84 | .PP |
33a0ccb2 | 85 | Pages shared with another process will be moved only if the initiating |
f01470e6 AK |
86 | process has the |
87 | .B CAP_SYS_NICE | |
88 | privilege. | |
47297adb | 89 | .SH RETURN VALUE |
f01470e6 AK |
90 | On success |
91 | .BR migrate_pages () | |
6edb20bc | 92 | returns the number of pages that could not be moved |
41a65f12 | 93 | (i.e., a return of zero means that all pages were successfully moved). |
f01470e6 AK |
94 | On error, it returns \-1, and sets |
95 | .I errno | |
96 | to indicate the error. | |
97 | .SH ERRORS | |
98 | .TP | |
3d350ba3 JS |
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 | |
f01470e6 AK |
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. | |
bea08fec | 136 | .\" FIXME Document the other errors that can occur for migrate_pages() |
f01470e6 AK |
137 | .SH VERSIONS |
138 | The | |
139 | .BR migrate_pages () | |
140 | system call first appeared on Linux in version 2.6.16. | |
3113c7f3 | 141 | .SH STANDARDS |
f01470e6 | 142 | This system call is Linux-specific. |
47297adb | 143 | .SH NOTES |
f01470e6 AK |
144 | For information on library support, see |
145 | .BR numa (7). | |
efeece04 | 146 | .PP |
f01470e6 AK |
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. | |
efeece04 | 155 | .PP |
f01470e6 AK |
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 (). | |
efeece04 | 167 | .PP |
f01470e6 AK |
168 | The |
169 | .I <numaif.h> | |
170 | header is not included with glibc, but requires installing | |
cd415e73 | 171 | .I libnuma\-devel |
f01470e6 | 172 | or a similar package. |
47297adb | 173 | .SH SEE ALSO |
f01470e6 AK |
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), | |
d4c52847 | 182 | .BR numastat (8) |
efeece04 | 183 | .PP |
1ae6b2c7 | 184 | .I Documentation/vm/page_migration.rst |
173fe7e7 | 185 | in the Linux kernel source tree |