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