man2/mbind.2

   1 .\" Copyright 2003,2004 Andi Kleen, SuSE Labs.
   2 .\"
   3 .\" Permission is granted to make and distribute verbatim copies of this
   4 .\" manual provided the copyright notice and this permission notice are
   5 .\" preserved on all copies.
   6 .\"
   7 .\" Permission is granted to copy and distribute modified versions of this
   8 .\" manual under the conditions for verbatim copying, provided that the
   9 .\" entire resulting derived work is distributed under the terms of a
  10 .\" permission notice identical to this one.
  11 .\"
  12 .\" Since the Linux kernel and libraries are constantly changing, this
  13 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  14 .\" responsibility for errors or omissions, or for damages resulting from
  15 .\" the use of the information contained herein.
  16 .\"
  17 .\" Formatted or processed versions of this manual, if unaccompanied by
  18 .\" the source, must acknowledge the copyright and authors of this work.
  19 .\"
  20 .\" 2006-02-03, mtk, substantial wording changes and other improvements
  21 .\"
  22 .TH MBIND 2 2006-02-07 "Linux" "Linux Programmer's Manual"
  23 .SH NAME
  24 mbind \- Set memory policy for a memory range
  25 .SH SYNOPSIS
  26 .nf
  27 .B "#include <numaif.h>"
  28 .sp
  29 .BI "int mbind(void *" start ", unsigned long " len  ", int " policy ,
  30 .BI "          unsigned long *" nodemask  ", unsigned long " maxnode ,
  31 .BI "          unsigned " flags );
  32 .sp
  33 .BI "cc ... \-lnuma"
  34 .fi
  35 .SH DESCRIPTION
  36 .BR mbind ()
  37 sets the NUMA memory
  38 .I policy
  39 for the memory range starting with
  40 .I start
  41 and continuing for
  42 .IR len
  43 bytes.
  44 The memory of a NUMA machine is divided into multiple nodes.
  45 The memory policy defines in which node memory is allocated.
  46 .BR mbind ()
  47 only has an effect for new allocations; if the pages inside
  48 the range have been already touched before setting the policy,
  49 then the policy has no effect.
  50
  51 Available policies are
  52 .BR MPOL_DEFAULT ,
  53 .BR MPOL_BIND ,
  54 .BR MPOL_INTERLEAVE ,
  55 and
  56 .BR MPOL_PREFERRED .
  57 All policies except
  58 .B MPOL_DEFAULT
  59 require the caller to specify the nodes to which the policy applies in the
  60 .I nodemask
  61 parameter.
  62 .I nodemask
  63 is a bitmask of nodes containing up to
  64 .I maxnode
  65 bits.
  66 The actual number of bytes transferred via this argument
  67 is rounded up to the next multiple of
  68 .IR "sizeof(unsigned long)" ,
  69 but the kernel will only use bits up to
  70 .IR maxnode .
  71 A NULL argument means an empty set of nodes.
  72
  73 The
  74 .B MPOL_DEFAULT
  75 policy is the default and means to use the underlying process policy
  76 (which can be modified with
  77 .BR set_mempolicy (2)).
  78 Unless the process policy has been changed this means to allocate
  79 memory on the node of the CPU that triggered the allocation.
  80 .I nodemask
  81 should be specified as NULL.
  82
  83 The
  84 .B MPOL_BIND
  85 policy is a strict policy that restricts memory allocation to the
  86 nodes specified in
  87 .IR nodemask .
  88 There won't be allocations on other nodes.
  89
  90 .B MPOL_INTERLEAVE
  91 interleaves allocations to the nodes specified in
  92 .IR nodemask .
  93 This optimizes for bandwidth instead of latency.
  94 To be effective the memory area should be fairly large,
  95 at least 1MB or bigger.
  96
  97 .B MPOL_PREFERRED
  98 sets the preferred node for allocation.
  99 The kernel will try to allocate in this
 100 node first and fall back to other nodes if the
 101 preferred nodes is low on free memory.
 102 Only the first node in the
 103 .I nodemask
 104 is used.
 105 If no node is set in the mask, then the memory is allocated on
 106 the node of the CPU that triggered the allocation allocation).
 107
 108 If
 109 .B MPOL_MF_STRICT
 110 is passed in
 111 .IR flags
 112 and
 113 .I policy
 114 is not
 115 .BR MPOL_DEFAULT ,
 116 then the call will fail with the error
 117 .B EIO
 118 if the existing pages in the mapping don't follow the policy.
 119 In 2.6.16 or later the kernel will also try to move pages
 120 to the requested node with this flag.
 121
 122 If
 123 .B MPOL_MF_MOVE
 124 is passed in
 125 .IR flags ,
 126 then an attempt will be made  to
 127 move all the pages in the mapping so that they follow the policy.
 128 Pages that are shared with other processes are not moved.
 129 If
 130 .B MPOL_MF_STRICT
 131 is also specified, then the call will fail with the error
 132 .B EIO
 133 if some pages could not be moved.
 134
 135 If
 136 .B MPOL_MF_MOVE_ALL
 137 is passed in
 138 .IR flags ,
 139 then all pages in the mapping will be moved regardless of whether
 140 other processes use the pages.
 141 The calling process must be privileged
 142 .RB ( CAP_SYS_NICE )
 143 to use this flag.
 144 If
 145 .B MPOL_MF_STRICT
 146 is also specified, then the call will fail with the error
 147 .B EIO
 148 if some pages could not be moved.
 149 .SH RETURN VALUE
 150 On success,
 151 .BR mbind ()
 152 returns 0;
 153 on error, \-1 is returned and
 154 .I errno
 155 is set to indicate the error.
 156 .SH ERRORS
 157 .TP
 158 .B EFAULT
 159 There was a unmapped hole in the specified memory range
 160 or a passed pointer was not valid.
 161 .TP
 162 .B EINVAL
 163 An invalid value was specified for
 164 .I flags
 165 or
 166 .IR mode ;
 167 or
 168 .I start + len
 169 was less than
 170 .IR start ;
 171 or
 172 .I policy
 173 was
 174 .B MPOL_DEFAULT
 175 and
 176 .I nodemask
 177 pointed to a non-empty set;
 178 or
 179 .I policy
 180 was
 181 .B MPOL_BIND
 182 or
 183 .B MPOL_INTERLEAVE
 184 and
 185 .I nodemask
 186 pointed to an empty set,
 187 .TP
 188 .B ENOMEM
 189 System out of memory.
 190 .TP
 191 .B EIO
 192 .B MPOL_MF_STRICT
 193 was specified and an existing page was already on a node
 194 that does not follow the policy.
 195 .SH CONFORMING TO
 196 This system call is Linux specific.
 197 .SH NOTES
 198 NUMA policy is not supported on file mappings.
 199
 200 .B MPOL_MF_STRICT
 201 is  ignored  on  huge page mappings right now.
 202
 203 It is unfortunate that the same flag,
 204 .BR MPOL_DEFAULT ,
 205 has different effects for
 206 .BR mbind (2)
 207 and
 208 .BR set_mempolicy (2).
 209 To select "allocation on the node of the CPU that
 210 triggered the allocation" (like
 211 .BR set_mempolicy (2)
 212 .BR MPOL_DEFAULT )
 213 when calling
 214 .BR mbind (),
 215 specify a
 216 .I policy
 217 of
 218 .B MPOL_PREFERRED
 219 with an empty
 220 .IR nodemask .
 221 .SS "Versions and Library Support"
 222 The
 223 .BR mbind (),
 224 .BR get_mempolicy (2),
 225 and
 226 .BR set_mempolicy (2)
 227 system calls were added to the Linux kernel with version 2.6.7.
 228 They are only available on kernels compiled with
 229 .BR CONFIG_NUMA .
 230
 231 Support for huge page policy was added with 2.6.16.
 232 For interleave policy to be effective on huge page mappings the
 233 policied memory needs to be tens of megabytes or larger.
 234
 235 .B MPOL_MF_MOVE
 236 and
 237 .B MPOL_MF_MOVE_ALL
 238 are only available on Linux 2.6.16 and later.
 239
 240 These system calls should not be used directly.
 241 Instead, the higher level interface provided by the
 242 .BR numa (3)
 243 functions in the
 244 .I numactl
 245 package is recommended.
 246 The
 247 .I numactl
 248 package is available at
 249 .IR ftp://ftp.suse.com/pub/people/ak/numa/ .
 250
 251 You can link with
 252 .I -lnuma
 253 to get system call definitions.
 254 .I libnuma
 255 is available in the
 256 .I numactl
 257 package.
 258 This package also has the
 259 .I numaif.h
 260 header.
 261 .SH SEE ALSO
 262 .BR numa (3),
 263 .BR numactl (8),
 264 .BR set_mempolicy (2),
 265 .BR get_mempolicy (2),
 266 .BR mmap (2)