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

FreeBSD Manual Pages


home | help
CPUSET(2)		    BSD	System Calls Manual		     CPUSET(2)

     cpuset, cpuset_getid, cpuset_setid	-- manage CPU affinity sets

     Standard C	Library	(libc, -lc)

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

     cpuset(cpusetid_t *setid);

     cpuset_setid(cpuwhich_t which, id_t id, cpusetid_t	setid);

     cpuset_getid(cpulevel_t level, cpuwhich_t which, id_t id,
	 cpusetid_t *setid);

     The cpuset	family of system calls allow applications to control sets of
     processors	and assign processes and threads to these sets.	 Processor
     sets contain lists	of CPUs	that members may run on	and exist only as long
     as	some process is	a member of the	set.  All processes in the system have
     an	assigned set.  The default set for all processes in the	system is the
     set numbered 1.  Threads belong to	the same set as	the process which con-
     tains them, however, they may further restrict their set with the anony-
     mous per-thread mask.

     Sets are referenced by a number of	type cpuset_id_t.  Each	thread has a
     root set, an assigned set,	and an anonymous mask.	Only the root and as-
     signed sets are numbered.	The root set is	the set	of all CPUs available
     in	the system or in the system partition the thread is running in.	 The
     assigned set is a subset of the root set and is administratively assigna-
     ble on a per-process basis.  Many processes and threads may be members of
     a numbered	set.

     The anonymous set is a further thread-specific refinement on the assigned
     set.  It is intended that administrators will manipulate numbered sets
     using cpuset(1) while application developers will manipulate anonymous
     sets using	cpuset_setaffinity(2).

     To	select the correct set a value of type cpulevel_t is used.  The	fol-
     lowing values for level are supported:

	   CPU_LEVEL_ROOT      Root set
	   CPU_LEVEL_CPUSET    Assigned	set
	   CPU_LEVEL_WHICH     Set specified by	which argument

     The which argument	determines how the value of id is interpreted and is
     of	type cpuwhich_t.  The which argument may have the following values:

	   CPU_WHICH_TID       id is lwpid_t (thread id)
	   CPU_WHICH_PID       id is pid_t (process id)
	   CPU_WHICH_CPUSET    id is a cpusetid_t (cpuset id)
	   CPU_WHICH_IRQ       id is an	irq number

     An	id of '-1' may be used with a which of CPU_WHICH_TID, CPU_WHICH_PID,
     or	CPU_WHICH_CPUSET to mean the current thread, process, or current
     thread's cpuset.  All cpuset syscalls allow this usage.

     A level argument of CPU_LEVEL_WHICH combined with a which argument	other
     than CPU_WHICH_CPUSET refers to the anonymous mask	of the object.	This
     mask does not have	an id and may only be manipulated with

     cpuset() creates a	new set	containing the same CPUs as the	root set of
     the current process and stores its	id in the space	provided by setid.  On
     successful	completion the calling process joins the set and is the	only
     member.  Children inherit this set	after a	call to	fork(2).

     cpuset_setid() attempts to	set the	id of the object specified by the
     which argument.  Currently	CPU_WHICH_PID is the only acceptable value for
     which as threads do not have an id	distinct from their process and	the
     API does not permit changing the id of an existing	set.  Upon successful
     completion	all of the threads in the target process will be running on
     CPUs permitted by the set.

     cpuset_getid() retrieves a	set id from the	object indicated by which and
     stores it in the space pointed to by setid.  The retrieved	id may be that
     of	either the root	or assigned set	depending on the value of level.
     level should be CPU_LEVEL_CPUSET or CPU_LEVEL_ROOT	to get the set id from
     the process or thread specified by	the id argument.  Specifying
     CPU_LEVEL_WHICH with a process or thread is unsupported since this	refer-
     ences the unnumbered anonymous mask.

     The actual	contents of the	sets may be retrieved or manipulated using
     cpuset_getaffinity(2) and cpuset_setaffinity(2).  See those manual	pages
     for more detail.

     Upon successful completion, the value 0 is	returned; otherwise the
     value -1 is returned and the global variable errno	is set to indicate the

     The following error codes may be set in errno:

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

     [EDEADLK]		The cpuset_setid() 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 setid pointer passed to cpuset_getid() or cpuset()
			was invalid.

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

     [EPERM]		The calling process did	not have the credentials re-
			quired to complete the operation.

     [ENFILE]		There was no free cpusetid_t for allocation.

     cpuset(1),	cpuset_getaffinity(2), cpuset_setaffinity(2),
     pthread_affinity_np(3), pthread_attr_affinity_np(3)

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

     Jeffrey Roberson <>

BSD				January	8, 2010				   BSD


Want to link to this manual page? Use this URL:

home | help