# numa

## NAME



           numa - NUMA policy library
    


## SYNOPSIS



           **#include <numa.h>**
    
           **cc ... -lnuma**
    
           **int numa_available(void);**
    
           **int numa_max_possible_node(void);**
           **int numa_num_possible_nodes();**
    
           **int numa_max_node(void);**
           **int numa_num_configured_nodes();**
           **struct bitmask *numa_get_mems_allowed(void);**
    
           **int numa_num_configured_cpus(void);**
           **struct bitmask *numa_all_nodes_ptr;**
           **struct bitmask *numa_no_nodes_ptr;**
           **struct bitmask *numa_all_cpus_ptr;**
    
           **int numa_num_task_cpus();**
           **int numa_num_task_nodes();**
    
           **int numa_parse_bitmap(char ***_line_ **, struct bitmask ***_mask_**);**
           **struct bitmask *numa_parse_nodestring(const char ***_string_**);**
           **struct bitmask *numa_parse_nodestring_all(const char ***_string_**);**
           **struct bitmask *numa_parse_cpustring(const char ***_string_**);**
           **struct bitmask *numa_parse_cpustring_all(const char ***_string_**);**
    
           **long long numa_node_size(int** _node_**, long long***_freep_**);**
           **long long numa_node_size64(int** _node_**, long long ***_freep_**);**
    
           **int numa_preferred(void);**
           **int numa_preferred_err(void);**
           **int numa_has_preferred_many(void);**
           **struct bitmask *numa_preferred_many(void);**
           **void numa_set_preferred(int** _node_**);**
           **void numa_set_preferred_many(struct bitmask ***_nodemask_**);**
           **int numa_has_home_node(void);**
           **int numa_set_mempolicy_home_node(void *start, unsigned long len,**
           **int home_node, int flags);**
           **int numa_get_interleave_node(void);**
           **struct bitmask *numa_get_interleave_mask(void);**
           **void numa_set_interleave_mask(struct bitmask ***_nodemask_**);**
           **void numa_interleave_memory(void ***_start_**, size_t** _size_**, struct**
           **bitmask ***_nodemask_**);**
           **struct bitmask *numa_get_weighted_interleave_mask(void);**
           **void numa_set_weighted_interleave_mask(struct bitmask ***_nodemask_**);**
           **void numa_weighted_interleave_memory(void ***_start_**, size_t** _size_**,**
           **struct bitmask ***_nodemask_**);**
           **void numa_bind(struct bitmask ***_nodemask_**);**
           **void numa_set_localalloc(void);**
           **void numa_set_membind(struct bitmask ***_nodemask_**);**
           **void numa_set_membind_balancing(struct bitmask ***_nodemask_**);**
           **struct bitmask *numa_get_membind(void);**
    
           **void *numa_alloc_onnode(size_t** _size_**, int** _node_**);**
           **void *numa_alloc_local(size_t** _size_**);**
           **void *numa_alloc_interleaved(size_t** _size_**);**
           **void *numa_alloc_interleaved_subset(size_t** _size_**,  struct bitmask**
           *****_nodemask_**);**
           **void *numa_alloc_weighted_interleaved(size_t** _size_**);**
           **void *numa_alloc_weighted_interleaved_subset(size_t** _size_**, struct**
           **bitmask ***_nodemask_**);**
           **void *numa_alloc(size_t** _size_**);**
           **void *numa_realloc(void ***_old_addr_**, size_t** _old_size_**, size_t**
           _new_size_**);**
           **void numa_free(void ***_start_**, size_t** _size_**);**
    
           **int numa_run_on_node(int** _node_**);**
           **int numa_run_on_node_mask(struct bitmask ***_nodemask_**);**
           **int numa_run_on_node_mask_all(struct bitmask ***_nodemask_**);**
           **struct bitmask *numa_get_run_node_mask(void);**
    
           **void numa_tonode_memory(void ***_start_**, size_t** _size_**, int** _node_**);**
           **void numa_tonodemask_memory(void ***_start_**, size_t** _size_**, struct**
           **bitmask ***_nodemask_**);**
           **void numa_setlocal_memory(void ***_start_**, size_t** _size_**);**
           **void numa_police_memory(void ***_start_**, size_t** _size_**);**
           **void numa_set_bind_policy(int** _strict_**);**
           **void numa_set_strict(int** _strict_**);**
    
           **int numa_distance(int** _node1_**, int** _node2_**);**
    
           **int numa_sched_getaffinity(pid_t** _pid_**, struct bitmask ***_mask_**);**
           **int numa_sched_setaffinity(pid_t** _pid_**, struct bitmask ***_mask_**);**
           **int numa_node_to_cpus(int** _node_**, struct bitmask ***_mask_**);**
           **void numa_node_to_cpu_update();**
           **int numa_node_of_cpu(int** _cpu_**);**
    
           **struct bitmask *numa_allocate_cpumask();**
    
           **void numa_free_cpumask();**
           **struct bitmask *numa_allocate_nodemask();**
    
           **void numa_free_nodemask();**
           **struct bitmask *numa_bitmask_alloc(unsigned int** _n_**);**
           **struct bitmask *numa_bitmask_clearall(struct bitmask ***_bmp_**);**
           **struct bitmask *numa_bitmask_clearbit(struct bitmask ***_bmp_**,**
           **unsigned int** _n_**);**
           **int numa_bitmask_equal(const struct bitmask ***_bmp1_**, const struct**
           **bitmask ***_bmp2_**);**
           **void numa_bitmask_free(struct bitmask ***_bmp_**);**
           **int numa_bitmask_isbitset(const struct bitmask ***_bmp_**, unsigned int**
           _n_**);**
           **unsigned int numa_bitmask_nbytes(struct bitmask ***_bmp_**);**
           **struct bitmask *numa_bitmask_setall(struct bitmask ***_bmp_**);**
           **struct bitmask *numa_bitmask_setbit(struct bitmask ***_bmp_**, unsigned**
           **int** _n_**);**
           **void copy_bitmask_to_nodemask(struct bitmask ***_bmp_**, nodemask_t**
           *****_nodemask_**)**
           **void copy_nodemask_to_bitmask(nodemask_t ***_nodemask_**, struct bitmask**
           *****_bmp_**)**
           **void copy_bitmask_to_bitmask(struct bitmask ***_bmpfrom_**, struct**
           **bitmask ***_bmpto_**)**
           **unsigned int numa_bitmask_weight(const struct bitmask *bmp )**
    
           **int numa_move_pages(int** _pid_**, unsigned long** _count_**, void ****_pages_**,**
           **const int ***_nodes_**, int ***_status_**, int** _flags_**);**
           **int numa_migrate_pages(int** _pid_**, struct bitmask ***_fromnodes_**, struct**
           **bitmask ***_tonodes_**);**
    
           **void numa_error(char ***_where_**);**
    
           **extern int** _numa_exit_on_error_**;**
           **extern int** _numa_exit_on_warn_**;**
           **extern int** _numa_fail_on_error_error_**;**
           **void numa_warn(int** _number_**, char ***_where_**, ...);**
    


