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 March 23, 2010
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.
53The kernel tolerates large sets as long as all CPUs specified
54in the set exist.
55Sets smaller than the kernel uses generate an error on calls to
56.Fn pthread_getaffinity_np
57even if the result set would fit within the user supplied set.
58Calls to
59.Fn pthread_setaffinity_np
60tolerate small sets with no restrictions.
61.Pp
62The supplied mask should have a size of
63.Fa cpusetsize
64bytes.
65This size is usually provided by calling
66.Li sizeof(cpuset_t)
67which is ultimately determined by the value of
68.Dv CPU_SETSIZE
69as defined in
70.In sys/cpuset.h .
71.Pp
72.Fn pthread_getaffinity_np
73retrieves the
74mask from the thread specified by
75.Fa td ,
76and stores it in the space provided by
77.Fa cpusetp .
78.Pp
79.Fn pthread_setaffinity_np
80attempts to set the mask for the thread specified by
81.Fa td
82to the value in
83.Fa cpusetp .
84.Sh RETURN VALUES
85If successful, the
86.Fn pthread_getaffinity_np
87and
88.Fn pthread_setaffinity_np
89functions will return zero.
90Otherwise an error number will be returned
91to indicate the error.
92.Sh ERRORS
93The
94.Fn pthread_getaffinity_np
95and
96.Fn pthread_setaffinity_np
97functions may fail if:
98.Bl -tag -width Er
99.It Bq Er EDEADLK
100The
101.Fn pthread_setaffinity_np
102call would leave a thread without a valid CPU to run on because the set
103does not overlap with the thread's anonymous mask.
104.It Bq Er EFAULT
105The
106.Fa cpusetp
107pointer passed was invalid.
108.It Bq Er ESRCH
109The thread specified by the
110.Fa td
111argument could not be found.
112.It Bq Er ERANGE
113The
114.Fa cpusetsize
115was either preposterously large or smaller than the kernel set size.
116.It Bq Er EPERM
117The calling thread did not have the credentials required to complete the
118operation.
119.El
120.Sh SEE ALSO
121.Xr cpuset 1 ,
122.Xr cpuset 2 ,
123.Xr cpuset_getid 2 ,
124.Xr cpuset_setid 2 ,
125.Xr pthread 3 ,
126.Xr pthread_attr_getaffinity_np 3 ,
127.Xr pthread_attr_setaffinity_np 3
128.Sh STANDARDS
129The
130.Nm pthread_getaffinity_np
131and
132.Nm pthread_setaffinity_np
133functions are non-standard
134.Fx
135extensions and may be not available on other operating systems.
136.Sh HISTORY
137The
138.Nm pthread_getaffinity_np
139and
140.Nm pthread_setaffinity_np
141function first appeared in
142.Fx 7.2 .
143.Sh AUTHORS
144.An -nosplit
145The
146.Nm pthread_getaffinity_np
147and
148.Nm pthread_setaffinity_np
149functions were written by
150.An David Xu Aq Mt davidxu@FreeBSD.org ,
151and this manpage was written by
152.An Xin LI Aq Mt delphij@FreeBSD.org .
153