1.\" Copyright (c) 2008 Christian Brueffer 2.\" Copyright (c) 2008 Jeffrey Roberson 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd May 3, 2017 29.Dt CPUSET 2 30.Os 31.Sh NAME 32.Nm cpuset , 33.Nm cpuset_getid , 34.Nm cpuset_setid 35.Nd manage CPU affinity sets 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In sys/param.h 40.In sys/cpuset.h 41.Ft int 42.Fn cpuset "cpusetid_t *setid" 43.Ft int 44.Fn cpuset_setid "cpuwhich_t which" "id_t id" "cpusetid_t setid" 45.Ft int 46.Fn cpuset_getid "cpulevel_t level" "cpuwhich_t which" "id_t id" "cpusetid_t *setid" 47.Sh DESCRIPTION 48The 49.Nm 50family of system calls allow applications to control sets of processors and 51memory domains and assign processes and threads to these sets. 52Processor sets contain lists of CPUs and domains that members may run on 53and exist only as long as some process is a member of the set. 54All processes in the system have an assigned set. 55The default set for all processes in the system is the set numbered 1. 56Threads belong to the same set as the process which contains them, 57however, they may further restrict their set with the anonymous 58per-thread mask to bind to a specific CPU or subset of CPUs and memory domains. 59.Pp 60Sets are referenced by a number of type 61.Ft cpuset_id_t . 62Each thread has a root set, an assigned set, and an anonymous mask. 63Only the root and assigned sets are numbered. 64The root set is the set of all CPUs and memory domains available in the system 65or in the system partition the thread is running in. 66The assigned set is a subset of the root set and is administratively 67assignable on a per-process basis. 68Many processes and threads may be members of a numbered set. 69.Pp 70The anonymous set is a further thread-specific refinement on the assigned 71set. 72It is intended that administrators will manipulate numbered sets using 73.Xr cpuset 1 74while application developers will manipulate anonymous sets using 75.Xr cpuset_setaffinity 2 and 76.Xr cpuset_setdomain 2 . 77.Pp 78To select the correct set a value of type 79.Ft cpulevel_t 80is used. 81The following values for 82.Fa level 83are supported: 84.Bl -column CPU_LEVEL_CPUSET -offset indent 85.It Dv CPU_LEVEL_ROOT Ta "Root set" 86.It Dv CPU_LEVEL_CPUSET Ta "Assigned set" 87.It Dv CPU_LEVEL_WHICH Ta "Set specified by which argument" 88.El 89.Pp 90The 91.Fa which 92argument determines how the value of 93.Fa id 94is interpreted and is of type 95.Ft cpuwhich_t . 96The 97.Fa which 98argument may have the following values: 99.Bl -column CPU_WHICH_CPUSET -offset indent 100.It Dv CPU_WHICH_TID Ta "id is lwpid_t (thread id)" 101.It Dv CPU_WHICH_PID Ta "id is pid_t (process id)" 102.It Dv CPU_WHICH_JAIL Ta "id is jid (jail id)" 103.It Dv CPU_WHICH_CPUSET Ta "id is a cpusetid_t (cpuset id)" 104.It Dv CPU_WHICH_IRQ Ta "id is an irq number" 105.It Dv CPU_WHICH_INTRHANDLER Ta "id is an irq number for an interrupt handler" 106.It Dv CPU_WHICH_ITHREAD Ta "id is an irq number for an ithread" 107.It Dv CPU_WHICH_DOMAIN Ta "id is a NUMA domain" 108.El 109.Pp 110An 111.Fa id 112of '-1' may be used with a 113.Fa which 114of 115.Dv CPU_WHICH_TID , 116.Dv CPU_WHICH_PID , 117or 118.Dv CPU_WHICH_CPUSET 119to mean the current thread, process, or current thread's 120cpuset. 121All cpuset syscalls allow this usage. 122.Pp 123A 124.Fa level 125argument of 126.Dv CPU_LEVEL_WHICH 127combined with a 128.Fa which 129argument other than 130.Dv CPU_WHICH_CPUSET 131refers to the anonymous mask of the object. 132This mask does not have an id and may only be manipulated with 133.Xr cpuset_setaffinity 2 . 134.Pp 135.Fn cpuset 136creates a new set containing the same CPUs as the root set of the current 137process and stores its id in the space provided by 138.Fa setid . 139On successful completion the calling process joins the set and is the 140only member. 141Children inherit this set after a call to 142.Xr fork 2 . 143.Pp 144.Fn cpuset_setid 145attempts to set the id of the object specified by the 146.Fa which 147argument. 148Currently 149.Dv CPU_WHICH_PID 150is the only acceptable value for which as 151threads do not have an id distinct from their process and the API does 152not permit changing the id of an existing set. 153Upon successful completion all of the threads in the target process will 154be running on CPUs permitted by the set. 155.Pp 156.Fn cpuset_getid 157retrieves a set id from the object indicated by 158.Fa which 159and stores it in the space pointed to by 160.Fa setid . 161The retrieved id may be that of either the root or assigned set 162depending on the value of 163.Fa level . 164.Fa level 165should be 166.Dv CPU_LEVEL_CPUSET 167or 168.Dv CPU_LEVEL_ROOT 169to get the set id from 170the process or thread specified by the 171.Fa id 172argument. 173Specifying 174.Dv CPU_LEVEL_WHICH 175with a process or thread is unsupported since 176this references the unnumbered anonymous mask. 177.Pp 178The actual contents of the sets may be retrieved or manipulated using 179.Xr cpuset_getaffinity 2 , 180.Xr cpuset_setaffinity 2 , 181.Xr cpuset_getdomain 2 , and 182.Xr cpuset_setdomain 2 . 183See those manual pages for more detail. 184.Sh RETURN VALUES 185.Rv -std 186.Sh ERRORS 187The following error codes may be set in 188.Va errno : 189.Bl -tag -width Er 190.It Bq Er EINVAL 191The 192.Fa which 193or 194.Fa level 195argument was not a valid value. 196.It Bq Er EDEADLK 197The 198.Fn cpuset_setid 199call would leave a thread without a valid CPU to run on because the set 200does not overlap with the thread's anonymous mask. 201.It Bq Er EFAULT 202The setid pointer passed to 203.Fn cpuset_getid 204or 205.Fn cpuset 206was invalid. 207.It Bq Er ESRCH 208The object specified by the 209.Fa id 210and 211.Fa which 212arguments could not be found. 213.It Bq Er EPERM 214The calling process did not have the credentials required to complete the 215operation. 216.It Bq Er ENFILE 217There was no free 218.Ft cpusetid_t 219for allocation. 220.El 221.Sh SEE ALSO 222.Xr cpuset 1 , 223.Xr cpuset_getaffinity 2 , 224.Xr cpuset_setaffinity 2 , 225.Xr cpuset_getdomain 2 , 226.Xr cpuset_setdomain 2 , 227.Xr pthread_affinity_np 3 , 228.Xr pthread_attr_affinity_np 3 , 229.Xr cpuset 9 230.Sh HISTORY 231The 232.Nm 233family of system calls first appeared in 234.Fx 7.1 . 235.Sh AUTHORS 236.An Jeffrey Roberson Aq Mt [email protected] 237