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 April 27, 2022 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. 54If the user-supplied mask is not large enough to fit all of the matching CPUs, 55.Fn cpuset_getaffinity 56fails with 57.Er ERANGE . 58Calls to 59.Fn cpuset_setaffinity 60tolerate masks of any size with no restrictions. 61The kernel uses the meaningful part of the mask, where the upper bound is 62the maximum CPU id present in the system. 63If bits for non-existing CPUs are set, calls to 64.Fn cpuset_setaffinity 65fails with 66.Er EINVAL . 67.Pp 68The supplied mask should have a size of 69.Fa cpusetsize 70bytes. 71This size is usually provided by calling 72.Li sizeof(cpuset_t) 73which is ultimately determined by the value of 74.Dv CPU_SETSIZE 75as defined in 76.In sys/cpuset.h . 77.Pp 78.Fn pthread_attr_getaffinity_np 79retrieves the 80mask from the thread attribute object specified by 81.Fa pattr , 82and stores it in the space provided by 83.Fa cpusetp . 84.Pp 85.Fn pthread_attr_setaffinity_np 86sets the mask for the thread attribute object specified by 87.Fa pattr 88to the value in 89.Fa cpusetp . 90.Sh RETURN VALUES 91If successful, the 92.Fn pthread_attr_getaffinity_np 93and 94.Fn pthread_attr_setaffinity_np 95functions will return zero. 96Otherwise an error number will be returned 97to indicate the error. 98.Sh ERRORS 99The 100.Fn pthread_attr_getaffinity_np 101functions will fail if: 102.Bl -tag -width Er 103.It Bq Er EINVAL 104The 105.Fa pattr 106or the attribute specified by it is 107.Dv NULL . 108.It Bq Er ERANGE 109The 110.Fa cpusetsize 111is too small. 112.El 113.Pp 114The 115.Fn pthread_attr_setaffinity_np 116function will fail if: 117.Bl -tag -width Er 118.It Bq Er EINVAL 119The 120.Fa pattr 121or the attribute specified by it is 122.Dv NULL . 123.It Bq Er EINVAL 124The 125.Fa cpusetp 126specified a CPU that was outside the set supported by the kernel. 127.It Bq Er ENOMEM 128Insufficient memory exists to store the cpuset mask. 129.El 130.Sh SEE ALSO 131.Xr cpuset 1 , 132.Xr cpuset 2 , 133.Xr cpuset_getid 2 , 134.Xr cpuset_setid 2 , 135.Xr pthread_getaffinity_np 3 , 136.Xr pthread_np 3 , 137.Xr pthread_setaffinity_np 3 138.Sh STANDARDS 139The 140.Nm pthread_attr_getaffinity_np 141and 142.Nm pthread_attr_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_attr_getaffinity_np 149and 150.Nm pthread_attr_setaffinity_np 151functions first appeared in 152.Fx 7.2 . 153.Sh AUTHORS 154.An -nosplit 155The 156.Nm pthread_attr_getaffinity_np 157and 158.Nm pthread_attr_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