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 2016-12-12 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 .sp
  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 .sp
  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
  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
  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
  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
 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
 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
 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
 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 the lowest numeric node ID first, until that node
 219 contains no free memory.
 220 Allocations will then come from the node with the next highest
 221 node ID specified in
 222 .I nodemask
 223 and so forth, until none of the specified nodes contain free memory.
 224 Pages will not be allocated from any node not specified in the
 225 .IR nodemask .
 226 .TP
 227 .B MPOL_INTERLEAVE
 228 This mode specifies that page allocations be interleaved across the
 229 set of nodes specified in
 230 .IR nodemask .
 231 This optimizes for bandwidth instead of latency
 232 by spreading out pages and memory accesses to those pages across
 233 multiple nodes.
 234 To be effective the memory area should be fairly large,
 235 at least 1MB or bigger with a fairly uniform access pattern.
 236 Accesses to a single page of the area will still be limited to
 237 the memory bandwidth of a single node.
 238 .TP
 239 .B MPOL_PREFERRED
 240 This mode sets the preferred node for allocation.
 241 The kernel will try to allocate pages from this
 242 node first and fall back to other nodes if the
 243 preferred nodes is low on free memory.
 244 If
 245 .I nodemask
 246 specifies more than one node ID, the first node in the
 247 mask will be selected as the preferred node.
 248 If the
 249 .I nodemask
 250 and
 251 .I maxnode
 252 arguments specify the empty set, then the memory is allocated on
 253 the node of the CPU that triggered the allocation.
 254 .TP
 255 .BR MPOL_LOCAL " (since Linux 3.8)"
 256 .\" commit 479e2802d09f1e18a97262c4c6f8f17ae5884bd8
 257 .\" commit f2a07f40dbc603c15f8b06e6ec7f768af67b424f
 258 This mode specifies "local allocation"; the memory is allocated on
 259 the node of the CPU that triggered the allocation (the "local node").
 260 The
 261 .I nodemask
 262 and
 263 .I maxnode
 264 arguments must specify the empty set.
 265 If the "local node" is low on free memory,
 266 the kernel will try to allocate memory from other nodes.
 267 The kernel will allocate memory from the "local node"
 268 whenever memory for this node is available.
 269 If the "local node" is not allowed by the thread's current cpuset context,
 270 the kernel will try to allocate memory from other nodes.
 271 The kernel will allocate memory from the "local node" whenever
 272 it becomes allowed by the thread's current cpuset context.
 273 By contrast,
 274 .B MPOL_DEFAULT
 275 reverts to the memory policy of the thread (which may be set via
 276 .BR set_mempolicy (2));
 277 that policy may be something other than "local allocation".
 278 .PP
 279 If
 280 .B MPOL_MF_STRICT
 281 is passed in
 282 .I flags
 283 and
 284 .I mode
 285 is not
 286 .BR MPOL_DEFAULT ,
 287 then the call will fail with the error
 288 .B EIO
 289 if the existing pages in the memory range don't follow the policy.
 290 .\" According to the kernel code, the following is not true
 291 .\" --Lee Schermerhorn
 292 .\" In 2.6.16 or later the kernel will also try to move pages
 293 .\" to the requested node with this flag.
 294
 295 If
 296 .B MPOL_MF_MOVE
 297 is specified in
 298 .IR flags ,
 299 then the kernel will attempt to move all the existing pages
 300 in the memory range so that they follow the policy.
 301 Pages that are shared with other processes will not be moved.
 302 If
 303 .B MPOL_MF_STRICT
 304 is also specified, then the call will fail with the error
 305 .B EIO
 306 if some pages could not be moved.
 307
 308 If
 309 .B MPOL_MF_MOVE_ALL
 310 is passed in
 311 .IR flags ,
 312 then the kernel will attempt to move all existing pages in the memory range
 313 regardless of whether other processes use the pages.
 314 The calling thread must be privileged
 315 .RB ( CAP_SYS_NICE )
 316 to use this flag.
 317 If
 318 .B MPOL_MF_STRICT
 319 is also specified, then the call will fail with the error
 320 .B EIO
 321 if some pages could not be moved.
 322 .\" ---------------------------------------------------------------
 323 .SH RETURN VALUE
 324 On success,
 325 .BR mbind ()
 326 returns 0;
 327 on error, \-1 is returned and
 328 .I errno
 329 is set to indicate the error.
 330 .\" ---------------------------------------------------------------
 331 .SH ERRORS
 332 .\"  I think I got all of the error returns.  --Lee Schermerhorn
 333 .TP
 334 .B EFAULT
 335 Part or all of the memory range specified by
 336 .I nodemask
 337 and
 338 .I maxnode
 339 points outside your accessible address space.
 340 Or, there was an unmapped hole in the specified memory range specified by
 341 .IR addr
 342 and
 343 .IR len .
 344 .TP
 345 .B EINVAL
 346 An invalid value was specified for
 347 .I flags
 348 or
 349 .IR mode ;
 350 or
 351 .I addr + len
 352 was less than
 353 .IR addr ;
 354 or
 355 .I addr
 356 is not a multiple of the system page size.
 357 Or,
 358 .I mode
 359 is
 360 .B MPOL_DEFAULT
 361 and
 362 .I nodemask
 363 specified a nonempty set;
 364 or
 365 .I mode
 366 is
 367 .B MPOL_BIND
 368 or
 369 .B MPOL_INTERLEAVE
 370 and
 371 .I nodemask
 372 is empty.
 373 Or,
 374 .I maxnode
 375 exceeds a kernel-imposed limit.
 376 .\" As at 2.6.23, this limit is "a page worth of bits", e.g.,
 377 .\" 8 * 4096 bits, assuming a 4kB page size.
 378 Or,
 379 .I nodemask
 380 specifies one or more node IDs that are
 381 greater than the maximum supported node ID.
 382 Or, none of the node IDs specified by
 383 .I nodemask
 384 are on-line and allowed by the thread's current cpuset context,
 385 or none of the specified nodes contain memory.
 386 Or, the
 387 .I mode
 388 argument specified both
 389 .B MPOL_F_STATIC_NODES
 390 and
 391 .BR MPOL_F_RELATIVE_NODES .
 392 .TP
 393 .B EIO
 394 .B MPOL_MF_STRICT
 395 was specified and an existing page was already on a node
 396 that does not follow the policy;
 397 or
 398 .B MPOL_MF_MOVE
 399 or
 400 .B MPOL_MF_MOVE_ALL
 401 was specified and the kernel was unable to move all existing
 402 pages in the range.
 403 .TP
 404 .B ENOMEM
 405 Insufficient kernel memory was available.
 406 .TP
 407 .B EPERM
 408 The
 409 .I flags
 410 argument included the
 411 .B MPOL_MF_MOVE_ALL
 412 flag and the caller does not have the
 413 .B CAP_SYS_NICE
 414 privilege.
 415 .\" ---------------------------------------------------------------
 416 .SH VERSIONS
 417 The
 418 .BR mbind ()
 419 system call was added to the Linux kernel in version 2.6.7.
 420 .SH CONFORMING TO
 421 This system call is Linux-specific.
 422 .SH NOTES
 423 For information on library support, see
 424 .BR numa (7).
 425
 426 NUMA policy is not supported on a memory-mapped file range
 427 that was mapped with the
 428 .B MAP_SHARED
 429 flag.
 430
 431 The
 432 .B MPOL_DEFAULT
 433 mode can have different effects for
 434 .BR mbind ()
 435 and
 436 .BR set_mempolicy (2).
 437 When
 438 .B MPOL_DEFAULT
 439 is specified for
 440 .BR set_mempolicy (2),
 441 the thread's memory policy reverts to the system default policy
 442 or local allocation.
 443 When
 444 .B MPOL_DEFAULT
 445 is specified for a range of memory using
 446 .BR mbind (),
 447 any pages subsequently allocated for that range will use
 448 the thread's memory policy, as set by
 449 .BR set_mempolicy (2).
 450 This effectively removes the explicit policy from the
 451 specified range, "falling back" to a possibly nondefault
 452 policy.
 453 To select explicit "local allocation" for a memory range,
 454 specify a
 455 .I mode
 456 of
 457 .B MPOL_LOCAL
 458 or
 459 .B MPOL_PREFERRED
 460 with an empty set of nodes.
 461 This method will work for
 462 .BR set_mempolicy (2),
 463 as well.
 464
 465 Support for huge page policy was added with 2.6.16.
 466 For interleave policy to be effective on huge page mappings the
 467 policied memory needs to be tens of megabytes or larger.
 468
 469 .B MPOL_MF_STRICT
 470 is ignored on huge page mappings.
 471
 472 .B MPOL_MF_MOVE
 473 and
 474 .B MPOL_MF_MOVE_ALL
 475 are available only on Linux 2.6.16 and later.
 476 .SH SEE ALSO
 477 .BR get_mempolicy (2),
 478 .BR getcpu (2),
 479 .BR mmap (2),
 480 .BR set_mempolicy (2),
 481 .BR shmat (2),
 482 .BR shmget (2),
 483 .BR numa (3),
 484 .BR cpuset (7),
 485 .BR numa (7),
 486 .BR numactl (8)