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