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>