1 .\" Copyright (c) 2008 Christian Brueffer
2 .\" Copyright (c) 2008 Jeffrey Roberson
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
8 .\" 1. Redistributions of source code must retain the above copyright
9 .\" notice, this list of conditions and the following disclaimer.
10 .\" 2. Redistributions in binary form must reproduce the above copyright
11 .\" notice, this list of conditions and the following disclaimer in the
12 .\" documentation and/or other materials provided with the distribution.
14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
17 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
35 .Nd manage CPU affinity sets
42 .Fn cpuset "cpusetid_t *setid"
44 .Fn cpuset_setid "cpuwhich_t which" "id_t id" "cpusetid_t setid"
46 .Fn cpuset_getid "cpulevel_t level" "cpuwhich_t which" "id_t id" "cpusetid_t *setid"
50 family of system calls allow applications to control sets of processors and
51 assign processes and threads to these sets.
52 Processor sets contain lists of CPUs that members may run on and exist only
53 as long as some process is a member of the set.
54 All processes in the system have an assigned set.
55 The default set for all processes in the system is the set numbered 1.
56 Threads belong to the same set as the process which contains them,
57 however, they may further restrict their set with the anonymous
60 Sets are referenced by a number of type
62 Each thread has a root set, an assigned set, and an anonymous mask.
63 Only the root and assigned sets are numbered.
64 The root set is the set of all CPUs available in the system or in the
65 system partition the thread is running in.
66 The assigned set is a subset of the root set and is administratively
67 assignable on a per-process basis.
68 Many processes and threads may be members of a numbered set.
70 The anonymous set is a further thread-specific refinement on the assigned
72 It is intended that administrators will manipulate numbered sets using
74 while application developers will manipulate anonymous sets using
75 .Xr cpuset_setaffinity 2 .
77 To select the correct set a value of type
80 The following values for
83 .Bl -column CPU_LEVEL_CPUSET -offset indent
84 .It Dv CPU_LEVEL_ROOT Ta "Root set"
85 .It Dv CPU_LEVEL_CPUSET Ta "Assigned set"
86 .It Dv CPU_LEVEL_WHICH Ta "Set specified by which argument"
91 argument determines how the value of
93 is interpreted and is of type
97 argument may have the following values:
98 .Bl -column CPU_WHICH_CPUSET -offset indent
99 .It Dv CPU_WHICH_TID Ta "id is lwpid_t (thread id)"
100 .It Dv CPU_WHICH_PID Ta "id is pid_t (process id)"
101 .It Dv CPU_WHICH_CPUSET Ta "id is a cpusetid_t (cpuset id)"
102 .It Dv CPU_WHICH_IRQ Ta "id is an irq number"
107 of '-1' may be used with a
114 to mean the current thread, process, or current thread's
116 All cpuset syscalls allow this usage.
126 refers to the anonymous mask of the object.
127 This mask does not have an id and may only be manipulated with
128 .Xr cpuset_setaffinity 2 .
131 creates a new set containing the same CPUs as the root set of the current
132 process and stores its id in the space provided by
134 On successful completion the calling process joins the set and is the
136 Children inherit this set after a call to
140 attempts to set the id of the object specified by the
145 is the only acceptable value for which as
146 threads do not have an id distinct from their process and the API does
147 not permit changing the id of an existing set.
148 Upon successful completion all of the threads in the target process will
149 be running on CPUs permitted by the set.
152 retrieves a set id from the object indicated by
154 and stores it in the space pointed to by
156 The retrieved id may be that of either the root or assigned set
157 depending on the value of
164 to get the set id from
165 the process or thread specified by the
170 with a process or thread is unsupported since
171 this references the unnumbered anonymous mask.
173 The actual contents of the sets may be retrieved or manipulated using
174 .Xr cpuset_getaffinity 2
176 .Xr cpuset_setaffinity 2 .
177 See those manual pages for more detail.
181 The following error codes may be set in
189 argument was not a valid value.
193 call would leave a thread without a valid CPU to run on because the set
194 does not overlap with the thread's anonymous mask.
196 The setid pointer passed to
202 The object specified by the
206 arguments could not be found.
208 The calling process did not have the credentials required to complete the
217 .Xr cpuset_getaffinity 2 ,
218 .Xr cpuset_setaffinity 2 ,
220 .Xr pthread_affinity_np 3 ,
221 .Xr pthread_attr_affinity_np 3
225 family of system calls first appeared in
228 .An Jeffrey Roberson Aq jeff@FreeBSD.org