mbind - Set memory policy for an memory range

#include <numaif.h>

int mbind(void *start, unsigned long len, int policy, unsigned long *nodemask, unsigned long maxnode, unsigned flags)

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.

mbind returns -1 when an error occurred, otherwise 0.

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.

For a higher level interface it is recommended to use the functions in numa(3) from the numactl package.

Until glibc supports these system calls you can link with -lnuma to get system call definitions. libnuma is available in the numactl package. It also has the numaif.h header.

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.

The mbind syscall was added to the Linux kernel with version 2.6.7rc1. It is only available on kernels compiled with CONFIG_NUMA.

numa(3), numactl(8), set_mempolicy(2), get_mempolicy(2), mmap(2)