Debian Codegraph @

upstream/fedora-44/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 2025-02-21 "Linux man-pages 6.13"
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 .BR MPOL_PREFERRED_MANY ,
69 or
70 .B MPOL_LOCAL
71 (which are described in detail below).
72 All modes except
73 .B MPOL_DEFAULT
74 require the caller to specify the node or nodes to which the mode applies,
75 via the
76 .I nodemask
77 argument.
78 .P
79 The
80 .I mode
81 argument may also include an optional
82 .IR "mode flag" .
83 The supported
84 .I "mode flags"
85 are:
86 .TP
87 .BR MPOL_F_NUMA_BALANCING " (since Linux 5.12)"
88 .\" commit bda420b985054a3badafef23807c4b4fa38a3dff
89 When
90 .I mode
91 is
92 .BR MPOL_BIND ,
93 enable the kernel NUMA balancing for the task if it is supported by the kernel.
94 If the flag isn't supported by the kernel, or is used with
95 .I mode
96 other than
97 .BR MPOL_BIND ,
98 \-1 is returned and
99 .I errno
100 is set to
101 .BR EINVAL .
102 .TP
103 .BR MPOL_F_RELATIVE_NODES " (since Linux 2.6.26)"
104 A nonempty
105 .I nodemask
106 specifies node IDs that are relative to the
107 set of node IDs allowed by the process's current cpuset.
108 .TP
109 .BR MPOL_F_STATIC_NODES " (since Linux 2.6.26)"
110 A nonempty
111 .I nodemask
112 specifies physical node IDs.
113 Linux will not remap the
114 .I nodemask
115 when the process moves to a different cpuset context,
116 nor when the set of nodes allowed by the process's
117 current cpuset context changes.
118 .P
119 .I nodemask
120 points to a bit mask of node IDs that contains up to
121 .I maxnode
122 bits.
123 The bit mask size is rounded to the next multiple of
124 .IR "sizeof(unsigned long)" ,
125 but the kernel will use bits only up to
126 .IR maxnode .
127 A NULL value of
128 .I nodemask
129 or a
130 .I maxnode
131 value of zero specifies the empty set of nodes.
132 If the value of
133 .I maxnode
134 is zero,
135 the
136 .I nodemask
137 argument is ignored.
138 .P
139 Where a
140 .I nodemask
141 is required, it must contain at least one node that is on-line,
142 allowed by the process's current cpuset context,
143 (unless the
144 .B MPOL_F_STATIC_NODES
145 mode flag is specified),
146 and contains memory.
147 If the
148 .B MPOL_F_STATIC_NODES
149 is set in
150 .I mode
151 and a required
152 .I nodemask
153 contains no nodes that are allowed by the process's current cpuset context,
154 the memory policy reverts to
155 .IR "local allocation" .
156 This effectively overrides the specified policy until the process's
157 cpuset context includes one or more of the nodes specified by
158 .IR nodemask .
159 .P
160 The
161 .I mode
162 argument must include one of the following values:
163 .TP
164 .B MPOL_DEFAULT
165 This mode specifies that any nondefault thread memory policy be removed,
166 so that the memory policy "falls back" to the system default policy.
167 The system default policy is "local allocation"\[em]that is,
168 allocate memory on the node of the CPU that triggered the allocation.
169 .I nodemask
170 must be specified as NULL.
171 If the "local node" contains no free memory, the system will
172 attempt to allocate memory from a "near by" node.
173 .TP
174 .B MPOL_BIND
175 This mode defines a strict policy that restricts memory allocation to the
176 nodes specified in
177 .IR nodemask .
178 If
179 .I nodemask
180 specifies more than one node, page allocations will come from
181 the node with the lowest numeric node ID first, until that node
182 contains no free memory.
183 Allocations will then come from the node with the next highest
184 node ID specified in
185 .I nodemask
186 and so forth, until none of the specified nodes contain free memory.
187 Pages will not be allocated from any node not specified in the
188 .IR nodemask .
189 .TP
190 .B MPOL_INTERLEAVE
191 This mode interleaves page allocations across the nodes specified in
192 .I nodemask
193 in numeric node ID order.
194 This optimizes for bandwidth instead of latency
195 by spreading out pages and memory accesses to those pages across
196 multiple nodes.
197 However, accesses to a single page will still be limited to
198 the memory bandwidth of a single node.
199 .\" NOTE: the following sentence doesn't make sense in the context
200 .\" of set_mempolicy() -- no memory area specified.
201 .\" To be effective the memory area should be fairly large,
202 .\" at least 1 MB or bigger.
203 .TP
204 .BR MPOL_WEIGHTED_INTERLEAVE " (since Linux 6.9)"
205 .\" commit fa3bea4e1f8202d787709b7e3654eb0a99aed758
206 This mode interleaves page allocations across the nodes specified in
207 .I nodemask
208 according to the weights in
209 .IR /sys/kernel/mm/mempolicy/weighted_interleave .
210 For example, if bits 0, 2, and 5 are set in
211 .IR nodemask ,
212 and the contents of
213 .IR /sys/kernel/mm/mempolicy/weighted_interleave/node0 ,
214 .IR /sys/ .\|.\|. /node2 ,
215 and
216 .IR /sys/ .\|.\|. /node5
217 are 4, 7, and 9, respectively,
218 then pages in this region will be allocated on nodes 0, 2, and 5
219 in a 4:7:9 ratio.
220 .TP
221 .B MPOL_PREFERRED
222 This mode sets the preferred node for allocation.
223 The kernel will try to allocate pages from this node first
224 and fall back to "near by" nodes if the preferred node is low on free
225 memory.
226 If
227 .I nodemask
228 specifies more than one node ID, the first node in the
229 mask will be selected as the preferred node.
230 If the
231 .I nodemask
232 and
233 .I maxnode
234 arguments specify the empty set, then the policy
235 specifies "local allocation"
236 (like the system default policy discussed above).
237 .TP
238 .BR MPOL_PREFERRED_MANY " (since Linux 5.15)"
239 .\" commit b27abaccf8e8b012f126da0c2a1ab32723ec8b9f
240 This mode specifies a preference for nodes
241 from which the kernel will try to allocate from.
242 This differs from
243 .B MPOL_PREFERRED
244 in that it accepts a set of nodes
245 versus a single node.
246 This policy is intended to benefit page allocations
247 where specific memory types
248 (i.e. non-volatile, high-bandwidth, or accelerator memory)
249 are of greater importance than node location.
250 .TP
251 .BR MPOL_LOCAL " (since Linux 3.8)"
252 .\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
253 .\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f
254 This mode specifies "local allocation"; the memory is allocated on
255 the node of the CPU that triggered the allocation (the "local node").
256 The
257 .I nodemask
258 and
259 .I maxnode
260 arguments must specify the empty set.
261 If the "local node" is low on free memory,
262 the kernel will try to allocate memory from other nodes.
263 The kernel will allocate memory from the "local node"
264 whenever memory for this node is available.
265 If the "local node" is not allowed by the process's current cpuset context,
266 the kernel will try to allocate memory from other nodes.
267 The kernel will allocate memory from the "local node" whenever
268 it becomes allowed by the process's current cpuset context.
269 .P
270 The thread memory policy is preserved across an
271 .BR execve (2),
272 and is inherited by child threads created using
273 .BR fork (2)
274 or
275 .BR clone (2).
276 .SH RETURN VALUE
277 On success,
278 .BR set_mempolicy ()
279 returns 0;
280 on error, \-1 is returned and
281 .I errno
282 is set to indicate the error.
283 .SH ERRORS
284 .TP
285 .B EFAULT
286 Part of all of the memory range specified by
287 .I nodemask
288 and
289 .I maxnode
290 points outside your accessible address space.
291 .TP
292 .B EINVAL
293 .I mode
294 is invalid.
295 Or,
296 .I mode
297 is
298 .B MPOL_DEFAULT
299 and
300 .I nodemask
301 is nonempty,
302 or
303 .I mode
304 is
305 .B MPOL_BIND
306 or
307 .B MPOL_INTERLEAVE
308 and
309 .I nodemask
310 is empty.
311 Or,
312 .I maxnode
313 specifies more than a page worth of bits.
314 Or,
315 .I nodemask
316 specifies one or more node IDs that are
317 greater than the maximum supported node ID.
318 Or, none of the node IDs specified by
319 .I nodemask
320 are on-line and allowed by the process's current cpuset context,
321 or none of the specified nodes contain memory.
322 Or, the
323 .I mode
324 argument specified both
325 .B MPOL_F_STATIC_NODES
326 and
327 .BR MPOL_F_RELATIVE_NODES .
328 Or, the
329 .B MPOL_F_NUMA_BALANCING
330 isn't supported by the kernel, or is used with
331 .I mode
332 other than
333 .BR MPOL_BIND .
334 .TP
335 .B ENOMEM
336 Insufficient kernel memory was available.
337 .SH STANDARDS
338 Linux.
339 .SH HISTORY
340 Linux 2.6.7.
341 .SH NOTES
342 Memory policy is not remembered if the page is swapped out.
343 When such a page is paged back in, it will use the policy of
344 the thread or memory range that is in effect at the time the
345 page is allocated.
346 .P
347 For information on library support, see
348 .BR numa (7).
349 .SH SEE ALSO
350 .BR get_mempolicy (2),
351 .BR getcpu (2),
352 .BR mbind (2),
353 .BR mmap (2),
354 .BR numa (3),
355 .BR cpuset (7),
356 .BR numa (7),
357 .BR numactl (8)