Debian Codegraph @

upstream/debian-unstable/man2/get_mempolicy.2

raw
1 .\" Copyright 2003-2004, Andi Kleen <[email protected]>
2 .\" Copyright 2003-2004, SuSE Labs
3 .\" Copyright 2007, Lee Schermerhorn <[email protected]>
4 .\" Copyright 2007, Hewlett Packard
5 .\" Copyright, the authors of the Linux man-pages project
6 .\"
7 .\" SPDX-License-Identifier: Linux-man-pages-copyleft-var
8 .\"
9 .TH get_mempolicy 2 2026-02-08 "Linux man-pages 6.18"
10 .SH NAME
11 get_mempolicy \- retrieve NUMA memory policy for a thread
12 .SH LIBRARY
13 NUMA (Non-Uniform Memory Access) policy library
14 .RI ( libnuma ,\~ \-lnuma )
15 .SH SYNOPSIS
16 .B "#include <numaif.h>"
17 .nf
18 .P
19 .BR "long get_mempolicy(" "unsigned long maxnode;"
20 .BI " int *" mode ,
21 .BI " unsigned long " nodemask [( maxnode " + ULONG_WIDTH \- 1)"
22 .B " / ULONG_WIDTH],"
23 .BI " unsigned long " maxnode ", void *" addr ,
24 .BI " unsigned long " flags );
25 .fi
26 .SH DESCRIPTION
27 .BR get_mempolicy ()
28 retrieves the NUMA policy of the calling thread or of a memory address,
29 depending on the setting of
30 .IR flags .
31 .P
32 A NUMA machine has different
33 memory controllers with different distances to specific CPUs.
34 The memory policy defines from which node memory is allocated for
35 the thread.
36 .P
37 If
38 .I flags
39 is specified as 0,
40 then information about the calling thread's default policy
41 (as set by
42 .BR set_mempolicy (2))
43 is returned, in the buffers pointed to by
44 .I mode
45 and
46 .IR nodemask .
47 The value returned in these arguments
48 may be used to restore the thread's policy to its state at
49 the time of the call to
50 .BR get_mempolicy ()
51 using
52 .BR set_mempolicy (2).
53 When
54 .I flags
55 is 0,
56 .I addr
57 must be specified as NULL.
58 .P
59 If
60 .I flags
61 specifies
62 .B MPOL_F_MEMS_ALLOWED
63 (available since Linux 2.6.24), the
64 .I mode
65 argument is ignored and the set of nodes (memories) that the
66 thread is allowed to specify in subsequent calls to
67 .BR mbind (2)
68 or
69 .BR set_mempolicy (2)
70 (in the absence of any
71 .IR "mode flags" )
72 is returned in
73 .IR nodemask .
74 It is not permitted to combine
75 .B MPOL_F_MEMS_ALLOWED
76 with either
77 .B MPOL_F_ADDR
78 or
79 .BR MPOL_F_NODE .
80 .P
81 If
82 .I flags
83 specifies
84 .BR MPOL_F_ADDR ,
85 then information is returned about the policy governing the memory
86 address given in
87 .IR addr .
88 This policy may be different from the thread's default policy if
89 .BR mbind (2)
90 or one of the helper functions described in
91 .BR numa (3)
92 has been used to establish a policy for the memory range containing
93 .IR addr .
94 .P
95 If the
96 .I mode
97 argument is not NULL, then
98 .BR get_mempolicy ()
99 will store the policy mode and any optional
100 .I "mode flags"
101 of the requested NUMA policy in the location pointed to by this argument.
102 If
103 .I nodemask
104 is not NULL, then the nodemask associated with the policy will be stored
105 in the location pointed to by this argument.
106 .I maxnode
107 specifies the number of node IDs
108 that can be stored into
109 .IR nodemask \[em]that
110 is, the maximum node ID plus one.
111 The value specified by
112 .I maxnode
113 is always rounded to a multiple of
114 .IR "sizeof(unsigned\ long)*8" .
115 .P
116 If
117 .I flags
118 specifies both
119 .B MPOL_F_NODE
120 and
121 .BR MPOL_F_ADDR ,
122 .BR get_mempolicy ()
123 will return the node ID of the node on which the address
124 .I addr
125 is allocated into the location pointed to by
126 .IR mode .
127 If no page has yet been allocated for the specified address,
128 .BR get_mempolicy ()
129 will allocate a page as if the thread had performed a read
130 (load) access to that address, and return the ID of the node
131 where that page was allocated.
132 .P
133 If
134 .I flags
135 specifies
136 .BR MPOL_F_NODE ,
137 but not
138 .BR MPOL_F_ADDR ,
139 and the thread's current policy is
140 .B MPOL_INTERLEAVE
141 or
142 .BR MPOL_WEIGHTED_INTERLEAVE ,
143 then
144 .BR get_mempolicy ()
145 will return in the location pointed to by a non-NULL
146 .I mode
147 argument,
148 the node ID of the next node that will be used for
149 interleaving of internal kernel pages allocated on behalf of the thread.
150 .\" Note: code returns next interleave node via 'mode' argument -Lee Schermerhorn
151 These allocations include pages for memory-mapped files in
152 process memory ranges mapped using the
153 .BR mmap (2)
154 call with the
155 .B MAP_PRIVATE
156 flag for read accesses, and in memory ranges mapped with the
157 .B MAP_SHARED
158 flag for all accesses.
159 .P
160 Other flag values are reserved.
161 .P
162 For an overview of the possible policies see
163 .BR set_mempolicy (2).
164 .SH RETURN VALUE
165 On success,
166 .BR get_mempolicy ()
167 returns 0;
168 on error, \-1 is returned and
169 .I errno
170 is set to indicate the error.
171 .SH ERRORS
172 .TP
173 .B EFAULT
174 Part of all of the memory range specified by
175 .I nodemask
176 and
177 .I maxnode
178 points outside your accessible address space.
179 .TP
180 .B EINVAL
181 The value specified by
182 .I maxnode
183 is less than the number of node IDs supported by the system.
184 Or
185 .I flags
186 specified values other than
187 .B MPOL_F_NODE
188 or
189 .BR MPOL_F_ADDR ;
190 or
191 .I flags
192 specified
193 .B MPOL_F_ADDR
194 and
195 .I addr
196 is NULL,
197 or
198 .I flags
199 did not specify
200 .B MPOL_F_ADDR
201 and
202 .I addr
203 is not NULL.
204 Or,
205 .I flags
206 specified
207 .B MPOL_F_NODE
208 but not
209 .B MPOL_F_ADDR
210 and the current thread policy is neither
211 .B MPOL_INTERLEAVE
212 nor
213 .BR MPOL_WEIGHTED_INTERLEAVE .
214 Or,
215 .I flags
216 specified
217 .B MPOL_F_MEMS_ALLOWED
218 with either
219 .B MPOL_F_ADDR
220 or
221 .BR MPOL_F_NODE .
222 (And there are other
223 .B EINVAL
224 cases.)
225 .SH STANDARDS
226 Linux.
227 .SH HISTORY
228 Linux 2.6.7.
229 .SH NOTES
230 For information on library support, see
231 .BR numa (7).
232 .SH SEE ALSO
233 .BR getcpu (2),
234 .BR mbind (2),
235 .BR mmap (2),
236 .BR set_mempolicy (2),
237 .BR numa (3),
238 .BR numa (7),
239 .BR numactl (8)