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