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