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_AFFINITY_NP 3 29.Os 30.Sh NAME 31.Nm pthread_getaffinity_np , 32.Nm pthread_setaffinity_np 33.Nd manage CPU affinity 34.Sh LIBRARY 35.Lb libpthread 36.Sh SYNOPSIS 37.In pthread_np.h 38.Ft int 39.Fn pthread_getaffinity_np "pthread_t td" "size_t cpusetsize" "cpuset_t *cpusetp" 40.Ft int 41.Fn pthread_setaffinity_np "pthread_t td" "size_t cpusetsize" "const cpuset_t *cpusetp" 42.Sh DESCRIPTION 43.Fn pthread_getaffinity_np 44and 45.Fn pthread_setaffinity_np 46allow the manipulation of sets of CPUs available to the specified thread. 47.Pp 48Masks of type 49.Ft cpuset_t 50are composed using the 51.Dv CPU_SET 52macros. 53If the user-supplied mask is not large enough to fit all of the matching CPUs, 54.Fn pthread_getaffinity_np 55fails with 56.Er ERANGE . 57Calls to 58.Fn pthread_setaffinity_np 59tolerate masks of any size with no restrictions. 60The kernel uses 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_setaffinity_np 64fails 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_getaffinity_np 78retrieves the 79mask from the thread specified by 80.Fa td , 81and stores it in the space provided by 82.Fa cpusetp . 83.Pp 84.Fn pthread_setaffinity_np 85attempts to set the mask for the thread specified by 86.Fa td 87to the value in 88.Fa cpusetp . 89.Sh RETURN VALUES 90If successful, the 91.Fn pthread_getaffinity_np 92and 93.Fn pthread_setaffinity_np 94functions will return zero. 95Otherwise an error number will be returned 96to indicate the error. 97.Sh ERRORS 98The 99.Fn pthread_getaffinity_np 100and 101.Fn pthread_setaffinity_np 102functions may fail if: 103.Bl -tag -width Er 104.It Bq Er EINVAL 105The 106.Fa cpusetp 107argument specified when calling 108.Fn pthread_setaffinity_np 109was not a valid value. 110.It Bq Er EDEADLK 111The 112.Fn pthread_setaffinity_np 113call would leave a thread without a valid CPU to run on because the set 114does not overlap with the thread's anonymous mask. 115.It Bq Er EFAULT 116The 117.Fa cpusetp 118pointer passed was invalid. 119.It Bq Er ESRCH 120The thread specified by the 121.Fa td 122argument could not be found. 123.It Bq Er ERANGE 124The 125.Fa cpusetsize 126was smaller than needed to fit all of the matching CPUs. 127.It Bq Er EPERM 128The calling thread did not have the credentials required to complete the 129operation. 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 3 , 137.Xr pthread_attr_getaffinity_np 3 , 138.Xr pthread_attr_setaffinity_np 3 , 139.Xr pthread_np 3 140.Sh STANDARDS 141The 142.Nm pthread_getaffinity_np 143and 144.Nm pthread_setaffinity_np 145functions are non-standard 146.Fx 147extensions and may be not available on other operating systems. 148.Sh HISTORY 149The 150.Nm pthread_getaffinity_np 151and 152.Nm pthread_setaffinity_np 153function first appeared in 154.Fx 7.2 . 155.Sh AUTHORS 156.An -nosplit 157The 158.Nm pthread_getaffinity_np 159and 160.Nm pthread_setaffinity_np 161functions were written by 162.An David Xu Aq Mt davidxu@FreeBSD.org , 163and this manpage was written by 164.An Xin LI Aq Mt delphij@FreeBSD.org . 165