Debian Codegraph @

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