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 June 2, 2016
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.
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_attr_getaffinity_np
58even if the result set would fit within the user supplied set.
59Calls to
60.Fn pthread_attr_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_attr_getaffinity_np
74retrieves the
75mask from the thread attribute object specified by
76.Fa pattr ,
77and stores it in the space provided by
78.Fa cpusetp .
79.Pp
80.Fn pthread_attr_setaffinity_np
81sets the mask for the thread attribute object specified by
82.Fa pattr
83to the value in
84.Fa cpusetp .
85.Sh RETURN VALUES
86If successful, the
87.Fn pthread_attr_getaffinity_np
88and
89.Fn pthread_attr_setaffinity_np
90functions will return zero.
91Otherwise an error number will be returned
92to indicate the error.
93.Sh ERRORS
94The
95.Fn pthread_attr_getaffinity_np
96functions will fail if:
97.Bl -tag -width Er
98.It Bq Er EINVAL
99The
100.Fa pattr
101or the attribute specified by it is
102.Dv NULL .
103.It Bq Er ERANGE
104The
105.Fa cpusetsize
106is too small.
107.El
108.Pp
109The
110.Fn pthread_attr_setaffinity_np
111function will fail if:
112.Bl -tag -width Er
113.It Bq Er EINVAL
114The
115.Fa pattr
116or the attribute specified by it is
117.Dv NULL .
118.It Bq Er EINVAL
119The
120.Fa cpusetp
121specified a CPU that was outside the set supported by the kernel.
122.It Bq Er ERANGE
123The
124.Fa cpusetsize
125is too small.
126.It Bq Er ENOMEM
127Insufficient memory exists to store the cpuset mask.
128.El
129.Sh SEE ALSO
130.Xr cpuset 1 ,
131.Xr cpuset 2 ,
132.Xr cpuset_getid 2 ,
133.Xr cpuset_setid 2 ,
134.Xr pthread_getaffinity_np 3 ,
135.Xr pthread_setaffinity_np 3
136.Sh STANDARDS
137The
138.Nm pthread_attr_getaffinity_np
139and
140.Nm pthread_attr_setaffinity_np
141functions are non-standard
142.Fx
143extensions and may be not available on other operating systems.
144.Sh HISTORY
145The
146.Nm pthread_attr_getaffinity_np
147and
148.Nm pthread_attr_setaffinity_np
149functions first appeared in
150.Fx 7.2 .
151.Sh AUTHORS
152.An -nosplit
153The
154.Nm pthread_attr_getaffinity_np
155and
156.Nm pthread_attr_setaffinity_np
157functions were written by
158.An David Xu Aq Mt davidxu@FreeBSD.org ,
159and this manpage was written by
160.An Xin LI Aq Mt delphij@FreeBSD.org .
161