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.\" $FreeBSD$ 26.\" 27.Dd October 12, 2021 28.Dt PTHREAD_ATTR_AFFINITY_NP 3 29.Os 30.Sh NAME 31.Nm pthread_attr_getaffinity_np , 32.Nm pthread_attr_setaffinity_np 33.Nd manage CPU affinity in thread attribute objects 34.Sh LIBRARY 35.Lb libpthread 36.Sh SYNOPSIS 37.In pthread_np.h 38.Ft int 39.Fn pthread_attr_getaffinity_np "const pthread_attr_t *pattr" "size_t cpusetsize" "cpuset_t *cpusetp" 40.Ft int 41.Fn pthread_attr_setaffinity_np "pthread_attr_t *pattr" "size_t cpusetsize" "const cpuset_t *cpusetp" 42.Sh DESCRIPTION 43The 44.Fn pthread_attr_getaffinity_np 45and 46.Fn pthread_attr_setaffinity_np 47functions allow the manipulation of sets of CPUs available to the specified thread attribute object. 48.Pp 49Masks of type 50.Ft cpuset_t 51are composed using the 52.Dv CPU_SET 53macros. 54The kernel tolerates large sets as long as all CPUs specified 55in the set exist. 56Sets smaller than the kernel uses generate an error on calls to 57.Fn pthread_attr_getaffinity_np 58even if the result set would fit within the user supplied set. 59Calls to 60.Fn pthread_attr_setaffinity_np 61tolerate small sets with no restrictions. 62.Pp 63The supplied mask should have a size of 64.Fa cpusetsize 65bytes. 66This size is usually provided by calling 67.Li sizeof(cpuset_t) 68which is ultimately determined by the value of 69.Dv CPU_SETSIZE 70as defined in 71.In sys/cpuset.h . 72.Pp 73.Fn pthread_attr_getaffinity_np 74retrieves the 75mask from the thread attribute object specified by 76.Fa pattr , 77and stores it in the space provided by 78.Fa cpusetp . 79.Pp 80.Fn pthread_attr_setaffinity_np 81sets the mask for the thread attribute object specified by 82.Fa pattr 83to the value in 84.Fa cpusetp . 85.Sh RETURN VALUES 86If successful, the 87.Fn pthread_attr_getaffinity_np 88and 89.Fn pthread_attr_setaffinity_np 90functions will return zero. 91Otherwise an error number will be returned 92to indicate the error. 93.Sh ERRORS 94The 95.Fn pthread_attr_getaffinity_np 96functions will fail if: 97.Bl -tag -width Er 98.It Bq Er EINVAL 99The 100.Fa pattr 101or the attribute specified by it is 102.Dv NULL . 103.It Bq Er ERANGE 104The 105.Fa cpusetsize 106is too small. 107.El 108.Pp 109The 110.Fn pthread_attr_setaffinity_np 111function will fail if: 112.Bl -tag -width Er 113.It Bq Er EINVAL 114The 115.Fa pattr 116or the attribute specified by it is 117.Dv NULL . 118.It Bq Er EINVAL 119The 120.Fa cpusetp 121specified a CPU that was outside the set supported by the kernel. 122.It Bq Er ERANGE 123The 124.Fa cpusetsize 125is too small. 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