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