original/man2/get_mempolicy.2

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