home | help 
CPUSET_GETAFFINITY(2)	       System Calls Manual	   CPUSET_GETAFFINITY(2)

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 ob-
     ject 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_getaffin-
     ity() 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 usu-
     ally 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 with-
			out a valid CPU to run on because the set does not over-
			lap 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 re-
			quired 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),
     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>

FreeBSD 11.1			  May 23, 2017		   CPUSET_GETAFFINITY(2)
home | help