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.Dd April 27, 2022 27.Dt CPUSET_GETAFFINITY 2 28.Os 29.Sh NAME 30.Nm cpuset_getaffinity , 31.Nm cpuset_setaffinity 32.Nd manage CPU affinity 33.Sh LIBRARY 34.Lb libc 35.Sh SYNOPSIS 36.In sys/param.h 37.In sys/cpuset.h 38.Ft int 39.Fn cpuset_getaffinity "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "cpuset_t *mask" 40.Ft int 41.Fn cpuset_setaffinity "cpulevel_t level" "cpuwhich_t which" "id_t id" "size_t setsize" "const cpuset_t *mask" 42.Sh DESCRIPTION 43.Fn cpuset_getaffinity 44and 45.Fn cpuset_setaffinity 46allow the manipulation of sets of CPUs available to processes, threads, 47interrupts, jails and other resources. 48These functions may manipulate sets of CPUs that contain many processes 49or per-object anonymous masks that effect only a single object. 50.Pp 51The valid values for the 52.Fa level 53and 54.Fa which 55arguments are documented in 56.Xr cpuset 2 . 57These arguments specify which object and which set of the object we are 58referring to. 59Not all possible combinations are valid. 60For example, only processes may belong to a numbered set accessed by a 61.Fa level 62argument of 63.Dv CPU_LEVEL_CPUSET . 64All resources, however, have a mask which may be manipulated with 65.Dv CPU_LEVEL_WHICH . 66.Pp 67Masks of type 68.Ft cpuset_t 69are composed using the 70.Dv CPU_SET 71macros. 72If the user-supplied mask is not large enough to fit all of the matching CPUs, 73.Fn cpuset_getaffinity 74fails with 75.Er ERANGE . 76Calls to 77.Fn cpuset_setaffinity 78tolerate masks of any size with no restrictions. 79The kernel uses the meaningful part of the mask, where the upper bound is 80the maximum CPU id present in the system. 81If bits for non-existing CPUs are set, calls to 82.Fn cpuset_setaffinity 83fail with 84.Er EINVAL . 85.Pp 86The supplied mask should have a size of 87.Fa setsize 88bytes. 89This size is usually provided by calling 90.Li sizeof(mask) 91which is ultimately determined by the value of 92.Dv CPU_SETSIZE 93as defined in 94.In sys/cpuset.h . 95.Pp 96.Fn cpuset_getaffinity 97retrieves the 98mask from the object specified by 99.Fa level , 100.Fa which 101and 102.Fa id 103and stores it in the space provided by 104.Fa mask . 105.Pp 106.Fn cpuset_setaffinity 107attempts to set the mask for the object specified by 108.Fa level , 109.Fa which 110and 111.Fa id 112to the value in 113.Fa mask . 114.Sh RETURN VALUES 115.Rv -std 116.Sh ERRORS 117The following error codes may be set in 118.Va errno : 119.Bl -tag -width Er 120.\" When changing this list, consider updating share/man/man3/pthread_create.3, 121.\" since that function can return any of these errors. 122.It Bq Er EINVAL 123The 124.Fa level 125or 126.Fa which 127argument was not a valid value. 128.It Bq Er EINVAL 129The 130.Fa mask 131argument specified when calling 132.Fn cpuset_setaffinity 133was not a valid value. 134.It Bq Er EDEADLK 135The 136.Fn cpuset_setaffinity 137call would leave a thread without a valid CPU to run on because the set 138does not overlap with the thread's anonymous mask. 139.It Bq Er EFAULT 140The mask pointer passed was invalid. 141.It Bq Er ESRCH 142The object specified by the 143.Fa id 144and 145.Fa which 146arguments could not be found. 147.It Bq Er ERANGE 148The 149.Fa cpusetsize 150was smaller than needed to fit all of the matching CPUs. 151.It Bq Er EPERM 152The calling process did not have the credentials required to complete the 153operation. 154.It Bq Er ECAPMODE 155The calling process attempted to act on a process other than itself, while 156in capability mode. 157See 158.Xr capsicum 4 . 159.El 160.Sh SEE ALSO 161.Xr cpuset 1 , 162.Xr cpuset 2 , 163.Xr cpuset_getdomain 2 , 164.Xr cpuset_getid 2 , 165.Xr cpuset_setdomain 2 , 166.Xr cpuset_setid 2 , 167.Xr pthread_affinity_np 3 , 168.Xr pthread_attr_affinity_np 3 , 169.Xr capsicum 4 , 170.Xr cpuset 9 171.Sh HISTORY 172The 173.Nm 174family of system calls first appeared in 175.Fx 7.1 . 176.Sh AUTHORS 177.An Jeffrey Roberson Aq Mt jeff@FreeBSD.org 178