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 March 23, 2010 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. 53The kernel tolerates large sets as long as all CPUs specified 54in the set exist. 55Sets smaller than the kernel uses generate an error on calls to 56.Fn pthread_getaffinity_np 57even if the result set would fit within the user supplied set. 58Calls to 59.Fn pthread_setaffinity_np 60tolerate small sets with no restrictions. 61.Pp 62The supplied mask should have a size of 63.Fa cpusetsize 64bytes. 65This size is usually provided by calling 66.Li sizeof(cpuset_t) 67which is ultimately determined by the value of 68.Dv CPU_SETSIZE 69as defined in 70.In sys/cpuset.h . 71.Pp 72.Fn pthread_getaffinity_np 73retrieves the 74mask from the thread specified by 75.Fa td , 76and stores it in the space provided by 77.Fa cpusetp . 78.Pp 79.Fn pthread_setaffinity_np 80attempts to set the mask for the thread specified by 81.Fa td 82to the value in 83.Fa cpusetp . 84.Sh RETURN VALUES 85If successful, the 86.Fn pthread_getaffinity_np 87and 88.Fn pthread_setaffinity_np 89functions will return zero. 90Otherwise an error number will be returned 91to indicate the error. 92.Sh ERRORS 93The 94.Fn pthread_getaffinity_np 95and 96.Fn pthread_setaffinity_np 97functions may fail if: 98.Bl -tag -width Er 99.It Bq Er EDEADLK 100The 101.Fn pthread_setaffinity_np 102call would leave a thread without a valid CPU to run on because the set 103does not overlap with the thread's anonymous mask. 104.It Bq Er EFAULT 105The 106.Fa cpusetp 107pointer passed was invalid. 108.It Bq Er ESRCH 109The thread specified by the 110.Fa td 111argument could not be found. 112.It Bq Er ERANGE 113The 114.Fa cpusetsize 115was either preposterously large or smaller than the kernel set size. 116.It Bq Er EPERM 117The calling thread did not have the credentials required to complete the 118operation. 119.El 120.Sh SEE ALSO 121.Xr cpuset 1 , 122.Xr cpuset 2 , 123.Xr cpuset_getid 2 , 124.Xr cpuset_setid 2 , 125.Xr pthread 3 , 126.Xr pthread_attr_getaffinity_np 3 , 127.Xr pthread_attr_setaffinity_np 3 128.Sh STANDARDS 129The 130.Nm pthread_getaffinity_np 131and 132.Nm pthread_setaffinity_np 133functions are non-standard 134.Fx 135extensions and may be not available on other operating systems. 136.Sh HISTORY 137The 138.Nm pthread_getaffinity_np 139and 140.Nm pthread_setaffinity_np 141function first appeared in 142.Fx 7.2 . 143.Sh AUTHORS 144.An -nosplit 145The 146.Nm pthread_getaffinity_np 147and 148.Nm pthread_setaffinity_np 149functions were written by 150.An David Xu Aq Mt davidxu@FreeBSD.org , 151and this manpage was written by 152.An Xin LI Aq Mt delphij@FreeBSD.org . 153