mbind(2) -- Linux man page
NAME
mbind - Set memory policy for an memory range
SYNOPSIS
#include <numaif.h>
int mbind(void *start, unsigned long len, int policy, unsigned long *nodemask,
unsigned long maxnode, unsigned flags)
DESCRIPTION
mbind
sets the NUMA memory
policy
for the memory range starting with
start
and length
len.
The memory of a NUMA machine is divided into multiple nodes.
The memory policy defines in which node memory is allocated.
mbind
has only an effect for new allocations; when the pages inside
the range have been already touched before setting the policy
the policy has no effect.
Available policies are
MPOL_DEFAULT,
MPOL_BIND,
MPOL_INTERLEAVE,
MPOL_PREFERRED.
All policies except
MPOL_DEFAULT
require to specify the nodes they apply to in the
nodemask
parameter.
nodemask
is a bit field of nodes that contains upto
maxnode
bits.
The node mask bit field size is rounded to the next multiple of
sizeof(unsigned long),
but the kernel will only use bits upto
maxnode.
When
MPOL_MF_STRICT
is passed in the
flags
parameter
EIO
will be returned when the existing pages in the mapping don't follow
the policy.
The
MPOL_DEFAULT
policy is the default and means to use the underlying process policy
(which can be modified with
set_mempolicy(2)
). Unless the process policy has been changed this means to allocate
memory on the node of the CPU that triggered the allocation.
nodemask
should be passed as NULL.
The
MPOL_BIND
policy is a strict policy that restricts memory allocation to the
nodes specified in
nodemask.
There won't be allocations on other nodes.
MPOL_INTERLEAVE
interleaves allocations to the nodes specified in
nodemask.
This optimizes for bandwidth instead of latency.
To be effective the memory area should be fairly large, at least 1MB or bigger.
MPOL_PREFERRED
sets the preferred node for allocation. The kernel will try to allocate in this
node first and fall back to other nodes when the preferred nodes is low on free
memory. Only the first node in the
nodemask
is used. When no node is set in the mask the current node is used for allocation.
RETURN VALUE
mbind
returns -1 when an error occurred, otherwise 0.
ERRORS
- EFAULT
-
There was a unmapped hole in the specified memory range
or an passed pointer was not valid.
- EINVAL
-
An illegal parameter was passed.
- ENOMEM
-
System out of memory
- EIO
-
MPOL_F_STRICT
was specified and an existing page was already on an wrong node.
NOTES
For a higher level interface it is recommended to use the functions in
numa(3).
Until glibc supports these system calls you can link with
-lnuma
to get system call definitions.
MPOL_MF_STRICT
is ignored on huge page mappings right now. For preferred and interleave
mappings it will only accept the first choice node.
For
MPOL_INTERLEAVE
mode the interleaving is changed at fault time. The final layout of
the pages depends on the order they were faulted in first.
SEE ALSO
numa(3),
numactl(8),
set_mempolicy(2),
get_mempolicy(2),
mmap(2)
| 
