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