Debian Codegraph @

upstream/debian-unstable/man2/migrate_pages.2

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