mbind

MBIND(3)                    Linux Programmer's Manual                   MBIND(3)



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) 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.


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


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



SuSE Labs                           Nov 2003                            MBIND(3)