Debian Codegraph @

upstream/debian-trixie/man2/set_mempolicy.2

raw
1 .\" SPDX-License-Identifier: Linux-man-pages-copyleft-var
2 .\"
3 .\" Copyright 2003,2004 Andi Kleen, SuSE Labs.
4 .\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard
5 .\"
6 .\" 2006-02-03, mtk, substantial wording changes and other improvements
7 .\" 2007-08-27, Lee Schermerhorn <[email protected]>
8 .\" more precise specification of behavior.
9 .\"
10 .TH set_mempolicy 2 2024-05-02 "Linux man-pages 6.9.1"
11 .SH NAME
12 set_mempolicy \- set default NUMA memory policy for a thread and its children
13 .SH LIBRARY
14 NUMA (Non-Uniform Memory Access) policy library
15 .RI ( libnuma ", " \-lnuma )
16 .SH SYNOPSIS
17 .nf
18 .B "#include <numaif.h>"
19 .P
20 .BI "long set_mempolicy(int " mode ", const unsigned long *" nodemask ,
21 .BI " unsigned long " maxnode );
22 .fi
23 .SH DESCRIPTION
24 .BR set_mempolicy ()
25 sets the NUMA memory policy of the calling thread,
26 which consists of a policy mode and zero or more nodes,
27 to the values specified by the
28 .IR mode ,
29 .IR nodemask ,
30 and
31 .I maxnode
32 arguments.
33 .P
34 A NUMA machine has different
35 memory controllers with different distances to specific CPUs.
36 The memory policy defines from which node memory is allocated for
37 the thread.
38 .P
39 This system call defines the default policy for the thread.
40 The thread policy governs allocation of pages in the process's
41 address space outside of memory ranges
42 controlled by a more specific policy set by
43 .BR mbind (2).
44 The thread default policy also controls allocation of any pages for
45 memory-mapped files mapped using the
46 .BR mmap (2)
47 call with the
48 .B MAP_PRIVATE
49 flag and that are only read (loaded) from by the thread
50 and of memory-mapped files mapped using the
51 .BR mmap (2)
52 call with the
53 .B MAP_SHARED
54 flag, regardless of the access type.
55 The policy is applied only when a new page is allocated
56 for the thread.
57 For anonymous memory this is when the page is first
58 touched by the thread.
59 .P
60 The
61 .I mode
62 argument must specify one of
63 .BR MPOL_DEFAULT ,
64 .BR MPOL_BIND ,
65 .BR MPOL_INTERLEAVE ,
66 .BR MPOL_WEIGHTED_INTERLEAVE ,
67 .BR MPOL_PREFERRED ,
68 or
69 .B MPOL_LOCAL
70 (which are described in detail below).
71 All modes except
72 .B MPOL_DEFAULT
73 require the caller to specify the node or nodes to which the mode applies,
74 via the
75 .I nodemask
76 argument.
77 .P
78 The
79 .I mode
80 argument may also include an optional
81 .IR "mode flag" .
82 The supported
83 .I "mode flags"
84 are:
85 .TP
86 .BR MPOL_F_NUMA_BALANCING " (since Linux 5.12)"
87 .\" commit bda420b985054a3badafef23807c4b4fa38a3dff
88 When
89 .I mode
90 is
91 .BR MPOL_BIND ,
92 enable the kernel NUMA balancing for the task if it is supported by the kernel.
93 If the flag isn't supported by the kernel, or is used with
94 .I mode
95 other than
96 .BR MPOL_BIND ,
97 \-1 is returned and
98 .I errno
99 is set to
100 .BR EINVAL .
101 .TP
102 .BR MPOL_F_RELATIVE_NODES " (since Linux 2.6.26)"
103 A nonempty
104 .I nodemask
105 specifies node IDs that are relative to the
106 set of node IDs allowed by the process's current cpuset.
107 .TP
108 .BR MPOL_F_STATIC_NODES " (since Linux 2.6.26)"
109 A nonempty
110 .I nodemask
111 specifies physical node IDs.
112 Linux will not remap the
113 .I nodemask
114 when the process moves to a different cpuset context,
115 nor when the set of nodes allowed by the process's
116 current cpuset context changes.
117 .P
118 .I nodemask
119 points to a bit mask of node IDs that contains up to
120 .I maxnode
121 bits.
122 The bit mask size is rounded to the next multiple of
123 .IR "sizeof(unsigned long)" ,
124 but the kernel will use bits only up to
125 .IR maxnode .
126 A NULL value of
127 .I nodemask
128 or a
129 .I maxnode
130 value of zero specifies the empty set of nodes.
131 If the value of
132 .I maxnode
133 is zero,
134 the
135 .I nodemask
136 argument is ignored.
137 .P
138 Where a
139 .I nodemask
140 is required, it must contain at least one node that is on-line,
141 allowed by the process's current cpuset context,
142 (unless the
143 .B MPOL_F_STATIC_NODES
144 mode flag is specified),
145 and contains memory.
146 If the
147 .B MPOL_F_STATIC_NODES
148 is set in
149 .I mode
150 and a required
151 .I nodemask
152 contains no nodes that are allowed by the process's current cpuset context,
153 the memory policy reverts to
154 .IR "local allocation" .
155 This effectively overrides the specified policy until the process's
156 cpuset context includes one or more of the nodes specified by
157 .IR nodemask .
158 .P
159 The
160 .I mode
161 argument must include one of the following values:
162 .TP
163 .B MPOL_DEFAULT
164 This mode specifies that any nondefault thread memory policy be removed,
165 so that the memory policy "falls back" to the system default policy.
166 The system default policy is "local allocation"\[em]that is,
167 allocate memory on the node of the CPU that triggered the allocation.
168 .I nodemask
169 must be specified as NULL.
170 If the "local node" contains no free memory, the system will
171 attempt to allocate memory from a "near by" node.
172 .TP
173 .B MPOL_BIND
174 This mode defines a strict policy that restricts memory allocation to the
175 nodes specified in
176 .IR nodemask .
177 If
178 .I nodemask
179 specifies more than one node, page allocations will come from
180 the node with the lowest numeric node ID first, until that node
181 contains no free memory.
182 Allocations will then come from the node with the next highest
183 node ID specified in
184 .I nodemask
185 and so forth, until none of the specified nodes contain free memory.
186 Pages will not be allocated from any node not specified in the
187 .IR nodemask .
188 .TP
189 .B MPOL_INTERLEAVE
190 This mode interleaves page allocations across the nodes specified in
191 .I nodemask
192 in numeric node ID order.
193 This optimizes for bandwidth instead of latency
194 by spreading out pages and memory accesses to those pages across
195 multiple nodes.
196 However, accesses to a single page will still be limited to
197 the memory bandwidth of a single node.
198 .\" NOTE: the following sentence doesn't make sense in the context
199 .\" of set_mempolicy() -- no memory area specified.
200 .\" To be effective the memory area should be fairly large,
201 .\" at least 1 MB or bigger.
202 .TP
203 .BR MPOL_WEIGHTED_INTERLEAVE " (since Linux 6.9)"
204 .\" commit fa3bea4e1f8202d787709b7e3654eb0a99aed758
205 This mode interleaves page allocations across the nodes specified in
206 .I nodemask
207 according to the weights in
208 .IR /sys/kernel/mm/mempolicy/weighted_interleave .
209 For example, if bits 0, 2, and 5 are set in
210 .IR nodemask ,
211 and the contents of
212 .IR /sys/kernel/mm/mempolicy/weighted_interleave/node0 ,
213 .IR /sys/ .\|.\|. /node2 ,
214 and
215 .IR /sys/ .\|.\|. /node5
216 are 4, 7, and 9, respectively,
217 then pages in this region will be allocated on nodes 0, 2, and 5
218 in a 4:7:9 ratio.
219 .TP
220 .B MPOL_PREFERRED
221 This mode sets the preferred node for allocation.
222 The kernel will try to allocate pages from this node first
223 and fall back to "near by" nodes if the preferred node is low on free
224 memory.
225 If
226 .I nodemask
227 specifies more than one node ID, the first node in the
228 mask will be selected as the preferred node.
229 If the
230 .I nodemask
231 and
232 .I maxnode
233 arguments specify the empty set, then the policy
234 specifies "local allocation"
235 (like the system default policy discussed above).
236 .TP
237 .BR MPOL_LOCAL " (since Linux 3.8)"
238 .\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
239 .\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f
240 This mode specifies "local allocation"; the memory is allocated on
241 the node of the CPU that triggered the allocation (the "local node").
242 The
243 .I nodemask
244 and
245 .I maxnode
246 arguments must specify the empty set.
247 If the "local node" is low on free memory,
248 the kernel will try to allocate memory from other nodes.
249 The kernel will allocate memory from the "local node"
250 whenever memory for this node is available.
251 If the "local node" is not allowed by the process's current cpuset context,
252 the kernel will try to allocate memory from other nodes.
253 The kernel will allocate memory from the "local node" whenever
254 it becomes allowed by the process's current cpuset context.
255 .P
256 The thread memory policy is preserved across an
257 .BR execve (2),
258 and is inherited by child threads created using
259 .BR fork (2)
260 or
261 .BR clone (2).
262 .SH RETURN VALUE
263 On success,
264 .BR set_mempolicy ()
265 returns 0;
266 on error, \-1 is returned and
267 .I errno
268 is set to indicate the error.
269 .SH ERRORS
270 .TP
271 .B EFAULT
272 Part of all of the memory range specified by
273 .I nodemask
274 and
275 .I maxnode
276 points outside your accessible address space.
277 .TP
278 .B EINVAL
279 .I mode
280 is invalid.
281 Or,
282 .I mode
283 is
284 .B MPOL_DEFAULT
285 and
286 .I nodemask
287 is nonempty,
288 or
289 .I mode
290 is
291 .B MPOL_BIND
292 or
293 .B MPOL_INTERLEAVE
294 and
295 .I nodemask
296 is empty.
297 Or,
298 .I maxnode
299 specifies more than a page worth of bits.
300 Or,
301 .I nodemask
302 specifies one or more node IDs that are
303 greater than the maximum supported node ID.
304 Or, none of the node IDs specified by
305 .I nodemask
306 are on-line and allowed by the process's current cpuset context,
307 or none of the specified nodes contain memory.
308 Or, the
309 .I mode
310 argument specified both
311 .B MPOL_F_STATIC_NODES
312 and
313 .BR MPOL_F_RELATIVE_NODES .
314 Or, the
315 .B MPOL_F_NUMA_BALANCING
316 isn't supported by the kernel, or is used with
317 .I mode
318 other than
319 .BR MPOL_BIND .
320 .TP
321 .B ENOMEM
322 Insufficient kernel memory was available.
323 .SH STANDARDS
324 Linux.
325 .SH HISTORY
326 Linux 2.6.7.
327 .SH NOTES
328 Memory policy is not remembered if the page is swapped out.
329 When such a page is paged back in, it will use the policy of
330 the thread or memory range that is in effect at the time the
331 page is allocated.
332 .P
333 For information on library support, see
334 .BR numa (7).
335 .SH SEE ALSO
336 .BR get_mempolicy (2),
337 .BR getcpu (2),
338 .BR mbind (2),
339 .BR mmap (2),
340 .BR numa (3),
341 .BR cpuset (7),
342 .BR numa (7),
343 .BR numactl (8)