Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

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

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	anony-
       mous 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	speci-
       fied 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	speci-
	    fied 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 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
       cpuset(1),     cpuset(2),    cpuset_getaffinity(2),    cpuset_getid(2),
       cpuset_setaffinity(2), cpuset_setid(2), capsicum(4), cpuset(9)

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

AUTHORS
       Jeffrey Roberson	<jeff@FreeBSD.org>

FreeBSD	13.2			 June 18, 2020		   CPUSET_GETDOMAIN(2)

NAME | LIBRARY | SYNOPSIS | DESCRIPTION | ALLOCATION POLICIES | RETURN VALUES | ERRORS | SEE ALSO | HISTORY | AUTHORS

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=cpuset_setdomain&sektion=2&manpath=FreeBSD+14.0-RELEASE+and+Ports>

home | help