Debian Codegraph @

upstream/debian-unstable/man2/set_mempolicy.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 .TH set_mempolicy 2 2026-02-08 "Linux man-pages 6.18"
10 .SH NAME
11 set_mempolicy \- set default NUMA memory policy for a thread and its children
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 set_mempolicy(int " mode ", const unsigned long *" nodemask ,
20 .BI " unsigned long " maxnode );
21 .fi
22 .SH DESCRIPTION
23 .BR set_mempolicy ()
24 sets the NUMA memory policy of the calling thread,
25 which consists of a policy mode and zero or more nodes,
26 to the values specified by the
27 .IR mode ,
28 .IR nodemask ,
29 and
30 .I maxnode
31 arguments.
32 .P
33 A NUMA machine has different
34 memory controllers with different distances to specific CPUs.
35 The memory policy defines from which node memory is allocated for
36 the thread.
37 .P
38 This system call defines the default policy for the thread.
39 The thread policy governs allocation of pages in the process's
40 address space outside of memory ranges
41 controlled by a more specific policy set by
42 .BR mbind (2).
43 The thread default policy also controls allocation of any pages for
44 memory-mapped files mapped using the
45 .BR mmap (2)
46 call with the
47 .B MAP_PRIVATE
48 flag and that are only read (loaded) from by the thread
49 and of memory-mapped files mapped using the
50 .BR mmap (2)
51 call with the
52 .B MAP_SHARED
53 flag, regardless of the access type.
54 The policy is applied only when a new page is allocated
55 for the thread.
56 For anonymous memory this is when the page is first
57 touched by the thread.
58 .P
59 The
60 .I mode
61 argument must specify one of
62 .BR MPOL_DEFAULT ,
63 .BR MPOL_BIND ,
64 .BR MPOL_INTERLEAVE ,
65 .BR MPOL_WEIGHTED_INTERLEAVE ,
66 .BR MPOL_PREFERRED ,
67 .BR MPOL_PREFERRED_MANY ,
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_PREFERRED_MANY " (since Linux 5.15)"
238 .\" commit b27abaccf8e8b012f126da0c2a1ab32723ec8b9f
239 This mode specifies a preference for nodes
240 from which the kernel will try to allocate from.
241 This differs from
242 .B MPOL_PREFERRED
243 in that it accepts a set of nodes
244 versus a single node.
245 This policy is intended to benefit page allocations
246 where specific memory types
247 (i.e., non-volatile, high-bandwidth, or accelerator memory)
248 are of greater importance than node location.
249 .TP
250 .BR MPOL_LOCAL " (since Linux 3.8)"
251 .\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
252 .\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f
253 This mode specifies "local allocation";
254 the memory is allocated on
255 the node of the CPU that triggered the allocation
256 (the "local node").
257 The
258 .I nodemask
259 and
260 .I maxnode
261 arguments must specify the empty set.
262 If the "local node" is low on free memory,
263 the kernel will try to allocate memory from other nodes.
264 The kernel will allocate memory from the "local node"
265 whenever memory for this node is available.
266 If the "local node" is not allowed by the process's current cpuset context,
267 the kernel will try to allocate memory from other nodes.
268 The kernel will allocate memory from the "local node" whenever
269 it becomes allowed by the process's current cpuset context.
270 .P
271 The thread memory policy is preserved across an
272 .BR execve (2),
273 and is inherited by child threads created using
274 .BR fork (2)
275 or
276 .BR clone (2).
277 .SH RETURN VALUE
278 On success,
279 .BR set_mempolicy ()
280 returns 0;
281 on error, \-1 is returned and
282 .I errno
283 is set to indicate the error.
284 .SH ERRORS
285 .TP
286 .B EFAULT
287 Part of all of the memory range specified by
288 .I nodemask
289 and
290 .I maxnode
291 points outside your accessible address space.
292 .TP
293 .B EINVAL
294 .I mode
295 is invalid.
296 Or,
297 .I mode
298 is
299 .B MPOL_DEFAULT
300 and
301 .I nodemask
302 is nonempty,
303 or
304 .I mode
305 is
306 .B MPOL_BIND
307 or
308 .B MPOL_INTERLEAVE
309 and
310 .I nodemask
311 is empty.
312 Or,
313 .I maxnode
314 specifies more than a page worth of bits.
315 Or,
316 .I nodemask
317 specifies one or more node IDs that are
318 greater than the maximum supported node ID.
319 Or, none of the node IDs specified by
320 .I nodemask
321 are on-line and allowed by the process's current cpuset context,
322 or none of the specified nodes contain memory.
323 Or, the
324 .I mode
325 argument specified both
326 .B MPOL_F_STATIC_NODES
327 and
328 .BR MPOL_F_RELATIVE_NODES .
329 Or, the
330 .B MPOL_F_NUMA_BALANCING
331 isn't supported by the kernel, or is used with
332 .I mode
333 other than
334 .BR MPOL_BIND .
335 .TP
336 .B ENOMEM
337 Insufficient kernel memory was available.
338 .SH STANDARDS
339 Linux.
340 .SH HISTORY
341 Linux 2.6.7.
342 .SH NOTES
343 Memory policy is not remembered if the page is swapped out.
344 When such a page is paged back in, it will use the policy of
345 the thread or memory range that is in effect at the time the
346 page is allocated.
347 .P
348 For information on library support, see
349 .BR numa (7).
350 .SH SEE ALSO
351 .BR get_mempolicy (2),
352 .BR getcpu (2),
353 .BR mbind (2),
354 .BR mmap (2),
355 .BR numa (3),
356 .BR cpuset (7),
357 .BR numa (7),
358 .BR numactl (8)