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 January 29, 2023
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.
53If the user-supplied mask is not large enough to fit all of the matching CPUs,
54.Fn pthread_getaffinity_np
55fails with
56.Er ERANGE .
57Calls to
58.Fn pthread_setaffinity_np
59tolerate masks of any size with no restrictions.
60The kernel uses 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_setaffinity_np
64fails 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_getaffinity_np
78retrieves the
79mask from the thread specified by
80.Fa td ,
81and stores it in the space provided by
82.Fa cpusetp .
83.Pp
84.Fn pthread_setaffinity_np
85attempts to set the mask for the thread specified by
86.Fa td
87to the value in
88.Fa cpusetp .
89.Sh RETURN VALUES
90If successful, the
91.Fn pthread_getaffinity_np
92and
93.Fn pthread_setaffinity_np
94functions will return zero.
95Otherwise an error number will be returned
96to indicate the error.
97.Sh ERRORS
98The
99.Fn pthread_getaffinity_np
100and
101.Fn pthread_setaffinity_np
102functions may fail if:
103.Bl -tag -width Er
104.It Bq Er EINVAL
105The
106.Fa cpusetp
107argument specified when calling
108.Fn pthread_setaffinity_np
109was not a valid value.
110.It Bq Er EDEADLK
111The
112.Fn pthread_setaffinity_np
113call would leave a thread without a valid CPU to run on because the set
114does not overlap with the thread's anonymous mask.
115.It Bq Er EFAULT
116The
117.Fa cpusetp
118pointer passed was invalid.
119.It Bq Er ESRCH
120The thread specified by the
121.Fa td
122argument could not be found.
123.It Bq Er ERANGE
124The
125.Fa cpusetsize
126was smaller than needed to fit all of the matching CPUs.
127.It Bq Er EPERM
128The calling thread did not have the credentials required to complete the
129operation.
130.El
131.Sh SEE ALSO
132.Xr cpuset 1 ,
133.Xr cpuset 2 ,
134.Xr cpuset_getid 2 ,
135.Xr cpuset_setid 2 ,
136.Xr pthread 3 ,
137.Xr pthread_attr_getaffinity_np 3 ,
138.Xr pthread_attr_setaffinity_np 3 ,
139.Xr pthread_np 3
140.Sh STANDARDS
141The
142.Nm pthread_getaffinity_np
143and
144.Nm pthread_setaffinity_np
145functions are non-standard
146.Fx
147extensions and may be not available on other operating systems.
148.Sh HISTORY
149The
150.Nm pthread_getaffinity_np
151and
152.Nm pthread_setaffinity_np
153function first appeared in
154.Fx 7.2 .
155.Sh AUTHORS
156.An -nosplit
157The
158.Nm pthread_getaffinity_np
159and
160.Nm pthread_setaffinity_np
161functions were written by
162.An David Xu Aq Mt davidxu@FreeBSD.org ,
163and this manpage was written by
164.An Xin LI Aq Mt delphij@FreeBSD.org .
165