1.\"- 2.\" Copyright (c) 2010 Xin LI <delphij@FreeBSD.org> 3.\" 4.\" Redistribution and use in source and binary forms, with or without 5.\" modification, are permitted provided that the following conditions 6.\" are met: 7.\" 1. Redistributions of source code must retain the above copyright 8.\" notice, this list of conditions and the following disclaimer. 9.\" 2. Redistributions in binary form must reproduce the above copyright 10.\" notice, this list of conditions and the following disclaimer in the 11.\" documentation and/or other materials provided with the distribution. 12.\" 13.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 16.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 23.\" SUCH DAMAGE. 24.\" 25.Dd January 29, 2023 26.Dt PTHREAD_AFFINITY_NP 3 27.Os 28.Sh NAME 29.Nm pthread_getaffinity_np , 30.Nm pthread_setaffinity_np 31.Nd manage CPU affinity 32.Sh LIBRARY 33.Lb libpthread 34.Sh SYNOPSIS 35.In pthread_np.h 36.Ft int 37.Fn pthread_getaffinity_np "pthread_t td" "size_t cpusetsize" "cpuset_t *cpusetp" 38.Ft int 39.Fn pthread_setaffinity_np "pthread_t td" "size_t cpusetsize" "const cpuset_t *cpusetp" 40.Sh DESCRIPTION 41.Fn pthread_getaffinity_np 42and 43.Fn pthread_setaffinity_np 44allow the manipulation of sets of CPUs available to the specified thread. 45.Pp 46Masks of type 47.Ft cpuset_t 48are composed using the 49.Dv CPU_SET 50macros. 51If the user-supplied mask is not large enough to fit all of the matching CPUs, 52.Fn pthread_getaffinity_np 53fails with 54.Er ERANGE . 55Calls to 56.Fn pthread_setaffinity_np 57tolerate masks of any size with no restrictions. 58The kernel uses the meaningful part of the mask, where the upper bound is 59the maximum CPU id present in the system. 60If bits for non-existing CPUs are set, calls to 61.Fn pthread_setaffinity_np 62fail with 63.Er EINVAL . 64.Pp 65The supplied mask should have a size of 66.Fa cpusetsize 67bytes. 68This size is usually provided by calling 69.Li sizeof(cpuset_t) 70which is ultimately determined by the value of 71.Dv CPU_SETSIZE 72as defined in 73.In sys/cpuset.h . 74.Pp 75.Fn pthread_getaffinity_np 76retrieves the 77mask from the thread specified by 78.Fa td , 79and stores it in the space provided by 80.Fa cpusetp . 81.Pp 82.Fn pthread_setaffinity_np 83attempts to set the mask for the thread specified by 84.Fa td 85to the value in 86.Fa cpusetp . 87.Sh RETURN VALUES 88If successful, the 89.Fn pthread_getaffinity_np 90and 91.Fn pthread_setaffinity_np 92functions will return zero. 93Otherwise an error number will be returned 94to indicate the error. 95.Sh ERRORS 96The 97.Fn pthread_getaffinity_np 98and 99.Fn pthread_setaffinity_np 100functions may fail if: 101.Bl -tag -width Er 102.It Bq Er EINVAL 103The 104.Fa cpusetp 105argument specified when calling 106.Fn pthread_setaffinity_np 107was not a valid value. 108.It Bq Er EDEADLK 109The 110.Fn pthread_setaffinity_np 111call would leave a thread without a valid CPU to run on because the set 112does not overlap with the thread's anonymous mask. 113.It Bq Er EFAULT 114The 115.Fa cpusetp 116pointer passed was invalid. 117.It Bq Er ESRCH 118The thread specified by the 119.Fa td 120argument could not be found. 121.It Bq Er ERANGE 122The 123.Fa cpusetsize 124was smaller than needed to fit all of the matching CPUs. 125.It Bq Er EPERM 126The calling thread did not have the credentials required to complete the 127operation. 128.El 129.Sh SEE ALSO 130.Xr cpuset 1 , 131.Xr cpuset 2 , 132.Xr cpuset_getid 2 , 133.Xr cpuset_setid 2 , 134.Xr pthread 3 , 135.Xr pthread_attr_getaffinity_np 3 , 136.Xr pthread_attr_setaffinity_np 3 , 137.Xr pthread_np 3 138.Sh STANDARDS 139The 140.Nm pthread_getaffinity_np 141and 142.Nm pthread_setaffinity_np 143functions are non-standard 144.Fx 145extensions and may be not available on other operating systems. 146.Sh HISTORY 147The 148.Nm pthread_getaffinity_np 149and 150.Nm pthread_setaffinity_np 151function first appeared in 152.Fx 7.2 . 153.Sh AUTHORS 154.An -nosplit 155The 156.Nm pthread_getaffinity_np 157and 158.Nm pthread_setaffinity_np 159functions were written by 160.An David Xu Aq Mt davidxu@FreeBSD.org , 161and this manpage was written by 162.An Xin LI Aq Mt delphij@FreeBSD.org . 163