1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
|
<table class="head">
<tr>
<td class="head-ltitle">PTHREAD_ATTR_AFFINITY_NP(3)</td>
<td class="head-vol">Library Functions Manual</td>
<td class="head-rtitle">PTHREAD_ATTR_AFFINITY_NP(3)</td>
</tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">pthread_attr_getaffinity_np</code>,
<code class="Nm">pthread_attr_setaffinity_np</code> —
<span class="Nd">manage CPU affinity in thread attribute objects</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="LIBRARY"><a class="permalink" href="#LIBRARY">LIBRARY</a></h1>
<p class="Pp"><span class="Lb">POSIX Threads Library (libpthread,
-lpthread)</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
<<a class="In">pthread_np.h</a>></code></p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">pthread_attr_getaffinity_np</code>(<var class="Fa" style="white-space: nowrap;">const
pthread_attr_t *pattr</var>,
<var class="Fa" style="white-space: nowrap;">size_t cpusetsize</var>,
<var class="Fa" style="white-space: nowrap;">cpuset_t *cpusetp</var>);</p>
<p class="Pp"><var class="Ft">int</var>
<br/>
<code class="Fn">pthread_attr_setaffinity_np</code>(<var class="Fa" style="white-space: nowrap;">pthread_attr_t
*pattr</var>, <var class="Fa" style="white-space: nowrap;">size_t
cpusetsize</var>, <var class="Fa" style="white-space: nowrap;">const
cpuset_t *cpusetp</var>);</p>
</section>
<section class="Sh">
<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1>
<p class="Pp">The
<a class="permalink" href="#pthread_attr_getaffinity_np"><code class="Fn" id="pthread_attr_getaffinity_np">pthread_attr_getaffinity_np</code></a>()
and <code class="Fn">pthread_attr_setaffinity_np</code>() functions allow
the manipulation of sets of CPUs available to the specified thread attribute
object.</p>
<p class="Pp" id="pthread_attr_getaffinity_np~2">Masks of type
<var class="Ft">cpuset_t</var> are composed using the
<code class="Dv">CPU_SET</code> macros. If the user-supplied mask is not
large enough to fit all of the matching CPUs,
<a class="permalink" href="#pthread_attr_getaffinity_np~2"><code class="Fn">pthread_attr_getaffinity_np</code></a>()
fails with <code class="Er">ERANGE</code>. Calls to
<code class="Fn">pthread_attr_setaffinity_np</code>() tolerate masks of any
size with no restrictions.
<code class="Fn">pthread_attr_setaffinity_np</code>() uses the meaningful
part of the mask, where the upper bound is the maximum CPU id present in the
system. If bits for non-existing CPUs are set, calls to
<code class="Fn">pthread_attr_setaffinity_np</code>() fail with
<code class="Er">EINVAL</code>.</p>
<p class="Pp">The supplied mask should have a size of
<var class="Fa">cpusetsize</var> bytes. This size is usually provided by
calling <code class="Li">sizeof(cpuset_t)</code> which is ultimately
determined by the value of <code class="Dv">CPU_SETSIZE</code> as defined in
<code class="In"><<a class="In">sys/cpuset.h</a>></code>.</p>
<p class="Pp" id="pthread_attr_getaffinity_np~3"><a class="permalink" href="#pthread_attr_getaffinity_np~3"><code class="Fn">pthread_attr_getaffinity_np</code></a>()
retrieves the mask from the thread attribute object specified by
<var class="Fa">pattr</var>, and stores it in the space provided by
<var class="Fa">cpusetp</var>.</p>
<p class="Pp" id="pthread_attr_setaffinity_np"><a class="permalink" href="#pthread_attr_setaffinity_np"><code class="Fn">pthread_attr_setaffinity_np</code></a>()
sets the mask for the thread attribute object specified by
<var class="Fa">pattr</var> to the value in
<var class="Fa">cpusetp</var>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="RETURN_VALUES"><a class="permalink" href="#RETURN_VALUES">RETURN
VALUES</a></h1>
<p class="Pp">If successful, the
<code class="Fn">pthread_attr_getaffinity_np</code>() and
<code class="Fn">pthread_attr_setaffinity_np</code>() functions will return
zero. Otherwise an error number will be returned to indicate the error.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="ERRORS"><a class="permalink" href="#ERRORS">ERRORS</a></h1>
<p class="Pp">The <code class="Fn">pthread_attr_getaffinity_np</code>()
functions will fail if:</p>
<dl class="Bl-tag">
<dt id="EINVAL">[<a class="permalink" href="#EINVAL"><code class="Er">EINVAL</code></a>]</dt>
<dd>The <var class="Fa">pattr</var> or the attribute specified by it is
<code class="Dv">NULL</code>.</dd>
<dt id="ERANGE">[<a class="permalink" href="#ERANGE"><code class="Er">ERANGE</code></a>]</dt>
<dd>The <var class="Fa">cpusetsize</var> is too small.</dd>
</dl>
<p class="Pp">The <code class="Fn">pthread_attr_setaffinity_np</code>() function
will fail if:</p>
<dl class="Bl-tag">
<dt id="EINVAL~2">[<a class="permalink" href="#EINVAL~2"><code class="Er">EINVAL</code></a>]</dt>
<dd>The <var class="Fa">pattr</var> or the attribute specified by it is
<code class="Dv">NULL</code>.</dd>
<dt id="EINVAL~3">[<a class="permalink" href="#EINVAL~3"><code class="Er">EINVAL</code></a>]</dt>
<dd>The <var class="Fa">cpusetp</var> specified a CPU that was outside the set
supported by the kernel.</dd>
<dt id="ENOMEM">[<a class="permalink" href="#ENOMEM"><code class="Er">ENOMEM</code></a>]</dt>
<dd>Insufficient memory exists to store the cpuset mask.</dd>
</dl>
</section>
<section class="Sh">
<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE
ALSO</a></h1>
<p class="Pp"><a class="Xr">cpuset(1)</a>, <a class="Xr">cpuset(2)</a>,
<a class="Xr">cpuset_getid(2)</a>, <a class="Xr">cpuset_setid(2)</a>,
<a class="Xr">pthread_getaffinity_np(3)</a>,
<a class="Xr">pthread_np(3)</a>,
<a class="Xr">pthread_setaffinity_np(3)</a></p>
</section>
<section class="Sh">
<h1 class="Sh" id="STANDARDS"><a class="permalink" href="#STANDARDS">STANDARDS</a></h1>
<p class="Pp">The <code class="Nm">pthread_attr_getaffinity_np</code> and
<code class="Nm">pthread_attr_setaffinity_np</code> functions are
non-standard <span class="Ux">FreeBSD</span> extensions and may be not
available on other operating systems.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="HISTORY"><a class="permalink" href="#HISTORY">HISTORY</a></h1>
<p class="Pp">The <code class="Nm">pthread_attr_getaffinity_np</code> and
<code class="Nm">pthread_attr_setaffinity_np</code> functions first appeared
in <span class="Ux">FreeBSD 7.2</span>.</p>
</section>
<section class="Sh">
<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1>
<p class="Pp">The <code class="Nm">pthread_attr_getaffinity_np</code> and
<code class="Nm">pthread_attr_setaffinity_np</code> functions were written
by <span class="An">David Xu</span>
<<a class="Mt" href="mailto:davidxu@FreeBSD.org">davidxu@FreeBSD.org</a>>,
and this manpage was written by <span class="An">Xin LI</span>
<<a class="Mt" href="mailto:delphij@FreeBSD.org">delphij@FreeBSD.org</a>>.</p>
</section>
</div>
<table class="foot">
<tr>
<td class="foot-date">January 29, 2023</td>
<td class="foot-os">FreeBSD 15.0</td>
</tr>
</table>
|
