Debian Codegraph @

upstream/debian-unstable/man2/mbind.2

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