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.Dd January 29, 2023
26.Dt PTHREAD_ATTR_AFFINITY_NP 3
27.Os
28.Sh NAME
29.Nm pthread_attr_getaffinity_np ,
30.Nm pthread_attr_setaffinity_np
31.Nd manage CPU affinity in thread attribute objects
32.Sh LIBRARY
33.Lb libpthread
34.Sh SYNOPSIS
35.In pthread_np.h
36.Ft int
37.Fn pthread_attr_getaffinity_np "const pthread_attr_t *pattr" "size_t cpusetsize" "cpuset_t *cpusetp"
38.Ft int
39.Fn pthread_attr_setaffinity_np "pthread_attr_t *pattr" "size_t cpusetsize" "const cpuset_t *cpusetp"
40.Sh DESCRIPTION
41The
42.Fn pthread_attr_getaffinity_np
43and
44.Fn pthread_attr_setaffinity_np
45functions allow the manipulation of sets of CPUs available to the specified thread attribute object.
46.Pp
47Masks of type
48.Ft cpuset_t
49are composed using the
50.Dv CPU_SET
51macros.
52If the user-supplied mask is not large enough to fit all of the matching CPUs,
53.Fn pthread_attr_getaffinity_np
54fails with
55.Er ERANGE .
56Calls to
57.Fn pthread_attr_setaffinity_np
58tolerate masks of any size with no restrictions.
59.Fn pthread_attr_setaffinity_np
60uses 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_attr_setaffinity_np
64fail 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_attr_getaffinity_np
78retrieves the
79mask from the thread attribute object specified by
80.Fa pattr ,
81and stores it in the space provided by
82.Fa cpusetp .
83.Pp
84.Fn pthread_attr_setaffinity_np
85sets the mask for the thread attribute object specified by
86.Fa pattr
87to the value in
88.Fa cpusetp .
89.Sh RETURN VALUES
90If successful, the
91.Fn pthread_attr_getaffinity_np
92and
93.Fn pthread_attr_setaffinity_np
94functions will return zero.
95Otherwise an error number will be returned
96to indicate the error.
97.Sh ERRORS
98The
99.Fn pthread_attr_getaffinity_np
100functions will fail if:
101.Bl -tag -width Er
102.It Bq Er EINVAL
103The
104.Fa pattr
105or the attribute specified by it is
106.Dv NULL .
107.It Bq Er ERANGE
108The
109.Fa cpusetsize
110is too small.
111.El
112.Pp
113The
114.Fn pthread_attr_setaffinity_np
115function will fail if:
116.Bl -tag -width Er
117.It Bq Er EINVAL
118The
119.Fa pattr
120or the attribute specified by it is
121.Dv NULL .
122.It Bq Er EINVAL
123The
124.Fa cpusetp
125specified a CPU that was outside the set supported by the kernel.
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_np 3 ,
136.Xr pthread_setaffinity_np 3
137.Sh STANDARDS
138The
139.Nm pthread_attr_getaffinity_np
140and
141.Nm pthread_attr_setaffinity_np
142functions are non-standard
143.Fx
144extensions and may be not available on other operating systems.
145.Sh HISTORY
146The
147.Nm pthread_attr_getaffinity_np
148and
149.Nm pthread_attr_setaffinity_np
150functions first appeared in
151.Fx 7.2 .
152.Sh AUTHORS
153.An -nosplit
154The
155.Nm pthread_attr_getaffinity_np
156and
157.Nm pthread_attr_setaffinity_np
158functions were written by
159.An David Xu Aq Mt davidxu@FreeBSD.org ,
160and this manpage was written by
161.An Xin LI Aq Mt delphij@FreeBSD.org .
162