NAME

       numa_getaffinity, numa_setaffinity — manage NUMA affinity

LIBRARY

       Standard C Library (libc, -lc)

SYNOPSIS

       #include <sys/param.h>
       #include <sys/numa.h>

       int
       numa_getaffinity(cpuwhich_t which, id_t id, struct vm_domain_policy_entry *policy);

       int
       numa_setaffinity(cpuwhich_t which, id_t id, const struct vm_domain_policy_entry *policy);

DESCRIPTION

       numa_getaffinity()  and numa_setaffinity() allow the manipulation of NUMA policies available to processes
       and threads.  These functions may manipulate NUMA policies that contain many processes or affect  only  a
       single object.

       Valid  values  for  the which argument are documented in cpuset(2).  These arguments specify which object
       set are used.  Only CPU_WHICH_TID and CPU_WHICH_PID can be manipulated.

       The policy entry contains a vm_domain_policy_entry with the following fields:

       struct vm_domain_policy_entry {
           vm_domain_policy_type_t policy;   /* VM policy */
           int domain;   /* VM domain, if applicable */
       }
       vm_domain_policy_type_t policy is one these:

       VM_POLICY_NONE  Reset the domain back to none.  Any parent object NUMA domain  policy  will  apply.   The
                       only valid value for domain is -1.

       VM_POLICY_ROUND_ROBIN
                       Select  round-robin  policy.   Pages will be allocated round-robin from each VM domain in
                       order.  The only valid value for domain is -1.

       VM_POLICY_FIXED_DOMAIN
                       Select fixed-domain only policy.  Pages will be allocated from  the  given  domain  which
                       must  be  set  to  a valid VM domain.  Pages will not be allocated from another domain if
                       domain is out of free pages.

       VM_POLICY_FIXED_DOMAIN_ROUND_ROBIN
                       Select fixed-domain only policy.  Pages will be allocated from domain which must  be  set
                       to a valid VM domain.  If page allocation fails, pages will be round-robin allocated from
                       another domain if domain is out of free pages.

       VM_POLICY_FIRST_TOUCH
                       Select first-touch policy.  Pages will be allocated from the NUMA domain which the thread
                       is  currently  scheduled  upon.   Pages  will not be allocated from another domain if the
                       current domain is out of free pages.  The only valid value for domain is -1.

       VM_POLICY_FIRST_TOUCH_ROUND_ROBIN
                       Select first-touch policy.  Pages will be allocated from the NUMA domain which the thread
                       is currently scheduled upon.  Pages will be allocated round-robin from another domain  if
                       the current domain is out of free pages.  The only valid value for domain is -1.

       Note that the VM might assign some pages from other domains.  For example, if an existing page allocation
       is covered by a superpage allocation.

       numa_getaffinity()  retrieves  the NUMA policy from the object specified by which and id and stores it in
       the space provided by policy.

       numa_setaffinity() attempts to set the NUMA policy for the object specified by which and id to the policy
       in policy.

RETURN VALUES

       Upon successful completion, the value 0 is returned; otherwise the value -1 is returned  and  the  global
       variable errno is set to indicate the error.

ERRORS

       errno can contain these error codes:

       [EINVAL]           The level or which argument was not a valid value.

       [EINVAL]           The  policy argument specified when calling numa_setaffinity() did not contain a valid
                          policy.

       [EFAULT]           The policy pointer passed was invalid.

       [ESRCH]            The object specified by the id and which arguments could not be found.

       [ERANGE]           The domain in the given policy was out of the range of possible VM domains available.

       [EPERM]            The calling process did not have the credentials required to complete the operation.

SEE ALSO

       cpuset(1),  numactl(1),   cpuset(2),   cpuset_getaffinity(2),   cpuset_getid(2),   cpuset_setaffinity(2),
       cpuset_setid(2), pthread_affinity_np(3), pthread_attr_affinity_np(3), numa(4)

HISTORY

       The numa_getaffinity family of system calls first appeared in FreeBSD 11.0.

AUTHORS

       Adrian Chadd <adrian@FreeBSD.org>

Debian                                             May 7, 2015                               NUMA_GETAFFINITY(2)