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 April 27, 2022
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.
54If the user-supplied mask is not large enough to fit all of the matching CPUs,
55.Fn cpuset_getaffinity
56fails with
57.Er ERANGE .
58Calls to
59.Fn cpuset_setaffinity
60tolerate masks of any size with no restrictions.
61The kernel uses the meaningful part of the mask, where the upper bound is
62the maximum CPU id present in the system.
63If bits for non-existing CPUs are set, calls to
64.Fn cpuset_setaffinity
65fails with
66.Er EINVAL .
67.Pp
68The supplied mask should have a size of
69.Fa cpusetsize
70bytes.
71This size is usually provided by calling
72.Li sizeof(cpuset_t)
73which is ultimately determined by the value of
74.Dv CPU_SETSIZE
75as defined in
76.In sys/cpuset.h .
77.Pp
78.Fn pthread_attr_getaffinity_np
79retrieves the
80mask from the thread attribute object specified by
81.Fa pattr ,
82and stores it in the space provided by
83.Fa cpusetp .
84.Pp
85.Fn pthread_attr_setaffinity_np
86sets the mask for the thread attribute object specified by
87.Fa pattr
88to the value in
89.Fa cpusetp .
90.Sh RETURN VALUES
91If successful, the
92.Fn pthread_attr_getaffinity_np
93and
94.Fn pthread_attr_setaffinity_np
95functions will return zero.
96Otherwise an error number will be returned
97to indicate the error.
98.Sh ERRORS
99The
100.Fn pthread_attr_getaffinity_np
101functions will fail if:
102.Bl -tag -width Er
103.It Bq Er EINVAL
104The
105.Fa pattr
106or the attribute specified by it is
107.Dv NULL .
108.It Bq Er ERANGE
109The
110.Fa cpusetsize
111is too small.
112.El
113.Pp
114The
115.Fn pthread_attr_setaffinity_np
116function will fail if:
117.Bl -tag -width Er
118.It Bq Er EINVAL
119The
120.Fa pattr
121or the attribute specified by it is
122.Dv NULL .
123.It Bq Er EINVAL
124The
125.Fa cpusetp
126specified a CPU that was outside the set supported by the kernel.
127.It Bq Er ENOMEM
128Insufficient memory exists to store the cpuset mask.
129.El
130.Sh SEE ALSO
131.Xr cpuset 1 ,
132.Xr cpuset 2 ,
133.Xr cpuset_getid 2 ,
134.Xr cpuset_setid 2 ,
135.Xr pthread_getaffinity_np 3 ,
136.Xr pthread_np 3 ,
137.Xr pthread_setaffinity_np 3
138.Sh STANDARDS
139The
140.Nm pthread_attr_getaffinity_np
141and
142.Nm pthread_attr_setaffinity_np
143functions are non-standard
144.Fx
145extensions and may be not available on other operating systems.
146.Sh HISTORY
147The
148.Nm pthread_attr_getaffinity_np
149and
150.Nm pthread_attr_setaffinity_np
151functions first appeared in
152.Fx 7.2 .
153.Sh AUTHORS
154.An -nosplit
155The
156.Nm pthread_attr_getaffinity_np
157and
158.Nm pthread_attr_setaffinity_np
159functions were written by
160.An David Xu Aq Mt davidxu@FreeBSD.org ,
161and this manpage was written by
162.An Xin LI Aq Mt delphij@FreeBSD.org .
163