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