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