original/man2/mbind.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 MBIND 2 2008-08-15 Linux "Linux Programmer's Manual"
  26 .SH NAME
  27 mbind \- Set memory policy for a memory range
  28 .SH SYNOPSIS
  29 .nf
  30 .B "#include <numaif.h>"
  31 .sp
  32 .BI "int mbind(void *" addr ", unsigned long " len  ", int " mode ,
  33 .BI "          unsigned long *" nodemask  ", unsigned long " maxnode ,
  34 .BI "          unsigned " flags );
  35 .sp
  36 Link with \fI\-lnuma\fP.
  37 .fi
  38 .SH DESCRIPTION
  39 .BR mbind ()
  40 sets the NUMA memory policy,
  41 which consists of a policy mode and zero or more nodes,
  42 for the memory range starting with
  43 .I addr
  44 and continuing for
  45 .I len
  46 bytes.
  47 The memory policy defines from which node memory is allocated.
  48
  49 If the memory range specified by the
  50 .IR addr " and " len
  51 arguments includes an "anonymous" region of memory\(emthat is
  52 a region of memory created using the
  53 .BR mmap (2)
  54 system call with the
  55 .BR MAP_ANONYMOUS \(emor
  56 a memory mapped file, mapped using the
  57 .BR mmap (2)
  58 system call with the
  59 .B MAP_PRIVATE
  60 flag, pages will only be allocated according to the specified
  61 policy when the application writes [stores] to the page.
  62 For anonymous regions, an initial read access will use a shared
  63 page in the kernel containing all zeros.
  64 For a file mapped with
  65 .BR MAP_PRIVATE ,
  66 an initial read access will allocate pages according to the
  67 process policy of the process that causes the page to be allocated.
  68 This may not be the process that called
  69 .BR mbind ().
  70
  71 The specified policy will be ignored for any
  72 .B MAP_SHARED
  73 mappings in the specified memory range.
  74 Rather the pages will be allocated according to the process policy
  75 of the process that caused the page to be allocated.
  76 Again, this may not be the process that called
  77 .BR mbind ().
  78
  79 If the specified memory range includes a shared memory region
  80 created using the
  81 .BR shmget (2)
  82 system call and attached using the
  83 .BR shmat (2)
  84 system call,
  85 pages allocated for the anonymous or shared memory region will
  86 be allocated according to the policy specified, regardless which
  87 process attached to the shared memory segment causes the allocation.
  88 If, however, the shared memory region was created with the
  89 .B SHM_HUGETLB
  90 flag,
  91 the huge pages will be allocated according to the policy specified
  92 only if the page allocation is caused by the process that calls
  93 .BR mbind ()
  94 for that region.
  95
  96 By default,
  97 .BR mbind ()
  98 only has an effect for new allocations; if the pages inside
  99 the range have been already touched before setting the policy,
 100 then the policy has no effect.
 101 This default behavior may be overridden by the
 102 .B MPOL_MF_MOVE
 103 and
 104 .B MPOL_MF_MOVE_ALL
 105 flags described below.
 106
 107 The
 108 .I mode
 109 argument must specify one of
 110 .BR MPOL_DEFAULT ,
 111 .BR MPOL_BIND ,
 112 .B MPOL_INTERLEAVE
 113 or
 114 .BR MPOL_PREFERRED .
 115 All policy modes except
 116 .B MPOL_DEFAULT
 117 require the caller to specify via the
 118 .I nodemask
 119 argument,
 120 the node or nodes to which the mode applies.
 121
 122 The
 123 .I mode
 124 argument may also include an optional
 125 .IR "mode flag ".
 126 The supported
 127 .I "mode flags"
 128 are:
 129 .TP
 130 .BR MPOL_F_STATIC_NODES " (since Linux-2.6.26)"
 131 A nonempty
 132 .I nodemask
 133 specifies physical node ids.
 134 Linux does not remap the
 135 .I nodemask
 136 when the process moves to a different cpuset context,
 137 nor when the set of nodes allowed by the process's
 138 current cpuset context changes.
 139 .TP
 140 .BR MPOL_F_RELATIVE_NODES " (since Linux-2.6.26)"
 141 A nonempty
 142 .I nodemask
 143 specifies node ids that are relative to the set of
 144 node ids allowed  by the process's current cpuset.
 145 .PP
 146 .I nodemask
 147 points to a bitmask of nodes containing up to
 148 .I maxnode
 149 bits.
 150 The bit mask size is rounded to the next multiple of
 151 .IR "sizeof(unsigned long)" ,
 152 but the kernel will only use bits up to
 153 .IR maxnode .
 154 A NULL value of
 155 .I nodemask
 156 or a
 157 .I maxnode
 158 value of zero specifies the empty set of nodes.
 159 If the value of
 160 .I maxnode
 161 is zero,
 162 the
 163 .I nodemask
 164 argument is ignored.
 165 Where a
 166 .I nodemask
 167 is required, it must contain at least one node that is on-line,
 168 allowed by the process's current cpuset context
 169 [unless the
 170 .B MPOL_F_STATIC_NODES
 171 mode flag is specified],
 172 and contains memory.
 173
 174 The
 175 .B MPOL_DEFAULT
 176 mode requests that any nondefault policy be removed,
 177 restoring default behavior.
 178 When applied to a range of memory via
 179 .BR mbind (),
 180 this means to use the process policy,
 181 which may have been set with
 182 .BR set_mempolicy (2).
 183 If the mode of the process policy is also
 184 .BR MPOL_DEFAULT ,
 185 the system-wide default policy will be used.
 186 The system-wide default policy allocates
 187 pages on the node of the CPU that triggers the allocation.
 188 For
 189 .BR MPOL_DEFAULT ,
 190 the
 191 .I nodemask
 192 and
 193 .I maxnode
 194 arguments must be specify the empty set of nodes.
 195
 196 The
 197 .B MPOL_BIND
 198 mode specifies a strict policy that restricts memory allocation to
 199 the nodes specified in
 200 .IR nodemask .
 201 If
 202 .I nodemask
 203 specifies more than one node, page allocations will come from
 204 the node with the lowest numeric node ID first, until that node
 205 contains no free memory.
 206 Allocations will then come from the node with the next highest
 207 node ID specified in
 208 .I nodemask
 209 and so forth, until none of the specified nodes contain free memory.
 210 Pages will not be allocated from any node not specified in the
 211 .IR nodemask .
 212
 213 The
 214 .B MPOL_INTERLEAVE
 215 mode specifies that page allocations be interleaved across the
 216 set of nodes specified in
 217 .IR nodemask .
 218 This optimizes for bandwidth instead of latency
 219 by spreading out pages and memory accesses to those pages across
 220 multiple nodes.
 221 To be effective the memory area should be fairly large,
 222 at least 1MB or bigger with a fairly uniform access pattern.
 223 Accesses to a single page of the area will still be limited to
 224 the memory bandwidth of a single node.
 225
 226 .B MPOL_PREFERRED
 227 sets the preferred node for allocation.
 228 The kernel will try to allocate pages from this
 229 node first and fall back to other nodes if the
 230 preferred nodes is low on free memory.
 231 If
 232 .I nodemask
 233 specifies more than one node ID, the first node in the
 234 mask will be selected as the preferred node.
 235 If the
 236 .I nodemask
 237 and
 238 .I maxnode
 239 arguments specify the empty set, then the memory is allocated on
 240 the node of the CPU that triggered the allocation.
 241 This is the only way to specify "local allocation" for a
 242 range of memory via
 243 .BR mbind ().
 244
 245 If
 246 .B MPOL_MF_STRICT
 247 is passed in
 248 .I flags
 249 and
 250 .I mode
 251 is not
 252 .BR MPOL_DEFAULT ,
 253 then the call will fail with the error
 254 .B EIO
 255 if the existing pages in the memory range don't follow the policy.
 256 .\" According to the kernel code, the following is not true
 257 .\" --Lee Schermerhorn
 258 .\" In 2.6.16 or later the kernel will also try to move pages
 259 .\" to the requested node with this flag.
 260
 261 If
 262 .B MPOL_MF_MOVE
 263 is specified in
 264 .IR flags ,
 265 then the kernel will attempt to move all the existing pages
 266 in the memory range so that they follow the policy.
 267 Pages that are shared with other processes will not be moved.
 268 If
 269 .B MPOL_MF_STRICT
 270 is also specified, then the call will fail with the error
 271 .B EIO
 272 if some pages could not be moved.
 273
 274 If
 275 .B MPOL_MF_MOVE_ALL
 276 is passed in
 277 .IR flags ,
 278 then the kernel will attempt to move all existing pages in the memory range
 279 regardless of whether other processes use the pages.
 280 The calling process must be privileged
 281 .RB ( CAP_SYS_NICE )
 282 to use this flag.
 283 If
 284 .B MPOL_MF_STRICT
 285 is also specified, then the call will fail with the error
 286 .B EIO
 287 if some pages could not be moved.
 288 .\" ---------------------------------------------------------------
 289 .SH RETURN VALUE
 290 On success,
 291 .BR mbind ()
 292 returns 0;
 293 on error, \-1 is returned and
 294 .I errno
 295 is set to indicate the error.
 296 .\" ---------------------------------------------------------------
 297 .SH ERRORS
 298 .\"  I think I got all of the error returns.  --Lee Schermerhorn
 299 .TP
 300 .B EFAULT
 301 Part or all of the memory range specified by
 302 .I nodemask
 303 and
 304 .I maxnode
 305 points outside your accessible address space.
 306 Or, there was an unmapped hole in the specified memory range.
 307 .TP
 308 .B EINVAL
 309 An invalid value was specified for
 310 .I flags
 311 or
 312 .IR mode ;
 313 or
 314 .I addr + len
 315 was less than
 316 .IR addr ;
 317 or
 318 .I addr
 319 is not a multiple of the system page size.
 320 Or,
 321 .I mode
 322 is
 323 .B MPOL_DEFAULT
 324 and
 325 .I nodemask
 326 specified a nonempty set;
 327 or
 328 .I mode
 329 is
 330 .B MPOL_BIND
 331 or
 332 .B MPOL_INTERLEAVE
 333 and
 334 .I nodemask
 335 is empty.
 336 Or,
 337 .I maxnode
 338 exceeds a kernel-imposed limit.
 339 .\" As at 2.6.23, this limit is "a page worth of bits", e.g.,
 340 .\" 8 * 4096 bits, assuming a 4kB page size.
 341 Or,
 342 .I nodemask
 343 specifies one or more node IDs that are
 344 greater than the maximum supported node ID.
 345 Or, none of the node IDs specified by
 346 .I nodemask
 347 are on-line and allowed by the process's current cpuset context,
 348 or none of the specified nodes contain memory.
 349 Or, the
 350 .I mode
 351 argument specified both
 352 .B MPOL_F_STATIC_NODES
 353 and
 354 .BR MPOL_F_RELATIVE_NODES .
 355 .TP
 356 .B EIO
 357 .B MPOL_MF_STRICT
 358 was specified and an existing page was already on a node
 359 that does not follow the policy;
 360 or
 361 .B MPOL_MF_MOVE
 362 or
 363 .B MPOL_MF_MOVE_ALL
 364 was specified and the kernel was unable to move all existing
 365 pages in the range.
 366 .TP
 367 .B ENOMEM
 368 Insufficient kernel memory was available.
 369 .TP
 370 .B EPERM
 371 The
 372 .I flags
 373 argument included the
 374 .B MPOL_MF_MOVE_ALL
 375 flag and the caller does not have the
 376 .B CAP_SYS_NICE
 377 privilege.
 378 .\" ---------------------------------------------------------------
 379 .SH VERSIONS
 380 The
 381 .BR mbind ()
 382 system call was added to the Linux kernel in version 2.6.7.
 383 .SH CONFORMING TO
 384 This system call is Linux-specific.
 385 .SH NOTES
 386 For information on library support, see
 387 .BR numa (7).
 388
 389 NUMA policy is not supported on a memory mapped file range
 390 that was mapped with the
 391 .B MAP_SHARED
 392 flag.
 393
 394 The
 395 .B MPOL_DEFAULT
 396 mode can have different effects for
 397 .BR mbind ()
 398 and
 399 .BR set_mempolicy (2).
 400 When
 401 .B MPOL_DEFAULT
 402 is specified for
 403 .BR set_mempolicy (2),
 404 the process's policy reverts to system default policy
 405 or local allocation.
 406 When
 407 .B MPOL_DEFAULT
 408 is specified for a range of memory using
 409 .BR mbind (),
 410 any pages subsequently allocated for that range will use
 411 the process's policy, as set by
 412 .BR set_mempolicy (2).
 413 This effectively removes the explicit policy from the
 414 specified range, "falling back" to a possibly nondefault
 415 policy.
 416 To select explicit "local allocation" for a memory range,
 417 specify a
 418 .I mode
 419 of
 420 .B MPOL_PREFERRED
 421 with an empty set of nodes.
 422 This method will work for
 423 .BR set_mempolicy (2),
 424 as well.
 425
 426 Support for huge page policy was added with 2.6.16.
 427 For interleave policy to be effective on huge page mappings the
 428 policied memory needs to be tens of megabytes or larger.
 429
 430 .B MPOL_MF_STRICT
 431 is ignored on huge page mappings.
 432
 433 .B MPOL_MF_MOVE
 434 and
 435 .B MPOL_MF_MOVE_ALL
 436 are only available on Linux 2.6.16 and later.
 437 .SH SEE ALSO
 438 .BR get_mempolicy (2),
 439 .BR getcpu (2),
 440 .BR mmap (2),
 441 .BR set_mempolicy (2),
 442 .BR shmat (2),
 443 .BR shmget (2),
 444 .BR numa (3),
 445 .BR cpuset (7),
 446 .BR numa (7),
 447 .BR numactl (8)