man2/get_mempolicy.2

   1 .\" Copyright 2003,2004 Andi Kleen, SuSE Labs.
   2 .\" and Copyright 2007 Lee Schermerhorn, Hewlett Packard
   3 .\"
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.
  17 .\"
  18 .\" Formatted or processed versions of this manual, if unaccompanied by
  19 .\" the source, must acknowledge the copyright and authors of this work.
  20 .\"
  21 .\" 2006-02-03, mtk, substantial wording changes and other improvements
  22 .\" 2007-08-27, Lee Schermerhorn <Lee.Schermerhorn@hp.com>
  23 .\"     more precise specification of behavior.
  24 .\"
  25 .TH GET_MEMPOLICY 2 2007-08-27 Linux "Linux Programmer's Manual"
  26 .SH NAME
  27 get_mempolicy \- Retrieve NUMA memory policy for a process
  28 .SH SYNOPSIS
  29 .B "#include <numaif.h>"
  30 .nf
  31 .sp
  32 .BI "int get_mempolicy(int *" mode ", unsigned long *" nodemask ,
  33 .BI "                  unsigned long " maxnode ", unsigned long " addr ,
  34 .BI "                  unsigned long " flags );
  35 .sp
  36 Link with \fI\-lnuma\fP
  37 .fi
  38 .SH DESCRIPTION
  39 .BR get_mempolicy ()
  40 retrieves the NUMA policy of the calling process or of a memory address,
  41 depending on the setting of
  42 .IR flags .
  43
  44 A NUMA machine has different
  45 memory controllers with different distances to specific CPUs.
  46 The memory policy defines from which node memory is allocated for
  47 the process.
  48
  49 If
  50 .I flags
  51 is specified as 0,
  52 then information about the calling process's default policy
  53 (as set by
  54 .BR set_mempolicy (2))
  55 is returned.
  56
  57 If
  58 .I flags
  59 specifies
  60 .BR MPOL_F_ADDR ,
  61 then information is returned about the policy governing the memory
  62 address given in
  63 .IR addr .
  64 This policy may be different from the process's default policy if
  65 .BR mbind (2)
  66 or one of the helper functions described in
  67 .BR numa (3)
  68 has been used to establish a policy for the memory range containing
  69 .IR addr .
  70
  71 If the
  72 .I mode
  73 argument is not NULL, then
  74 .IR get_mempolicy ()
  75 will store the policy mode of the requested NUMA policy in the location
  76 pointed to by this argument.
  77 If
  78 .I nodemask
  79 is not NULL, then the nodemask associated with the policy will be stored
  80 in the location pointed to by this argument.
  81 .I maxnode
  82 specifies the number of node IDs
  83 that can be stored into
  84 .IR nodemask \(emthat
  85 is, the maximum node ID plus one.
  86 The value specified by
  87 .I maxnode
  88 is always rounded to a multiple of
  89 .IR "sizeof(unsigned long)" .
  90
  91 If
  92 .I flags
  93 specifies both
  94 .B MPOL_F_NODE
  95 and
  96 .BR MPOL_F_ADDR ,
  97 .IR get_mempolicy ()
  98 will return the node ID of the node on which the address
  99 .I addr
 100 is allocated into the location pointed to by
 101 .IR mode .
 102 If no page has yet been allocated for the specified address,
 103 .IR get_mempolicy ()
 104 will allocate a page as if the process had performed a read
 105 [load] access to that address, and return the ID of the node
 106 where that page was allocated.
 107
 108 If
 109 .I flags
 110 specifies
 111 .BR MPOL_F_NODE ,
 112 but not
 113 .BR MPOL_F_ADDR ,
 114 and the process's current policy is
 115 .BR MPOL_INTERLEAVE ,
 116 then
 117 .IR get_mempolicy ()
 118 will return in the location pointed to by a non-NULL
 119 .I mode
 120 argument,
 121 the node ID of the next node that will be used for
 122 interleaving of internal kernel pages allocated on behalf of the process.
 123 .\" Note:  code returns next interleave node via 'mode' argument -Lee Schermerhorn
 124 These allocations include pages for memory mapped files in
 125 process memory ranges mapped using the
 126 .IR mmap (2)
 127 call with the
 128 .B MAP_PRIVATE
 129 flag for read accesses, and in memory ranges mapped with the
 130 .B MAP_SHARED
 131 flag for all accesses.
 132
 133 Other flag values are reserved.
 134
 135 For an overview of the possible policies see
 136 .BR set_mempolicy (2).
 137 .SH RETURN VALUE
 138 On success,
 139 .BR get_mempolicy ()
 140 returns 0;
 141 on error, \-1 is returned and
 142 .I errno
 143 is set to indicate the error.
 144 .SH ERRORS
 145 .TP
 146 .B EINVAL
 147 The value specified by
 148 .I maxnode
 149 is less than the number of node IDs supported by the system.
 150 Or
 151 .I flags
 152 specified values other than
 153 .B MPOL_F_NODE
 154 or
 155 .BR MPOL_F_ADDR ;
 156 or
 157 .I flags
 158 specified
 159 .B MPOL_F_ADDR
 160 and
 161 .I addr
 162 is NULL,
 163 or
 164 .I flags
 165 did not specify
 166 .B MPOL_F_ADDR
 167 and
 168 .I addr
 169 is not NULL.
 170 Or,
 171 .I flags
 172 specified
 173 .B MPOL_F_NODE
 174 but not
 175 .B MPOL_F_ADDR
 176 and the current process policy is not
 177 .BR MPOL_INTERLEAVE .
 178 (And there are other EINVAL cases.)
 179 .TP
 180 .B EFAULT
 181 Part of all of the memory range specified by
 182 .I nodemask
 183 and
 184 .I maxnode
 185 points outside your accessible address space.
 186 .SH NOTES
 187 If the mode of the process policy or the policy governing allocations at the
 188 specified address is
 189 .B MPOL_PREFERRED
 190 and this policy was installed with an empty
 191 .IR nodemask \(emspecifying
 192 local allocation,
 193 .IR get_mempolicy ()
 194 will return the mask of on-line node IDs in the location pointed to by
 195 a non-NULL
 196 .I nodemask
 197 argument.
 198 This mask does not take into consideration any adminstratively imposed
 199 restrictions on the process's context.
 200 .\" FIXME:
 201 .\" "context" above refers to cpusets.
 202 .\" No man page to reference. --Lee Schermerhorn
 203 .\"
 204 .\"  Christoph says the following is untrue.  These are "fully supported."
 205 .\"  Andi concedes that he has lost this battle and approves [?]
 206 .\"  updating the man pages to document the behavior.  --Lee Schermerhorn
 207 .\" This manual page is incomplete:
 208 .\" it does not document the details the
 209 .\" .BR MPOL_F_NODE
 210 .\" flag,
 211 .\" which modifies the operation of
 212 .\" .BR get_mempolicy ().
 213 .\" This is deliberate: this flag is not intended for application use,
 214 .\" and its operation may change or it may be removed altogether in
 215 .\" future kernel versions.
 216 .\" .B Do not use it.
 217 .SS "Versions and Library Support"
 218 See
 219 .BR mbind (2).
 220 .SH SEE ALSO
 221 .BR mbind (2),
 222 .BR mmap (2),
 223 .BR set_mempolicy (2),
 224 .BR numactl (8),
 225 .BR numa (3)