1.\"- 2.\" Copyright (c) 2010 Xin LI <delphij@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd March 23, 2010 29.Dt PTHREAD_AFFINITY_NP 3 30.Os 31.Sh NAME 32.Nm pthread_getaffinity_np , 33.Nm pthread_setaffinity_np 34.Nd manage CPU affinity 35.Sh LIBRARY 36.Lb libpthread 37.Sh SYNOPSIS 38.In pthread_np.h 39.Ft int 40.Fn pthread_getaffinity_np "pthread_t td" "size_t cpusetsize" "cpuset_t *cpusetp" 41.Ft int 42.Fn pthread_setaffinity_np "pthread_t td" "size_t cpusetsize" "const cpuset_t *cpusetp" 43.Sh DESCRIPTION 44.Fn pthread_getaffinity_np 45and 46.Fn pthread_setaffinity_np 47allow the manipulation of sets of CPUs available to the specified thread. 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_getaffinity_np 58even if the result set would fit within the user supplied set. 59Calls to 60.Fn pthread_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_getaffinity_np 74retrieves the 75mask from the thread specified by 76.Fa td , 77and stores it in the space provided by 78.Fa cpusetp . 79.Pp 80.Fn pthread_setaffinity_np 81attempts to set the mask for the thread specified by 82.Fa td 83to the value in 84.Fa cpusetp . 85.Sh RETURN VALUES 86If successful, the 87.Fn pthread_getaffinity_np 88and 89.Fn pthread_setaffinity_np 90functions will return zero. 91Otherwise an error number will be returned 92to indicate the error. 93.Sh ERRORS 94The 95.Fn pthread_getaffinity_np 96and 97.Fn pthread_setaffinity_np 98functions may fail if: 99.Bl -tag -width Er 100.It Bq Er EDEADLK 101The 102.Fn pthread_setaffinity_np 103call would leave a thread without a valid CPU to run on because the set 104does not overlap with the thread's anonymous mask. 105.It Bq Er EFAULT 106The 107.Fa cpusetp 108pointer passed was invalid. 109.It Bq Er ESRCH 110The thread specified by the 111.Fa td 112argument could not be found. 113.It Bq Er ERANGE 114The 115.Fa cpusetsize 116was either preposterously large or smaller than the kernel set size. 117.It Bq Er EPERM 118The calling thread did not have the credentials required to complete the 119operation. 120.El 121.Sh SEE ALSO 122.Xr cpuset 1 , 123.Xr cpuset 2 , 124.Xr cpuset_getid 2 , 125.Xr cpuset_setid 2 , 126.Xr pthread 3 , 127.Xr pthread_attr_getaffinity_np 3 , 128.Xr pthread_attr_setaffinity_np 3 129.Sh STANDARDS 130The 131.Nm pthread_getaffinity_np 132and 133.Nm pthread_setaffinity_np 134functions are non-standard 135.Fx 136extensions and may be not available on other operating systems. 137.Sh HISTORY 138The 139.Nm pthread_getaffinity_np 140and 141.Nm pthread_setaffinity_np 142function first appeared in 143.Fx 7.2 . 144.Sh AUTHORS 145.An -nosplit 146The 147.Nm pthread_getaffinity_np 148and 149.Nm pthread_setaffinity_np 150functions were written by 151.An David Xu 152.Aq davidxu@FreeBSD.org , 153and this manpage was written by 154.An Xin LI 155.Aq delphij@FreeBSD.org . 156