Debian Codegraph @

upstream/debian-trixie/man2/mbind.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 .\" FIXME
11 .\" Linux 3.8 added MPOL_MF_LAZY, which needs to be documented.
12 .\" Does it also apply for move_pages()?
13 .\"
14 .\" commit b24f53a0bea38b266d219ee651b22dba727c44ae
15 .\" Author: Lee Schermerhorn <[email protected]>
16 .\" Date: Thu Oct 25 14:16:32 2012 +0200
17 .\"
18 .TH mbind 2 2024-05-02 "Linux man-pages 6.9.1"
19 .SH NAME
20 mbind \- set memory policy for a memory range
21 .SH LIBRARY
22 NUMA (Non-Uniform Memory Access) policy library
23 .RI ( libnuma ", " \-lnuma )
24 .SH SYNOPSIS
25 .nf
26 .B "#include <numaif.h>"
27 .P
28 .BI "long mbind(void " addr [. len "], unsigned long " len ", int " mode ,
29 .BI " const unsigned long " nodemask [(. maxnode " + ULONG_WIDTH - 1)"
30 .B " / ULONG_WIDTH],"
31 .BI " unsigned long " maxnode ", unsigned int " flags );
32 .fi
33 .SH DESCRIPTION
34 .BR mbind ()
35 sets the NUMA memory policy,
36 which consists of a policy mode and zero or more nodes,
37 for the memory range starting with
38 .I addr
39 and continuing for
40 .I len
41 bytes.
42 The memory policy defines from which node memory is allocated.
43 .P
44 If the memory range specified by the
45 .IR addr " and " len
46 arguments includes an "anonymous" region of memory\[em]that is
47 a region of memory created using the
48 .BR mmap (2)
49 system call with the
50 .BR MAP_ANONYMOUS \[em]or
51 a memory-mapped file, mapped using the
52 .BR mmap (2)
53 system call with the
54 .B MAP_PRIVATE
55 flag, pages will be allocated only according to the specified
56 policy when the application writes (stores) to the page.
57 For anonymous regions, an initial read access will use a shared
58 page in the kernel containing all zeros.
59 For a file mapped with
60 .BR MAP_PRIVATE ,
61 an initial read access will allocate pages according to the
62 memory policy of the thread that causes the page to be allocated.
63 This may not be the thread that called
64 .BR mbind ().
65 .P
66 The specified policy will be ignored for any
67 .B MAP_SHARED
68 mappings in the specified memory range.
69 Rather the pages will be allocated according to the memory policy
70 of the thread that caused the page to be allocated.
71 Again, this may not be the thread that called
72 .BR mbind ().
73 .P
74 If the specified memory range includes a shared memory region
75 created using the
76 .BR shmget (2)
77 system call and attached using the
78 .BR shmat (2)
79 system call,
80 pages allocated for the anonymous or shared memory region will
81 be allocated according to the policy specified, regardless of which
82 process attached to the shared memory segment causes the allocation.
83 If, however, the shared memory region was created with the
84 .B SHM_HUGETLB
85 flag,
86 the huge pages will be allocated according to the policy specified
87 only if the page allocation is caused by the process that calls
88 .BR mbind ()
89 for that region.
90 .P
91 By default,
92 .BR mbind ()
93 has an effect only for new allocations; if the pages inside
94 the range have been already touched before setting the policy,
95 then the policy has no effect.
96 This default behavior may be overridden by the
97 .B MPOL_MF_MOVE
98 and
99 .B MPOL_MF_MOVE_ALL
100 flags described below.
101 .P
102 The
103 .I mode
104 argument must specify one of
105 .BR MPOL_DEFAULT ,
106 .BR MPOL_BIND ,
107 .BR MPOL_INTERLEAVE ,
108 .BR MPOL_WEIGHTED_INTERLEAVE ,
109 .BR MPOL_PREFERRED ,
110 or
111 .B MPOL_LOCAL
112 (which are described in detail below).
113 All policy modes except
114 .B MPOL_DEFAULT
115 require the caller to specify the node or nodes to which the mode applies,
116 via the
117 .I nodemask
118 argument.
119 .P
120 The
121 .I mode
122 argument may also include an optional
123 .IR "mode flag" .
124 The supported
125 .I "mode flags"
126 are:
127 .TP
128 .BR MPOL_F_NUMA_BALANCING " (since Linux 5.15)"
129 .\" commit bda420b985054a3badafef23807c4b4fa38a3dff
130 .\" commit 6d2aec9e123bb9c49cb5c7fc654f25f81e688e8c
131 When
132 .I mode
133 is
134 .BR MPOL_BIND ,
135 enable the kernel NUMA balancing for the task if it is supported by the kernel.
136 If the flag isn't supported by the kernel, or is used with
137 .I mode
138 other than
139 .BR MPOL_BIND ,
140 \-1 is returned and
141 .I errno
142 is set to
143 .BR EINVAL .
144 .TP
145 .BR MPOL_F_STATIC_NODES " (since Linux-2.6.26)"
146 A nonempty
147 .I nodemask
148 specifies physical node IDs.
149 Linux does not remap the
150 .I nodemask
151 when the thread moves to a different cpuset context,
152 nor when the set of nodes allowed by the thread's
153 current cpuset context changes.
154 .TP
155 .BR MPOL_F_RELATIVE_NODES " (since Linux-2.6.26)"
156 A nonempty
157 .I nodemask
158 specifies node IDs that are relative to the set of
159 node IDs allowed by the thread's current cpuset.
160 .P
161 .I nodemask
162 points to a bit mask of nodes containing up to
163 .I maxnode
164 bits.
165 The bit mask size is rounded to the next multiple of
166 .IR "sizeof(unsigned long)" ,
167 but the kernel will use bits only up to
168 .IR maxnode .
169 A NULL value of
170 .I nodemask
171 or a
172 .I maxnode
173 value of zero specifies the empty set of nodes.
174 If the value of
175 .I maxnode
176 is zero,
177 the
178 .I nodemask
179 argument is ignored.
180 Where a
181 .I nodemask
182 is required, it must contain at least one node that is on-line,
183 allowed by the thread's current cpuset context
184 (unless the
185 .B MPOL_F_STATIC_NODES
186 mode flag is specified),
187 and contains memory.
188 .P
189 The
190 .I mode
191 argument must include one of the following values:
192 .TP
193 .B MPOL_DEFAULT
194 This mode requests that any nondefault policy be removed,
195 restoring default behavior.
196 When applied to a range of memory via
197 .BR mbind (),
198 this means to use the thread memory policy,
199 which may have been set with
200 .BR set_mempolicy (2).
201 If the mode of the thread memory policy is also
202 .BR MPOL_DEFAULT ,
203 the system-wide default policy will be used.
204 The system-wide default policy allocates
205 pages on the node of the CPU that triggers the allocation.
206 For
207 .BR MPOL_DEFAULT ,
208 the
209 .I nodemask
210 and
211 .I maxnode
212 arguments must be specify the empty set of nodes.
213 .TP
214 .B MPOL_BIND
215 This mode specifies a strict policy that restricts memory allocation to
216 the nodes specified in
217 .IR nodemask .
218 If
219 .I nodemask
220 specifies more than one node, page allocations will come from
221 the node with sufficient free memory that is closest to
222 the node where the allocation takes place.
223 Pages will not be allocated from any node not specified in the
224 IR nodemask .
225 (Before Linux 2.6.26,
226 .\" commit 19770b32609b6bf97a3dece2529089494cbfc549
227 page allocations came from
228 the node with the lowest numeric node ID first, until that node
229 contained no free memory.
230 Allocations then came from the node with the next highest
231 node ID specified in
232 .I nodemask
233 and so forth, until none of the specified nodes contained free memory.)
234 .TP
235 .B MPOL_INTERLEAVE
236 This mode specifies that page allocations be interleaved across the
237 set of nodes specified in
238 .IR nodemask .
239 This optimizes for bandwidth instead of latency
240 by spreading out pages and memory accesses to those pages across
241 multiple nodes.
242 To be effective the memory area should be fairly large,
243 at least 1\ MB or bigger with a fairly uniform access pattern.
244 Accesses to a single page of the area will still be limited to
245 the memory bandwidth of a single node.
246 .TP
247 .BR MPOL_WEIGHTED_INTERLEAVE " (since Linux 6.9)"
248 .\" commit fa3bea4e1f8202d787709b7e3654eb0a99aed758
249 This mode interleaves page allocations across the nodes specified in
250 .I nodemask
251 according to the weights in
252 .IR /sys/kernel/mm/mempolicy/weighted_interleave .
253 For example, if bits 0, 2, and 5 are set in
254 .IR nodemask ,
255 and the contents of
256 .IR /sys/kernel/mm/mempolicy/weighted_interleave/node0 ,
257 .IR /sys/ .\|.\|. /node2 ,
258 and
259 .IR /sys/ .\|.\|. /node5
260 are 4, 7, and 9, respectively,
261 then pages in this region will be allocated on nodes 0, 2, and 5
262 in a 4:7:9 ratio.
263 .TP
264 .B MPOL_PREFERRED
265 This mode sets the preferred node for allocation.
266 The kernel will try to allocate pages from this
267 node first and fall back to other nodes if the
268 preferred nodes is low on free memory.
269 If
270 .I nodemask
271 specifies more than one node ID, the first node in the
272 mask will be selected as the preferred node.
273 If the
274 .I nodemask
275 and
276 .I maxnode
277 arguments specify the empty set, then the memory is allocated on
278 the node of the CPU that triggered the allocation.
279 .TP
280 .BR MPOL_LOCAL " (since Linux 3.8)"
281 .\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
282 .\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f
283 This mode specifies "local allocation"; the memory is allocated on
284 the node of the CPU that triggered the allocation (the "local node").
285 The
286 .I nodemask
287 and
288 .I maxnode
289 arguments must specify the empty set.
290 If the "local node" is low on free memory,
291 the kernel will try to allocate memory from other nodes.
292 The kernel will allocate memory from the "local node"
293 whenever memory for this node is available.
294 If the "local node" is not allowed by the thread's current cpuset context,
295 the kernel will try to allocate memory from other nodes.
296 The kernel will allocate memory from the "local node" whenever
297 it becomes allowed by the thread's current cpuset context.
298 By contrast,
299 .B MPOL_DEFAULT
300 reverts to the memory policy of the thread (which may be set via
301 .BR set_mempolicy (2));
302 that policy may be something other than "local allocation".
303 .P
304 If
305 .B MPOL_MF_STRICT
306 is passed in
307 .I flags
308 and
309 .I mode
310 is not
311 .BR MPOL_DEFAULT ,
312 then the call fails with the error
313 .B EIO
314 if the existing pages in the memory range don't follow the policy.
315 .\" According to the kernel code, the following is not true
316 .\" --Lee Schermerhorn
317 .\" In Linux 2.6.16 or later the kernel will also try to move pages
318 .\" to the requested node with this flag.
319 .P
320 If
321 .B MPOL_MF_MOVE
322 is specified in
323 .IR flags ,
324 then the kernel will attempt to move all the existing pages
325 in the memory range so that they follow the policy.
326 Pages that are shared with other processes will not be moved.
327 If
328 .B MPOL_MF_STRICT
329 is also specified, then the call fails with the error
330 .B EIO
331 if some pages could not be moved.
332 If the
333 .B MPOL_INTERLEAVE
334 policy was specified,
335 pages already residing on the specified nodes
336 will not be moved such that they are interleaved.
337 .P
338 If
339 .B MPOL_MF_MOVE_ALL
340 is passed in
341 .IR flags ,
342 then the kernel will attempt to move all existing pages in the memory range
343 regardless of whether other processes use the pages.
344 The calling thread must be privileged
345 .RB ( CAP_SYS_NICE )
346 to use this flag.
347 If
348 .B MPOL_MF_STRICT
349 is also specified, then the call fails with the error
350 .B EIO
351 if some pages could not be moved.
352 If the
353 .B MPOL_INTERLEAVE
354 policy was specified,
355 pages already residing on the specified nodes
356 will not be moved such that they are interleaved.
357 .\" ---------------------------------------------------------------
358 .SH RETURN VALUE
359 On success,
360 .BR mbind ()
361 returns 0;
362 on error, \-1 is returned and
363 .I errno
364 is set to indicate the error.
365 .\" ---------------------------------------------------------------
366 .SH ERRORS
367 .\" I think I got all of the error returns. --Lee Schermerhorn
368 .TP
369 .B EFAULT
370 Part or all of the memory range specified by
371 .I nodemask
372 and
373 .I maxnode
374 points outside your accessible address space.
375 Or, there was an unmapped hole in the specified memory range specified by
376 .I addr
377 and
378 .IR len .
379 .TP
380 .B EINVAL
381 An invalid value was specified for
382 .I flags
383 or
384 .IR mode ;
385 or
386 .I addr + len
387 was less than
388 .IR addr ;
389 or
390 .I addr
391 is not a multiple of the system page size.
392 Or,
393 .I mode
394 is
395 .B MPOL_DEFAULT
396 and
397 .I nodemask
398 specified a nonempty set;
399 or
400 .I mode
401 is
402 .B MPOL_BIND
403 or
404 .B MPOL_INTERLEAVE
405 and
406 .I nodemask
407 is empty.
408 Or,
409 .I maxnode
410 exceeds a kernel-imposed limit.
411 .\" As at 2.6.23, this limit is "a page worth of bits", e.g.,
412 .\" 8 * 4096 bits, assuming a 4kB page size.
413 Or,
414 .I nodemask
415 specifies one or more node IDs that are
416 greater than the maximum supported node ID.
417 Or, none of the node IDs specified by
418 .I nodemask
419 are on-line and allowed by the thread's current cpuset context,
420 or none of the specified nodes contain memory.
421 Or, the
422 .I mode
423 argument specified both
424 .B MPOL_F_STATIC_NODES
425 and
426 .BR MPOL_F_RELATIVE_NODES .
427 .TP
428 .B EIO
429 .B MPOL_MF_STRICT
430 was specified and an existing page was already on a node
431 that does not follow the policy;
432 or
433 .B MPOL_MF_MOVE
434 or
435 .B MPOL_MF_MOVE_ALL
436 was specified and the kernel was unable to move all existing
437 pages in the range.
438 .TP
439 .B ENOMEM
440 Insufficient kernel memory was available.
441 .TP
442 .B EPERM
443 The
444 .I flags
445 argument included the
446 .B MPOL_MF_MOVE_ALL
447 flag and the caller does not have the
448 .B CAP_SYS_NICE
449 privilege.
450 .\" ---------------------------------------------------------------
451 .SH STANDARDS
452 Linux.
453 .SH HISTORY
454 Linux 2.6.7.
455 .P
456 Support for huge page policy was added with Linux 2.6.16.
457 For interleave policy to be effective on huge page mappings the
458 policied memory needs to be tens of megabytes or larger.
459 .P
460 Before Linux 5.7.
461 .\" commit dcf1763546d76c372f3136c8d6b2b6e77f140cf0
462 .B MPOL_MF_STRICT
463 was ignored on huge page mappings.
464 .P
465 .B MPOL_MF_MOVE
466 and
467 .B MPOL_MF_MOVE_ALL
468 are available only on Linux 2.6.16 and later.
469 .SH NOTES
470 For information on library support, see
471 .BR numa (7).
472 .P
473 NUMA policy is not supported on a memory-mapped file range
474 that was mapped with the
475 .B MAP_SHARED
476 flag.
477 .P
478 The
479 .B MPOL_DEFAULT
480 mode can have different effects for
481 .BR mbind ()
482 and
483 .BR set_mempolicy (2).
484 When
485 .B MPOL_DEFAULT
486 is specified for
487 .BR set_mempolicy (2),
488 the thread's memory policy reverts to the system default policy
489 or local allocation.
490 When
491 .B MPOL_DEFAULT
492 is specified for a range of memory using
493 .BR mbind (),
494 any pages subsequently allocated for that range will use
495 the thread's memory policy, as set by
496 .BR set_mempolicy (2).
497 This effectively removes the explicit policy from the
498 specified range, "falling back" to a possibly nondefault
499 policy.
500 To select explicit "local allocation" for a memory range,
501 specify a
502 .I mode
503 of
504 .B MPOL_LOCAL
505 or
506 .B MPOL_PREFERRED
507 with an empty set of nodes.
508 This method will work for
509 .BR set_mempolicy (2),
510 as well.
511 .SH SEE ALSO
512 .BR get_mempolicy (2),
513 .BR getcpu (2),
514 .BR mmap (2),
515 .BR set_mempolicy (2),
516 .BR shmat (2),
517 .BR shmget (2),
518 .BR numa (3),
519 .BR cpuset (7),
520 .BR numa (7),
521 .BR numactl (8)