## DESCRIPTION



           The _libnuma_ library offers a simple programming interface to the
           NUMA (Non Uniform Memory Access) policy supported by the Linux
           kernel. On a NUMA architecture some memory areas have different
           latency or bandwidth than others.
    
           Available policies are page interleaving (i.e., allocate in a
           round-robin fashion from all, or a subset, of the nodes on the
           system), preferred node allocation (i.e., preferably allocate on a
           particular node), local allocation (i.e., allocate on the node on
           which the task is currently executing), or allocation only on
           specific nodes (i.e., allocate on some subset of the available
           nodes).  It is also possible to bind tasks to specific nodes.
    
           Numa memory allocation policy may be specified as a per-task
           attribute, that is inherited by children tasks and processes, or
           as an attribute of a range of process virtual address space.  Numa
           memory policies specified for a range of virtual address space are
           shared by all tasks in the process.  Furthermore, memory policies
           specified for a range of a shared memory attached using shmat(2)
           or mmap(2) from shmfs/hugetlbfs are shared by all processes that
           attach to that region.  Memory policies for shared disk backed
           file mappings are currently ignored.
    
           The default memory allocation policy for tasks and all memory
           range is local allocation.  This assumes that no ancestor has
           installed a non-default policy.
    
           For setting a specific policy globally for all memory allocations
           in a process and its children it is easiest to start it with the
           numactl(8) utility. For more finegrained policy inside an
           application this library can be used.
    
           All numa memory allocation policy only takes effect when a page is
           actually faulted into the address space of a process by accessing
           it. The **numa_alloc_*** functions take care of this automatically.
    
           A _node_ is defined as an area where all memory has the same speed
           as seen from a particular CPU.  A node can contain multiple CPUs.
           Caches are ignored for this definition.
    
           Most functions in this library are only concerned about numa nodes
           and their memory.  The exceptions to this are:
           _numa_node_to_cpus_(), _numa_node_to_cpu_update_(),
           _numa_node_of_cpu_(), _numa_bind_(), _numa_run_on_node_(),
           _numa_run_on_node_mask_(), _numa_run_on_node_mask_all_(), and
           _numa_get_run_node_mask_().  These functions deal with the CPUs
           associated with numa nodes.  See the descriptions below for more
           information.
    
           Some of these functions accept or return a pointer to struct
           bitmask.  A struct bitmask controls a bit map of arbitrary length
           containing a bit representation of nodes.  The predefined variable
           _numa_all_nodes_ptr_ points to a bit mask that has all available
           nodes set; _numa_no_nodes_ptr_ points to the empty set.
    
           Before any other calls in this library can be used
           **numa_available**() must be called. If it returns -1, all other
           functions in this library are undefined.
    
           **numa_max_possible_node()** returns the number of the highest
           possible node in a system.  In other words, the size of a kernel
           type nodemask_t (in bits) minus 1.  This number can be gotten by
           calling **numa_num_possible_nodes()** and subtracting 1.
    
           **numa_num_possible_nodes()** returns the size of kernel's node mask
           (kernel type nodemask_t).  In other words, large enough to
           represent the maximum number of nodes that the kernel can handle.
           This will match the kernel's MAX_NUMNODES value.  This count is
           derived from /proc/self/status, field Mems_allowed.
    
           **numa_max_node**() returns the highest node number available on the
           current system.  (See the node numbers in
           /sys/devices/system/node/ ).  Also see
           **numa_num_configured_nodes().**
    
           **numa_num_configured_nodes()** returns the number of memory nodes in
           the system. This count includes any nodes that are currently
           disabled. This count is derived from the node numbers in
           /sys/devices/system/node. (Depends on the kernel being configured
           with /sys (CONFIG_SYSFS)).
    
           **numa_get_mems_allowed()** returns the mask of nodes from which the
           process is allowed to allocate memory in it's current cpuset
           context.  Any nodes that are not included in the returned bitmask
           will be ignored in any of the following libnuma memory policy
           calls.
    
           **numa_num_configured_cpus()** returns the number of cpus in the
           system.  This count includes any cpus that are currently disabled.
           This count is derived from the cpu numbers in
           /sys/devices/system/cpu. If the kernel is configured without /sys
           (CONFIG_SYSFS=n) then it falls back to using the number of online
           cpus.
    
           **numa_all_nodes_ptr** points to a bitmask that is allocated by the
           library with bits representing all nodes on which the calling task
           may allocate memory.  This set may be up to all nodes on the
           system, or up to the nodes in the current cpuset.  The bitmask is
           allocated by a call to **numa_allocate_nodemask()** using size
           **numa_max_possible_node().** The set of nodes to record is derived
           from /proc/self/status, field "Mems_allowed".  The user should not
           alter this bitmask.
    
           **numa_no_nodes_ptr** points to a bitmask that is allocated by the
           library and left all zeroes.  The bitmask is allocated by a call
           to **numa_allocate_nodemask()** using size **numa_max_possible_node().**
           The user should not alter this bitmask.
    
           **numa_all_cpus_ptr** points to a bitmask that is allocated by the
           library with bits representing all cpus on which the calling task
           may execute.  This set may be up to all cpus on the system, or up
           to the cpus in the current cpuset.  The bitmask is allocated by a
           call to **numa_allocate_cpumask()** using size
           **numa_num_possible_cpus().** The set of cpus to record is derived
           from /proc/self/status, field "Cpus_allowed".  The user should not
           alter this bitmask.
    
           **numa_num_task_cpus()** returns the number of cpus that the calling
           task is allowed to use.  This count is derived from the map
           /proc/self/status, field "Cpus_allowed". Also see the bitmask
           **numa_all_cpus_ptr.**
    
           **numa_num_task_nodes()** returns the number of nodes on which the
           calling task is allowed to allocate memory.  This count is derived
           from the map /proc/self/status, field "Mems_allowed".  Also see
           the bitmask **numa_all_nodes_ptr.**
    
           **numa_parse_bitmap()** parses _line_ , which is a character string such
           as found in /sys/devices/system/node/nodeN/cpumap into a bitmask
           structure.  The string contains the hexadecimal representation of
           a bit map.  The bitmask may be allocated with
           **numa_allocate_cpumask().** Returns  0 on success.  Returns -1 on
           failure.  This function is probably of little use to a user
           application, but it is used by _libnuma_ internally.
    
           **numa_parse_nodestring()** parses a character string list of nodes
           into a bit mask.  The bit mask is allocated by
           **numa_allocate_nodemask().** The string is a comma-separated list of
           node numbers or node ranges.  A leading ! can be used to indicate
           "not" this list (in other words, all nodes except this list), and
           a leading + can be used to indicate that the node numbers in the
           list are relative to the task's cpuset.  The string can be "all"
           to specify all ( **numa_num_task_nodes()**) nodes.  Node numbers are
           limited by the number in the system.  See **numa_max_node()** and
           **numa_num_configured_nodes().**
           Examples:  1-5,7,10   !4-5   +0-3
           If the string is of 0 length, bitmask **numa_no_nodes_ptr** is
           returned.  Returns 0 if the string is invalid.
    
           **numa_parse_nodestring_all()** is similar to **numa_parse_nodestring** ,
           but can parse all possible nodes, not only current nodeset.
    
           **numa_parse_cpustring()** parses a character string list of cpus into
           a bit mask.  The bit mask is allocated by **numa_allocate_cpumask().**
           The string is a comma-separated list of cpu numbers or cpu ranges.
           A leading ! can be used to indicate "not" this list (in other
           words, all cpus except this list), and a leading + can be used to
           indicate that the cpu numbers in the list are relative to the
           task's cpuset.  The string can be "all" to specify all (
           **numa_num_task_cpus()**) cpus.  Cpu numbers are limited by the
           number in the system.  See **numa_num_task_cpus()** and
           **numa_num_configured_cpus().**
           Examples:  1-5,7,10   !4-5   +0-3
           Returns 0 if the string is invalid.
    
           **numa_parse_cpustring_all()** is similar to **numa_parse_cpustring** ,
           but can parse all possible cpus, not only current cpuset.
    
           **numa_node_size**() returns the memory size of a node. If the
           argument _freep_ is not NULL, it used to return the amount of free
           memory on the node.  On error it returns -1.
    
           **numa_node_size64**() works the same as **numa_node_size**().  This is
           useful on 32-bit architectures with large nodes.
    
           **numa_preferred**() returns the preferred node of the current task.
           This is the node on which the kernel preferably allocates memory,
           unless some other policy overrides this.
    
           **numa_preferred_err**() Similiar to numa_preferred(), but If the
           preferred node is unavailable, return an error instead of zero.
    
           **numa_has_preferred_many**() Returns > 0 if the system supports
           multiple preferred nodes.
    
           **numa_preferred_many**() Returns the current set of preferred nodes.
           This implies the empty set when the policy isn't one used for
           preference _(PREFERRED, PREFERRED_MANY, BIND)._  The caller is
           responsible for freeing the mask with **numa_bitmask_free**().
    
           **numa_set_preferred**() sets the preferred node for the current task
           to _node_.  The system will attempt to allocate memory from the
           preferred node, but will fall back to other nodes if no memory is
           available on the the preferred node.  Passing a _node_ of -1
           argument specifies local allocation and is equivalent to calling
           **numa_set_localalloc**().
    
           **numa_set_preferred_many**() sets the preferred set of nodes for the
           current task to _nodemask_.  This is similar to **numa_set_preferred**()
           with the exception that it utilizes a different kernel interface
           to specify multiple preferred nodes.  The caller is responsible
           for freeing the mask with **numa_bitmask_free**().
    
           **numa_has_home_node()** Returns 1 if the system supports setting
           home_node for mbind and preferred_many.
    
           **numa_set_mempolicy_home_node()** set the home node for a VMA policy
           present in the task's address range.  A home node is the NUMA node
           closest to which page allocation will come from.  Users should use
           it after setting up a mbind or perfered_many memory policy for the
           specified range.
    
           **numa_get_interleave_mask**() returns the current interleave mask if
           the task's memory allocation policy is page interleaved.
           Otherwise, this function returns an empty mask.
    
           **numa_set_interleave_mask**() sets the memory interleave mask for the
           current task to _nodemask_.  All new memory allocations are page
           interleaved over all nodes in the interleave mask. Interleaving
           can be turned off again by passing an empty mask (_numa_no_nodes_).
           The page interleaving only occurs on the actual page fault that
           puts a new page into the current address space. It is also only a
           hint: the kernel will fall back to other nodes if no memory is
           available on the interleave target.
    
           **numa_get_weighted_interleave_mask**() returns the current weighted
           interleave mask if the task's memory allocation policy is weighted
           interleaving.  Otherwise, this function returns an empty mask.
    
           **numa_set_weighted_interleave_mask**() sets the memory weighted
           interleave mask for the current task to _nodemask_.  All new memory
           allocations are weighted-interleaved over all nodes in the
           weighted interleave mask, according to the weights in
           _/sys/kernel/mm/mempolicy/weighted_interleave/node*._  Interleaving
           can be turned off again by passing an empty mask (_numa_no_nodes_)_._
           The weighted interleaving only occurs on the actual page fault
           that puts a new page into the current address space. It is also
           only a hint: the kernel will fall back to other nodes if no memory
           is available on the weighted interleave target.
    
           **numa_interleave_memory**() interleaves _size_ bytes of memory page by
           page from _start_ on nodes specified in _nodemask_.  The _size_ argument
           will be rounded up to a multiple of the system page size.  If
           _nodemask_ contains nodes that are externally denied to this
           process, this call will fail.  This is a lower level function to
           interleave allocated but not yet faulted in memory. Not yet
           faulted in means the memory is allocated using mmap(2) or
           shmat(2), but has not been accessed by the current process yet.
           The memory is page interleaved to all nodes specified in _nodemask_.
           Normally **numa_alloc_interleaved**() should be used for private
           memory instead, but this function is useful to handle shared
           memory areas. To be useful the memory area should be several
           megabytes at least (or tens of megabytes of hugetlbfs mappings) If
           the **numa_set_strict**() flag is true then the operation will cause a
           numa_error if there were already pages in the mapping that do not
           follow the policy.
    
           **numa_weighted_interleave_memory**() interleaves _size_ bytes of memory
           page by page from _start_ on nodes specified in _nodemask_ according
           to the weights in
           _/sys/kernel/mm/mempolicy/weighted_interleave/node*._  The _size_
           argument will be rounded up to a multiple of the system page size.
           If _nodemask_ contains nodes that are externally denied to this
           process, this call will fail.  This is a lower level function to
           interleave allocated but not yet faulted in memory. Not yet
           faulted in means the memory is allocated using mmap(2) or
           shmat(2), but has not been accessed by the current process yet.
           The memory is page interleaved to all nodes specified in _nodemask_.
           Normally **numa_alloc_weighted_interleaved**() should be used for
           private memory instead, but this function is useful to handle
           shared memory areas. To be useful the memory area should be
           several megabytes at least (or tens of megabytes of hugetlbfs
           mappings) If the **numa_set_strict**() flag is true then the operation
           will cause a numa_error if there were already pages in the mapping
           that do not follow the policy.
    
           **numa_bind**() binds the current task and its children to the nodes
           specified in _nodemask_.  They will only run on the CPUs of the
           specified nodes and only be able to allocate memory from them.
           This function is equivalent to calling
           _numa_run_on_node_mask(nodemask)_ followed by
           _numa_set_membind(nodemask)_.  If tasks should be bound to
           individual CPUs inside nodes consider using _numa_node_to_cpus_ and
           the sched_setaffinity(2) syscall.
    
           **numa_set_localalloc**() sets the memory allocation policy for the
           calling task to local allocation.  In this mode, the preferred
           node for memory allocation is effectively the node where the task
           is executing at the time of a page allocation.
    
           **numa_set_membind**() sets the memory allocation mask.  The task will
           only allocate memory from the nodes set in _nodemask_.  Passing an
           empty _nodemask_ or a _nodemask_ that contains nodes other than those
           in the mask returned by _numa_get_mems_allowed_() will result in an
           error.
    
           **numa_set_membind_balancing**() sets the memory allocation mask and
           enable the Linux kernel NUMA balancing for the task if the feature
           is supported by the kernel.  The task will only allocate memory
           from the nodes set in _nodemask_.  Passing an empty _nodemask_ or a
           _nodemask_ that contains nodes other than those in the mask returned
           by _numa_get_mems_allowed_() will result in an error.
    
           **numa_get_membind**() returns the mask of nodes from which memory can
           currently be allocated.  If the returned mask is equal to
           _numa_all_nodes_ , then memory allocation is allowed from all nodes.
    
           **numa_alloc_onnode**() allocates memory on a specific node.  The _size_
           argument will be rounded up to a multiple of the system page size.
           if the specified _node_ is externally denied to this process, this
           call will fail.  This function is relatively slow compared to the
           malloc(3) family of functions.  The memory must be freed with
           **numa_free**().  On errors NULL is returned.
    
           **numa_alloc_local**() allocates _size_ bytes of memory on the local
           node.  The _size_ argument will be rounded up to a multiple of the
           system page size.  This function is relatively slow compared to
           the malloc(3) family of functions.  The memory must be freed with
           **numa_free**().  On errors NULL is returned.
    
           **numa_alloc_interleaved**() allocates _size_ bytes of memory page
           interleaved on all nodes. This function is relatively slow and
           should only be used for large areas consisting of multiple pages.
           The interleaving works at page level and will only show an effect
           when the area is large.  The allocated memory must be freed with
           **numa_free**().  On error, NULL is returned.
    
           **numa_alloc_weighted_interleaved**() allocates _size_ bytes of memory
           page interleaved on all nodes according to the weights in
           _/sys/kernel/mm/mempolicy/weighted_interleave/node*._  This function
           is relatively slow and should only be used for large areas
           consisting of multiple pages. The interleaving works at page level
           and will only show an effect when the area is large.  The
           allocated memory must be freed with **numa_free**().  On error, NULL
           is returned.
    
           **numa_alloc_interleaved_subset**() attempts to allocate _size_ bytes of
           memory page interleaved on nodes specified in _nodemask_.  The _size_
           argument will be rounded up to a multiple of the system page size.
           The nodes on which a process is allowed to allocate memory may be
           constrained externally.  If this is the case, this function may
           fail.  This function is relatively slow compared to the malloc(3)
           family of functions and should only be used for large areas
           consisting of multiple pages.  The interleaving works at page
           level and will only show an effect when the area is large.  The
           allocated memory must be freed with **numa_free**().  On error, NULL
           is returned.
    
           **numa_alloc_weighted_interleaved_subset**() attempts to allocate _size_
           bytes of memory page interleaved on nodes specified in _nodemask_
           according to the weights in
           _/sys/kernel/mm/mempolicy/weighted_interleave/node*._  The _size_
           argument will be rounded up to a multiple of the system page size.
           The nodes on which a process is allowed to allocate memory may be
           constrained externally.  If this is the case, this function may
           fail.  This function is relatively slow compared to the malloc(3)
           family of functions and should only be used for large areas
           consisting of multiple pages.  The interleaving works at page
           level and will only show an effect when the area is large.  The
           allocated memory must be freed with **numa_free**().  On error, NULL
           is returned.
    
           **numa_alloc**() allocates _size_ bytes of memory with the current NUMA
           policy.  The _size_ argument will be rounded up to a multiple of the
           system page size.  This function is relatively slow compared to
           the malloc(3) family of functions.  The memory must be freed with
           **numa_free**().  On errors NULL is returned.
    
           **numa_realloc**() changes the size of the memory area pointed to by
           _old_addr_ from _old_size_ to _new_size._  The memory area pointed to by
           _old_addr_ must have been allocated with one of the **numa_alloc***
           functions.  The _new_size_ will be rounded up to a multiple of the
           system page size. The contents of the memory area will be
           unchanged to the minimum of the old and new sizes; newly allocated
           memory will be uninitialized. The memory policy (and node
           bindings) associated with the original memory area will be
           preserved in the resized area. For example, if the initial area
           was allocated with a call to **numa_alloc_onnode(),** then the new
           pages (if the area is enlarged) will be allocated on the same
           node.  However, if no memory policy was set for the original area,
           then **numa_realloc**() cannot guarantee that the new pages will be
           allocated on the same node. On success, the address of the resized
           area is returned (which might be different from that of the
           initial area), otherwise NULL is returned and _errno_ is set to
           indicate the error. The pointer returned by **numa_realloc**() is
           suitable for passing to **numa_free**().
    
           **numa_free**() frees _size_ bytes of memory starting at _start_ ,
           allocated by the **numa_alloc_*** functions above.  The _size_ argument
           will be rounded up to a multiple of the system page size.
    
           **numa_run_on_node**() runs the current task and its children on a
           specific node. They will not migrate to CPUs of other nodes until
           the node affinity is reset with a new call to
           **numa_run_on_node_mask**().  Passing -1 permits the kernel to
           schedule on all nodes again.  On success, 0 is returned; on error
           -1 is returned, and _errno_ is set to indicate the error.
    
           **numa_run_on_node_mask**() runs the current task and its children
           only on nodes specified in _nodemask_.  They will not migrate to
           CPUs of other nodes until the node affinity is reset with a new
           call to **numa_run_on_node_mask**() or **numa_run_on_node**().  Passing
           _numa_all_nodes_ permits the kernel to schedule on all nodes again.
           On success, 0 is returned; on error -1 is returned, and _errno_ is
           set to indicate the error.
    
           **numa_run_on_node_mask_all**() runs the current task and its children
           only on nodes specified in _nodemask_ like _numa_run_on_node_mask_ but
           without any cpuset awareness.
    
           **numa_get_run_node_mask**() returns a mask of CPUs on which the
           current task is allowed to run.
    
           **numa_tonode_memory**() put memory on a specific node. The
           constraints described for **numa_interleave_memory**() apply here too.
    
           **numa_tonodemask_memory**() put memory on a specific set of nodes.
           The constraints described for **numa_interleave_memory**() apply here
           too.
    
           **numa_setlocal_memory**() locates memory on the current node. The
           constraints described for **numa_interleave_memory**() apply here too.
    
           **numa_police_memory**() locates memory with the current NUMA policy.
           The constraints described for **numa_interleave_memory**() apply here
           too. The function will read-modify-write parts of the memory, and
           it's the callers responsibility to avoid data races with parallel
           threads.
    
           **numa_distance**() reports the distance in the machine topology
           between two nodes.  The factors are a multiple of 10. It returns 0
           when the distance cannot be determined. A node has distance 10 to
           itself.  Reporting the distance requires a Linux kernel version of
           _2.6.10_ or newer.
    
           **numa_set_bind_policy**() specifies whether calls that bind memory to
           a specific node should use the preferred policy or a strict
           policy.  The preferred policy allows the kernel to allocate memory
           on other nodes when there isn't enough free on the target node.
           strict will fail the allocation in that case.  Setting the
           argument to specifies strict, 0 preferred.  Note that specifying
           more than one node non strict may only use the first node in some
           kernel versions.
    
           **numa_set_strict**() sets a flag that says whether the functions
           allocating on specific nodes should use use a strict policy.
           Strict means the allocation will fail if the memory cannot be
           allocated on the target node.  Default operation is to fall back
           to other nodes.  This doesn't apply to interleave and default.
    
           **numa_get_interleave_node()** is used by _libnuma_ internally. It is
           probably not useful for user applications.  It uses the
           MPOL_F_NODE flag of the get_mempolicy system call, which is not
           intended for application use (its operation may change or be
           removed altogether in future kernel versions). See
           get_mempolicy(2).
    
           **numa_pagesize()** returns the number of bytes in page. This function
           is simply a fast alternative to repeated calls to the getpagesize
           system call.  See getpagesize(2).
    
           **numa_sched_getaffinity()** retrieves a bitmask of the cpus on which
           a task may run.  The task is specified by _pid._  Returns the return
           value of the sched_getaffinity system call.  See
           sched_getaffinity(2).  The bitmask must be at least the size of
           the kernel's cpu mask structure. Use **numa_allocate_cpumask()** to
           allocate it.  Test the bits in the mask by calling
           **numa_bitmask_isbitset().**
    
           **numa_sched_setaffinity()** sets a task's allowed cpu's to those
           cpu's specified in _mask._  The task is specified by _pid._  Returns
           the return value of the sched_setaffinity system call.  See
           sched_setaffinity(2).  You may allocate the bitmask with
           **numa_allocate_cpumask().** Or the bitmask may be smaller than the
           kernel's cpu mask structure. For example, call
           **numa_bitmask_alloc()** using a maximum number of cpus from
           **numa_num_configured_cpus().** Set the bits in the mask by calling
           **numa_bitmask_setbit().**
    
           **numa_node_to_cpus**() converts a node number to a bitmask of CPUs.
           The user must pass a bitmask structure with a mask buffer long
           enough to represent all possible cpu's.  Use
           numa_allocate_cpumask() to create it.  If the bitmask is not long
           enough _errno_ will be set to _ERANGE_ and -1 returned. On success 0
           is returned.
    
           **numa_node_to_cpu_update**() Mark cpus bitmask of all nodes stale,
           then get the latest bitmask by calling **numa_node_to_cpus**() This
           allows to update the libnuma state after a CPU hotplug event. The
           application is in charge of detecting CPU hotplug events.
    
           **numa_node_of_cpu**() returns the node that a cpu belongs to. If the
           user supplies an invalid cpu _errno_ will be set to _EINVAL_ and -1
           will be returned.
    
           **numa_allocate_cpumask**() returns a bitmask of a size equal to the
           kernel's cpu mask (kernel type cpumask_t).  In other words, large
           enough to represent NR_CPUS cpus.  This number of cpus can be
           gotten by calling **numa_num_possible_cpus().** The bitmask is zero-
           filled.
    
           **numa_free_cpumask** frees a cpumask previously allocate by
           _numa_allocate_cpumask._
    
           **numa_allocate_nodemask()** returns a bitmask of a size equal to the
           kernel's node mask (kernel type nodemask_t).  In other words,
           large enough to represent MAX_NUMNODES nodes.  This number of
           nodes can be gotten by calling **numa_num_possible_nodes().** The
           bitmask is zero-filled.
    
           **numa_free_nodemask()** frees a nodemask previous allocated by
           _numa_allocate_nodemask()._
    
           **numa_bitmask_alloc()** allocates a bitmask structure and its
           associated bit mask.  The memory allocated for the bit mask
           contains enough words (type unsigned long) to contain _n_ bits.  The
           bit mask is zero-filled.  The bitmask structure points to the bit
           mask and contains the _n_ value.
    
           **numa_bitmask_clearall()** sets all bits in the bit mask to 0.  The
           bitmask structure points to the bit mask and contains its size (
           _bmp_ ->size).  The value of _bmp_ is always returned.  Note that
           **numa_bitmask_alloc()** creates a zero-filled bit mask.
    
           **numa_bitmask_clearbit()** sets a specified bit in a bit mask to 0.
           Nothing is done if the _n_ value is greater than the size of the
           bitmask (and no error is returned). The value of _bmp_ is always
           returned.
    
           **numa_bitmask_equal()** returns 1 if two bitmasks are equal.  It
           returns 0 if they are not equal.  If the bitmask structures
           control bit masks of different sizes, the "missing" trailing bits
           of the smaller bit mask are considered to be 0.
    
           **numa_bitmask_free()** deallocates the memory of both the bitmask
           structure pointed to by _bmp_ and the bit mask.  It is an error to
           attempt to free this bitmask twice.
    
           **numa_bitmask_isbitset()** returns the value of a specified bit in a
           bit mask.  If the _n_ value is greater than the size of the bit map,
           0 is returned.
    
           **numa_bitmask_nbytes()** returns the size (in bytes) of the bit mask
           controlled by _bmp._  The bit masks are always full words (type
           unsigned long), and the returned size is the actual size of all
           those words.
    
           **numa_bitmask_setall()** sets all bits in the bit mask to 1.  The
           bitmask structure points to the bit mask and contains its size (
           _bmp_ ->size).  The value of _bmp_ is always returned.
    
           **numa_bitmask_setbit()** sets a specified bit in a bit mask to 1.
           Nothing is done if _n_ is greater than the size of the bitmask (and
           no error is returned). The value of _bmp_ is always returned.
    
           **copy_bitmask_to_nodemask()** copies the body (the bit map itself) of
           the bitmask structure pointed to by _bmp_ to the nodemask_t
           structure pointed to by the _nodemask_ pointer. If the two areas
           differ in size, the copy is truncated to the size of the receiving
           field or zero-filled.
    
           **copy_nodemask_to_bitmask()** copies the nodemask_t structure pointed
           to by the _nodemask_ pointer to the body (the bit map itself) of the
           bitmask structure pointed to by the _bmp_ pointer. If the two areas
           differ in size, the copy is truncated to the size of the receiving
           field or zero-filled.
    
           **copy_bitmask_to_bitmask()** copies the body (the bit map itself) of
           the bitmask structure pointed to by the _bmpfrom_ pointer to the
           body of the bitmask structure pointed to by the _bmpto_ pointer. If
           the two areas differ in size, the copy is truncated to the size of
           the receiving field or zero-filled.
    
           **numa_bitmask_weight()** returns a count of the bits that are set in
           the body of the bitmask pointed to by the _bmp_ argument.
    
           **numa_move_pages()** moves a list of pages in the address space of
           the currently executing or current process.  It simply uses the
           move_pages system call.
           _pid_ - ID of task.  If not valid, use the current task.
           _count_ - Number of pages.
           _pages_ - List of pages to move.
           _nodes_ - List of nodes to which pages can be moved.
           _status_ - Field to which status is to be returned.
           _flags_ - MPOL_MF_MOVE or MPOL_MF_MOVE_ALL
           See move_pages(2).
    
           **numa_migrate_pages()** simply uses the migrate_pages system call to
           cause the pages of the calling task, or a specified task, to be
           migated from one set of nodes to another.  See migrate_pages(2).
           The bit masks representing the nodes should be allocated with
           **numa_allocate_nodemask()** , or with **numa_bitmask_alloc()** using an _n_
           value returned from **numa_num_possible_nodes().** A task's current
           node set can be gotten by calling **numa_get_membind().** Bits in the
           _tonodes_ mask can be set by calls to **numa_bitmask_setbit().**
    
           **numa_error**() is a _libnuma_ internal function that can be overridden
           by the user program.  This function is called with a _char *_
           argument when a _libnuma_ function fails.  Overriding the library
           internal definition makes it possible to specify a different error
           handling strategy when a _libnuma_ function fails. It does not
           affect **numa_available**().  The **numa_error**() function defined in
           _libnuma_ prints an error on _stderr_ and terminates the program if
           _numa_exit_on_error_ is set to a non-zero value.  The default value
           of _numa_exit_on_error_ is zero.  When the _numa_fail_alloc_on_error_
           variable is set to 1 make _numa_alloc_ functions fail with a NULL
           return if the policy cannot be set. Default 0.
    
           **numa_warn**() is a _libnuma_ internal function that can be also
           overridden by the user program.  It is called to warn the user
           when a _libnuma_ function encounters a non-fatal error.  The default
           implementation prints a warning to _stderr_.  The first argument is
           a unique number identifying each warning. After that there is a
           printf(3)-style format string and a variable number of arguments.
           _numa_warn_ exits the program when _numa_exit_on_warn_ is set to a
           non-zero value.  The default value of _numa_exit_on_warn_ is zero.
    


## Compatibility with libnuma version 1



           Binaries that were compiled for libnuma version 1 need not be re-
           compiled to run with libnuma version 2.
           Source codes written for libnuma version 1 may be re-compiled
           without change with version 2 installed. To do so, in the code's
           Makefile add this option to CFLAGS:  -DNUMA_VERSION1_COMPATIBILITY
    


## THREAD SAFETY



           _numa_set_bind_policy_ and _numa_exit_on_error_ are process global.
           The other calls are thread safe.
    


* * *