]> git.ipfire.org Git - thirdparty/man-pages.git/blame - man2/set_mempolicy.2
core.5: grfix
[thirdparty/man-pages.git] / man2 / set_mempolicy.2
CommitLineData
314093c9 1.\" Copyright 2003,2004 Andi Kleen, SuSE Labs.
73ae0a09 2.\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard
314093c9 3.\"
9f882130 4.\" %%%LICENSE_START(VERBATIM_PROF)
314093c9
MK
5.\" Permission is granted to make and distribute verbatim copies of this
6.\" manual provided the copyright notice and this permission notice are
7.\" preserved on all copies.
8.\"
9.\" Permission is granted to copy and distribute modified versions of this
10.\" manual under the conditions for verbatim copying, provided that the
11.\" entire resulting derived work is distributed under the terms of a
12.\" permission notice identical to this one.
c13182ef 13.\"
314093c9
MK
14.\" Since the Linux kernel and libraries are constantly changing, this
15.\" manual page may be incorrect or out-of-date. The author(s) assume no
16.\" responsibility for errors or omissions, or for damages resulting from
c13182ef
MK
17.\" the use of the information contained herein.
18.\"
314093c9
MK
19.\" Formatted or processed versions of this manual, if unaccompanied by
20.\" the source, must acknowledge the copyright and authors of this work.
9f882130 21.\" %%%LICENSE_END
c13182ef 22.\"
314093c9 23.\" 2006-02-03, mtk, substantial wording changes and other improvements
00045cbb
MK
24.\" 2007-08-27, Lee Schermerhorn <Lee.Schermerhorn@hp.com>
25.\" more precise specification of behavior.
314093c9 26.\"
adfbcbeb 27.TH SET_MEMPOLICY 2 2008-08-15 Linux "Linux Programmer's Manual"
314093c9 28.SH NAME
73ae0a09 29set_mempolicy \- set default NUMA memory policy for a process and its children
314093c9 30.SH SYNOPSIS
521bf584 31.nf
c13182ef 32.B "#include <numaif.h>"
314093c9 33.sp
73ae0a09 34.BI "int set_mempolicy(int " mode ", unsigned long *" nodemask ,
521bf584 35.BI " unsigned long " maxnode );
73ae0a09 36.sp
4ed3353d 37Link with \fI\-lnuma\fP.
521bf584 38.fi
314093c9
MK
39.SH DESCRIPTION
40.BR set_mempolicy ()
73ae0a09
MK
41sets the NUMA memory policy of the calling process,
42which consists of a policy mode and zero or more nodes,
43to the values specified by the
44.IR mode ,
45.I nodemask
46and
0daa9e92 47.I maxnode
73ae0a09 48arguments.
314093c9
MK
49
50A NUMA machine has different
51memory controllers with different distances to specific CPUs.
73ae0a09 52The memory policy defines from which node memory is allocated for
c13182ef 53the process.
314093c9 54
73ae0a09 55This system call defines the default policy for the process.
ecccf7c2 56The process policy governs allocation of pages in the process's
73ae0a09
MK
57address space outside of memory ranges
58controlled by a more specific policy set by
314093c9 59.BR mbind (2).
73ae0a09 60The process default policy also controls allocation of any pages for
9a141bfb 61memory-mapped files mapped using the
73ae0a09
MK
62.BR mmap (2)
63call with the
64.B MAP_PRIVATE
cdba9253 65flag and that are only read [loaded] from by the process
9a141bfb 66and of memory-mapped files mapped using the
73ae0a09
MK
67.BR mmap (2)
68call with the
69.B MAP_SHARED
70flag, regardless of the access type.
33a0ccb2 71The policy is applied only when a new page is allocated
c13182ef
MK
72for the process.
73For anonymous memory this is when the page is first
314093c9
MK
74touched by the application.
75
73ae0a09
MK
76The
77.I mode
78argument must specify one of
314093c9
MK
79.BR MPOL_DEFAULT ,
80.BR MPOL_BIND ,
bcc7c6dc 81.BR MPOL_INTERLEAVE ,
73ae0a09 82or
314093c9 83.BR MPOL_PREFERRED .
73ae0a09 84All modes except
314093c9 85.B MPOL_DEFAULT
73ae0a09 86require the caller to specify via the
c13182ef 87.I nodemask
c4bb193f 88argument one or more nodes.
73ae0a09 89
f98b728e
MK
90The
91.I mode
92argument may also include an optional
adfbcbeb 93.IR "mode flag" .
f98b728e
MK
94The supported
95.I "mode flags"
96are:
97.TP
98.BR MPOL_F_STATIC_NODES " (since Linux 2.6.26)"
aa796481 99A nonempty
f98b728e
MK
100.I nodemask
101specifies physical node ids.
f6374cc2 102Linux will not remap the
f98b728e
MK
103.I nodemask
104when the process moves to a different cpuset context,
105nor when the set of nodes allowed by the process's
106current cpuset context changes.
107.TP
108.BR MPOL_F_RELATIVE_NODES " (since Linux 2.6.26)"
aa796481 109A nonempty
f98b728e
MK
110.I nodemask
111specifies node ids that are relative to the set of
4e836144 112node ids allowed by the process's current cpuset.
f98b728e 113.PP
c13182ef 114.I nodemask
00045cbb 115points to a bit mask of node IDs that contains up to
314093c9 116.I maxnode
c13182ef 117bits.
73ae0a09 118The bit mask size is rounded to the next multiple of
c13182ef 119.IR "sizeof(unsigned long)" ,
33a0ccb2 120but the kernel will use bits only up to
314093c9 121.IR maxnode .
73ae0a09
MK
122A NULL value of
123.I nodemask
124or a
125.I maxnode
126value of zero specifies the empty set of nodes.
127If the value of
128.I maxnode
129is zero,
130the
131.I nodemask
132argument is ignored.
f98b728e 133
cdba9253
MK
134Where a
135.I nodemask
136is required, it must contain at least one node that is on-line,
137allowed by the process's current cpuset context,
f98b728e
MK
138[unless the
139.B MPOL_F_STATIC_NODES
140mode flag is specified],
cdba9253 141and contains memory.
f98b728e
MK
142If the
143.B MPOL_F_STATIC_NODES
144is set in
145.I mode
146and a required
147.I nodemask
148contains no nodes that are allowed by the process's current cpuset context,
149the memory policy reverts to
150.IR "local allocation" .
151This effectively overrides the specified policy until the process's
152cpuset context includes one or more of the nodes specified by
fe48639f 153.IR nodemask .
314093c9 154
c13182ef 155The
314093c9 156.B MPOL_DEFAULT
24b74457 157mode specifies that any nondefault process memory policy be removed,
f98b728e 158so that the memory policy "falls back" to the system default policy.
88879aeb
MK
159The system default policy is "local allocation"\(emthat is,
160allocate memory on the node of the CPU that triggered the allocation.
c13182ef 161.I nodemask
73ae0a09
MK
162must be specified as NULL.
163If the "local node" contains no free memory, the system will
164attempt to allocate memory from a "near by" node.
314093c9
MK
165
166The
167.B MPOL_BIND
73ae0a09 168mode defines a strict policy that restricts memory allocation to the
c13182ef 169nodes specified in
314093c9 170.IR nodemask .
73ae0a09
MK
171If
172.I nodemask
173specifies more than one node, page allocations will come from
00045cbb 174the node with the lowest numeric node ID first, until that node
73ae0a09
MK
175contains no free memory.
176Allocations will then come from the node with the next highest
00045cbb 177node ID specified in
73ae0a09
MK
178.I nodemask
179and so forth, until none of the specified nodes contain free memory.
180Pages will not be allocated from any node not specified in the
181.IR nodemask .
314093c9
MK
182
183.B MPOL_INTERLEAVE
73ae0a09
MK
184interleaves page allocations across the nodes specified in
185.I nodemask
00045cbb 186in numeric node ID order.
73ae0a09
MK
187This optimizes for bandwidth instead of latency
188by spreading out pages and memory accesses to those pages across
189multiple nodes.
190However, accesses to a single page will still be limited to
191the memory bandwidth of a single node.
192.\" NOTE: the following sentence doesn't make sense in the context
193.\" of set_mempolicy() -- no memory area specified.
194.\" To be effective the memory area should be fairly large,
195.\" at least 1MB or bigger.
314093c9
MK
196
197.B MPOL_PREFERRED
c13182ef 198sets the preferred node for allocation.
73ae0a09
MK
199The kernel will try to allocate pages from this node first
200and fall back to "near by" nodes if the preferred node is low on free
c13182ef 201memory.
73ae0a09
MK
202If
203.I nodemask
00045cbb 204specifies more than one node ID, the first node in the
73ae0a09
MK
205mask will be selected as the preferred node.
206If the
c13182ef 207.I nodemask
73ae0a09
MK
208and
209.I maxnode
1313d297
MK
210arguments specify the empty set, then the policy
211specifies "local allocation"
212(like the system default policy discussed above).
314093c9 213
73ae0a09 214The process memory policy is preserved across an
3bd6a9b1
MK
215.BR execve (2),
216and is inherited by child processes created using
c13182ef
MK
217.BR fork (2)
218or
314093c9 219.BR clone (2).
314093c9
MK
220.SH RETURN VALUE
221On success,
222.BR set_mempolicy ()
223returns 0;
224on error, \-1 is returned and
c13182ef 225.I errno
314093c9 226is set to indicate the error.
73ae0a09
MK
227.SH ERRORS
228.TP
b3a7b55e
MK
229.B EFAULT
230Part of all of the memory range specified by
231.I nodemask
232and
233.I maxnode
234points outside your accessible address space.
235.TP
73ae0a09 236.B EINVAL
4d2be0ee
MK
237.I mode
238is invalid.
73ae0a09
MK
239Or,
240.I mode
241is
00045cbb 242.B MPOL_DEFAULT
73ae0a09
MK
243and
244.I nodemask
aa796481 245is nonempty,
73ae0a09
MK
246or
247.I mode
248is
00045cbb 249.B MPOL_BIND
73ae0a09 250or
00045cbb 251.B MPOL_INTERLEAVE
73ae0a09
MK
252and
253.I nodemask
254is empty.
255Or,
256.I maxnode
257specifies more than a page worth of bits.
258Or,
259.I nodemask
00045cbb 260specifies one or more node IDs that are
cdba9253 261greater than the maximum supported node ID.
00045cbb 262Or, none of the node IDs specified by
73ae0a09 263.I nodemask
cdba9253
MK
264are on-line and allowed by the process's current cpuset context,
265or none of the specified nodes contain memory.
f98b728e
MK
266Or, the
267.I mode
268argument specified both
269.B MPOL_F_STATIC_NODES
270and
271.BR MPOL_F_RELATIVE_NODES .
73ae0a09 272.TP
73ae0a09
MK
273.B ENOMEM
274Insufficient kernel memory was available.
adfbcbeb
MK
275.SH VERSIONS
276The
277.BR set_mempolicy (),
278system call was added to the Linux kernel in version 2.6.7.
9d9dc1e8 279.SH CONFORMING TO
8382f16d 280This system call is Linux-specific.
a1d5f77c
MK
281.SH NOTES
282Process policy is not remembered if the page is swapped out.
73ae0a09
MK
283When such a page is paged back in, it will use the policy of
284the process or memory range that is in effect at the time the
285page is allocated.
adfbcbeb
MK
286
287For information on library support, see
288.BR numa (7).
314093c9 289.SH SEE ALSO
fa23e023 290.BR get_mempolicy (2),
f0c34053 291.BR getcpu (2),
314093c9 292.BR mbind (2),
73ae0a09 293.BR mmap (2),
a18e2edb
MK
294.BR numa (3),
295.BR cpuset (7),
adfbcbeb 296.BR numa (7),
a18e2edb 297.BR numactl (8)