Debian Codegraph @

upstream/debian-trixie/man2/migrate_pages.2

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