]> CyberLeo.Net >> Repos - FreeBSD/FreeBSD.git/blob - share/man/man3/pthread_affinity_np.3
Remove $FreeBSD$: two-line nroff pattern
[FreeBSD/FreeBSD.git] / share / man / man3 / pthread_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 .Dd January 29, 2023
26 .Dt PTHREAD_AFFINITY_NP 3
27 .Os
28 .Sh NAME
29 .Nm pthread_getaffinity_np ,
30 .Nm pthread_setaffinity_np
31 .Nd manage CPU affinity
32 .Sh LIBRARY
33 .Lb libpthread
34 .Sh SYNOPSIS
35 .In pthread_np.h
36 .Ft int
37 .Fn pthread_getaffinity_np "pthread_t td" "size_t cpusetsize" "cpuset_t *cpusetp"
38 .Ft int
39 .Fn pthread_setaffinity_np "pthread_t td" "size_t cpusetsize" "const cpuset_t *cpusetp"
40 .Sh DESCRIPTION
41 .Fn pthread_getaffinity_np
42 and
43 .Fn pthread_setaffinity_np
44 allow the manipulation of sets of CPUs available to the specified thread.
45 .Pp
46 Masks of type
47 .Ft cpuset_t
48 are composed using the
49 .Dv CPU_SET
50 macros.
51 If the user-supplied mask is not large enough to fit all of the matching CPUs,
52 .Fn pthread_getaffinity_np
53 fails with
54 .Er ERANGE .
55 Calls to
56 .Fn pthread_setaffinity_np
57 tolerate masks of any size with no restrictions.
58 The kernel uses the meaningful part of the mask, where the upper bound is
59 the maximum CPU id present in the system.
60 If bits for non-existing CPUs are set, calls to
61 .Fn pthread_setaffinity_np
62 fail with
63 .Er EINVAL .
64 .Pp
65 The supplied mask should have a size of
66 .Fa cpusetsize
67 bytes.
68 This size is usually provided by calling
69 .Li sizeof(cpuset_t)
70 which is ultimately determined by the value of
71 .Dv CPU_SETSIZE
72 as defined in
73 .In sys/cpuset.h .
74 .Pp
75 .Fn pthread_getaffinity_np
76 retrieves the
77 mask from the thread specified by
78 .Fa td ,
79 and stores it in the space provided by
80 .Fa cpusetp .
81 .Pp
82 .Fn pthread_setaffinity_np
83 attempts to set the mask for the thread specified by
84 .Fa td
85 to the value in
86 .Fa cpusetp .
87 .Sh RETURN VALUES
88 If successful, the
89 .Fn pthread_getaffinity_np
90 and
91 .Fn pthread_setaffinity_np
92 functions will return zero.
93 Otherwise an error number will be returned
94 to indicate the error.
95 .Sh ERRORS
96 The
97 .Fn pthread_getaffinity_np
98 and
99 .Fn pthread_setaffinity_np
100 functions may fail if:
101 .Bl -tag -width Er
102 .It Bq Er EINVAL
103 The
104 .Fa cpusetp
105 argument specified when calling
106 .Fn pthread_setaffinity_np
107 was not a valid value.
108 .It Bq Er EDEADLK
109 The
110 .Fn pthread_setaffinity_np
111 call would leave a thread without a valid CPU to run on because the set
112 does not overlap with the thread's anonymous mask.
113 .It Bq Er EFAULT
114 The
115 .Fa cpusetp
116 pointer passed was invalid.
117 .It Bq Er ESRCH
118 The thread specified by the
119 .Fa td
120 argument could not be found.
121 .It Bq Er ERANGE
122 The
123 .Fa cpusetsize
124 was smaller than needed to fit all of the matching CPUs.
125 .It Bq Er EPERM
126 The calling thread did not have the credentials required to complete the
127 operation.
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 3 ,
135 .Xr pthread_attr_getaffinity_np 3 ,
136 .Xr pthread_attr_setaffinity_np 3 ,
137 .Xr pthread_np 3
138 .Sh STANDARDS
139 The
140 .Nm pthread_getaffinity_np
141 and
142 .Nm pthread_setaffinity_np
143 functions are non-standard
144 .Fx
145 extensions and may be not available on other operating systems.
146 .Sh HISTORY
147 The
148 .Nm pthread_getaffinity_np
149 and
150 .Nm pthread_setaffinity_np
151 function first appeared in
152 .Fx 7.2 .
153 .Sh AUTHORS
154 .An -nosplit
155 The
156 .Nm pthread_getaffinity_np
157 and
158 .Nm pthread_setaffinity_np
159 functions were written by
160 .An David Xu Aq Mt davidxu@FreeBSD.org ,
161 and this manpage was written by
162 .An Xin LI Aq Mt delphij@FreeBSD.org .