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_ATTR_AFFINITY_NP 3 27.Os 28.Sh NAME 29.Nm pthread_attr_getaffinity_np , 30.Nm pthread_attr_setaffinity_np 31.Nd manage CPU affinity in thread attribute objects 32.Sh LIBRARY 33.Lb libpthread 34.Sh SYNOPSIS 35.In pthread_np.h 36.Ft int 37.Fn pthread_attr_getaffinity_np "const pthread_attr_t *pattr" "size_t cpusetsize" "cpuset_t *cpusetp" 38.Ft int 39.Fn pthread_attr_setaffinity_np "pthread_attr_t *pattr" "size_t cpusetsize" "const cpuset_t *cpusetp" 40.Sh DESCRIPTION 41The 42.Fn pthread_attr_getaffinity_np 43and 44.Fn pthread_attr_setaffinity_np 45functions allow the manipulation of sets of CPUs available to the specified thread attribute object. 46.Pp 47Masks of type 48.Ft cpuset_t 49are composed using the 50.Dv CPU_SET 51macros. 52If the user-supplied mask is not large enough to fit all of the matching CPUs, 53.Fn pthread_attr_getaffinity_np 54fails with 55.Er ERANGE . 56Calls to 57.Fn pthread_attr_setaffinity_np 58tolerate masks of any size with no restrictions. 59.Fn pthread_attr_setaffinity_np 60uses the meaningful part of the mask, where the upper bound is 61the maximum CPU id present in the system. 62If bits for non-existing CPUs are set, calls to 63.Fn pthread_attr_setaffinity_np 64fail with 65.Er EINVAL . 66.Pp 67The supplied mask should have a size of 68.Fa cpusetsize 69bytes. 70This size is usually provided by calling 71.Li sizeof(cpuset_t) 72which is ultimately determined by the value of 73.Dv CPU_SETSIZE 74as defined in 75.In sys/cpuset.h . 76.Pp 77.Fn pthread_attr_getaffinity_np 78retrieves the 79mask from the thread attribute object specified by 80.Fa pattr , 81and stores it in the space provided by 82.Fa cpusetp . 83.Pp 84.Fn pthread_attr_setaffinity_np 85sets the mask for the thread attribute object specified by 86.Fa pattr 87to the value in 88.Fa cpusetp . 89.Sh RETURN VALUES 90If successful, the 91.Fn pthread_attr_getaffinity_np 92and 93.Fn pthread_attr_setaffinity_np 94functions will return zero. 95Otherwise an error number will be returned 96to indicate the error. 97.Sh ERRORS 98The 99.Fn pthread_attr_getaffinity_np 100functions will fail if: 101.Bl -tag -width Er 102.It Bq Er EINVAL 103The 104.Fa pattr 105or the attribute specified by it is 106.Dv NULL . 107.It Bq Er ERANGE 108The 109.Fa cpusetsize 110is too small. 111.El 112.Pp 113The 114.Fn pthread_attr_setaffinity_np 115function will fail if: 116.Bl -tag -width Er 117.It Bq Er EINVAL 118The 119.Fa pattr 120or the attribute specified by it is 121.Dv NULL . 122.It Bq Er EINVAL 123The 124.Fa cpusetp 125specified a CPU that was outside the set supported by the kernel. 126.It Bq Er ENOMEM 127Insufficient memory exists to store the cpuset mask. 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_getaffinity_np 3 , 135.Xr pthread_np 3 , 136.Xr pthread_setaffinity_np 3 137.Sh STANDARDS 138The 139.Nm pthread_attr_getaffinity_np 140and 141.Nm pthread_attr_setaffinity_np 142functions are non-standard 143.Fx 144extensions and may be not available on other operating systems. 145.Sh HISTORY 146The 147.Nm pthread_attr_getaffinity_np 148and 149.Nm pthread_attr_setaffinity_np 150functions first appeared in 151.Fx 7.2 . 152.Sh AUTHORS 153.An -nosplit 154The 155.Nm pthread_attr_getaffinity_np 156and 157.Nm pthread_attr_setaffinity_np 158functions were written by 159.An David Xu Aq Mt davidxu@FreeBSD.org , 160and this manpage was written by 161.An Xin LI Aq Mt delphij@FreeBSD.org . 162