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 January 8, 2015 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 51assign processes and threads to these sets. 52Processor sets contain lists of CPUs that members may run on and exist only 53as 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. 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 available in the system or in the 65system 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 . 76.Pp 77To select the correct set a value of type 78.Ft cpulevel_t 79is used. 80The following values for 81.Fa level 82are supported: 83.Bl -column CPU_LEVEL_CPUSET -offset indent 84.It Dv CPU_LEVEL_ROOT Ta "Root set" 85.It Dv CPU_LEVEL_CPUSET Ta "Assigned set" 86.It Dv CPU_LEVEL_WHICH Ta "Set specified by which argument" 87.El 88.Pp 89The 90.Fa which 91argument determines how the value of 92.Fa id 93is interpreted and is of type 94.Ft cpuwhich_t . 95The 96.Fa which 97argument may have the following values: 98.Bl -column CPU_WHICH_CPUSET -offset indent 99.It Dv CPU_WHICH_TID Ta "id is lwpid_t (thread id)" 100.It Dv CPU_WHICH_PID Ta "id is pid_t (process id)" 101.It Dv CPU_WHICH_JAIL Ta "id is jid (jail id)" 102.It Dv CPU_WHICH_CPUSET Ta "id is a cpusetid_t (cpuset id)" 103.It Dv CPU_WHICH_IRQ Ta "id is an irq number" 104.It Dv CPU_WHICH_DOMAIN Ta "id is a NUMA domain" 105.El 106.Pp 107An 108.Fa id 109of '-1' may be used with a 110.Fa which 111of 112.Dv CPU_WHICH_TID , 113.Dv CPU_WHICH_PID , 114or 115.Dv CPU_WHICH_CPUSET 116to mean the current thread, process, or current thread's 117cpuset. 118All cpuset syscalls allow this usage. 119.Pp 120A 121.Fa level 122argument of 123.Dv CPU_LEVEL_WHICH 124combined with a 125.Fa which 126argument other than 127.Dv CPU_WHICH_CPUSET 128refers to the anonymous mask of the object. 129This mask does not have an id and may only be manipulated with 130.Xr cpuset_setaffinity 2 . 131.Pp 132.Fn cpuset 133creates a new set containing the same CPUs as the root set of the current 134process and stores its id in the space provided by 135.Fa setid . 136On successful completion the calling process joins the set and is the 137only member. 138Children inherit this set after a call to 139.Xr fork 2 . 140.Pp 141.Fn cpuset_setid 142attempts to set the id of the object specified by the 143.Fa which 144argument. 145Currently 146.Dv CPU_WHICH_PID 147is the only acceptable value for which as 148threads do not have an id distinct from their process and the API does 149not permit changing the id of an existing set. 150Upon successful completion all of the threads in the target process will 151be running on CPUs permitted by the set. 152.Pp 153.Fn cpuset_getid 154retrieves a set id from the object indicated by 155.Fa which 156and stores it in the space pointed to by 157.Fa setid . 158The retrieved id may be that of either the root or assigned set 159depending on the value of 160.Fa level . 161.Fa level 162should be 163.Dv CPU_LEVEL_CPUSET 164or 165.Dv CPU_LEVEL_ROOT 166to get the set id from 167the process or thread specified by the 168.Fa id 169argument. 170Specifying 171.Dv CPU_LEVEL_WHICH 172with a process or thread is unsupported since 173this references the unnumbered anonymous mask. 174.Pp 175The actual contents of the sets may be retrieved or manipulated using 176.Xr cpuset_getaffinity 2 177and 178.Xr cpuset_setaffinity 2 . 179See those manual pages for more detail. 180.Sh RETURN VALUES 181.Rv -std 182.Sh ERRORS 183The following error codes may be set in 184.Va errno : 185.Bl -tag -width Er 186.It Bq Er EINVAL 187The 188.Fa which 189or 190.Fa level 191argument was not a valid value. 192.It Bq Er EDEADLK 193The 194.Fn cpuset_setid 195call would leave a thread without a valid CPU to run on because the set 196does not overlap with the thread's anonymous mask. 197.It Bq Er EFAULT 198The setid pointer passed to 199.Fn cpuset_getid 200or 201.Fn cpuset 202was invalid. 203.It Bq Er ESRCH 204The object specified by the 205.Fa id 206and 207.Fa which 208arguments could not be found. 209.It Bq Er EPERM 210The calling process did not have the credentials required to complete the 211operation. 212.It Bq Er ENFILE 213There was no free 214.Ft cpusetid_t 215for allocation. 216.El 217.Sh SEE ALSO 218.Xr cpuset 1 , 219.Xr cpuset_getaffinity 2 , 220.Xr cpuset_setaffinity 2 , 221.Xr pthread_affinity_np 3 , 222.Xr pthread_attr_affinity_np 3 223.Sh HISTORY 224The 225.Nm 226family of system calls first appeared in 227.Fx 7.1 . 228.Sh AUTHORS 229.An Jeffrey Roberson Aq Mt [email protected] 230