NAME

       cpuset_getaffinity, cpuset_setaffinity — manage CPU affinity

LIBRARY

       Standard C Library (libc, -lc)

SYNOPSIS

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

       int
       cpuset_getaffinity(cpulevel_t level, cpuwhich_t which, id_t id, size_t setsize, cpuset_t *mask);

       int
       cpuset_setaffinity(cpulevel_t level, cpuwhich_t which, id_t id, size_t setsize, const cpuset_t *mask);

DESCRIPTION

       cpuset_getaffinity()  and  cpuset_setaffinity()  allow  the  manipulation  of  sets  of CPUs available to
       processes, threads, interrupts, jails and other resources.  These functions may manipulate sets  of  CPUs
       that contain many processes or per-object anonymous masks that effect 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 cpuset_t are composed using the CPU_SET macros.  The kernel tolerates large sets as long as
       all CPUs specified in the set exist.  Sets smaller than the kernel uses generate an  error  on  calls  to
       cpuset_getaffinity()  even  if  the  result  set  would  fit  within  the  user  supplied  set.  Calls to
       cpuset_setaffinity() 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 CPU_SETSIZE as defined in <sys/cpuset.h>.

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

       cpuset_setaffinity()  attempts  to  set  the  mask for the object specified by level, which and id to the
       value in mask.

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 argument specified when calling cpuset_setaffinity() was not a valid value.

       [EDEADLK]          The  cpuset_setaffinity()  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 cpusetsize 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_getdomain(2),
       cpuset_setdomain(2), pthread_affinity_np(3), pthread_attr_affinity_np(3), cpuset(9)

HISTORY

       The cpuset_getaffinity family of system calls first appeared in FreeBSD 7.1.

AUTHORS

       Jeffrey Roberson <jeff@FreeBSD.org>

Debian                                            May 23, 2017                             CPUSET_GETAFFINITY(2)