NAME

     cpuset_getdomain, cpuset_setdomain — manage memory domain policy

LIBRARY

     Standard C Library (libc, -lc)

SYNOPSIS

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

     int
     cpuset_getdomain(cpulevel_t level, cpuwhich_t which, id_t id, size_t setsize,
         domainset_t *mask, int *policy);

     int
     cpuset_setdomain(cpulevel_t level, cpuwhich_t which, id_t id, size_t setsize,
         const domainset_t *mask, int policy);

DESCRIPTION

     cpuset_getdomain() and cpuset_setdomain() allow the manipulation of sets of memory domains
     and allocation policy available to processes, threads, jails and other resources.  These
     functions may manipulate sets of memory domains that contain many processes or per-object
     anonymous masks that affect only a single object.

     The valid values for the level and which arguments are documented in cpuset(2).  These
     arguments specify which object and which set of the object we are referring to.  Not all
     possible combinations are valid.  For example, only processes may belong to a numbered set
     accessed by a level argument of CPU_LEVEL_CPUSET.  All resources, however, have a mask which
     may be manipulated with CPU_LEVEL_WHICH.

     Masks of type domainset_t are composed using the DOMAINSET macros.  The kernel tolerates
     large sets as long as all domains specified in the set exist.  Sets smaller than the kernel
     uses generate an error on calls to cpuset_getdomain() even if the result set would fit
     within the user supplied set.  Calls to cpuset_setdomain() tolerate small sets with no
     restrictions.

     The supplied mask should have a size of setsize bytes.  This size is usually provided by
     calling sizeof(mask) which is ultimately determined by the value of DOMAINSET_SETSIZE as
     defined in <sys/domainset.h>.

     cpuset_getdomain() retrieves the mask and policy from the object specified by level, which
     and id and stores it in the space provided by mask and policy.

     cpuset_setdomain() attempts to set the mask and policy for the object specified by level,
     which and id to the values in mask and policy.

ALLOCATION POLICIES

     Valid policy values are as follows:

     DOMAINSET_POLICY_ROUNDROBIN
          Memory is allocated on a round-robin basis by cycling through each domain in mask.

     DOMAINSET_POLICY_FIRSTTOUCH
          Memory is allocated on the domain local to the CPU the requesting thread is running on.
          Failure to allocate from this domain will fallback to round-robin.

     DOMAINSET_POLICY_PREFER
          Memory is allocated preferentially from the single domain specified in the mask.  If
          memory is unavailable the domains listed in the parent cpuset will be visited in a
          round-robin order.

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

     The following error codes may be set in errno:

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

     [EINVAL]           The mask or policy argument specified when calling cpuset_setdomain() was
                        not a valid value.

     [EDEADLK]          The cpuset_setdomain() call would leave a thread without a valid CPU to
                        run on because the set does not overlap with the thread's anonymous mask.

     [EFAULT]           The mask pointer passed was invalid.

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

     [ERANGE]           The domainsetsize was either preposterously large or smaller than the
                        kernel set size.

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

     [ECAPMODE]         The calling process attempted to act on a process other than itself,
                        while in capability mode.  See capsicum(4).

SEE ALSO

     capsicum(4), cpuset(1), cpuset(2), cpuset_getid(2), cpuset_setid(2), cpuset_getaffinity(2),
     cpuset_setaffinity(2), cpuset(9)

HISTORY

     The cpuset_getdomain family of system calls first appeared in FreeBSD 12.0.

AUTHORS

     Jeffrey Roberson <jeff@FreeBSD.org>