| blob | fd15f23b7eb794f7dab098e6c5d8896a1de8400a |
1 .\" Copyright (C) 2006 Michael Kerrisk
2 .\" and Copyright (C) 2008 Linux Foundation, written by Michael Kerrisk
3 .\" <mtk.manpages@gmail.com>
4 .\"
5 .\" %%%LICENSE_START(VERBATIM)
6 .\" Permission is granted to make and distribute verbatim copies of this
7 .\" manual provided the copyright notice and this permission notice are
8 .\" preserved on all copies.
9 .\"
10 .\" Permission is granted to copy and distribute modified versions of this
11 .\" manual under the conditions for verbatim copying, provided that the
12 .\" entire resulting derived work is distributed under the terms of a
13 .\" permission notice identical to this one.
14 .\"
15 .\" Since the Linux kernel and libraries are constantly changing, this
16 .\" manual page may be incorrect or out-of-date. The author(s) assume no
17 .\" responsibility for errors or omissions, or for damages resulting from
18 .\" the use of the information contained herein. The author(s) may not
19 .\" have taken the same level of care in the production of this manual,
20 .\" which is licensed free of charge, as they might when working
21 .\" professionally.
22 .\"
23 .\" Formatted or processed versions of this manual, if unaccompanied by
24 .\" the source, must acknowledge the copyright and authors of this work.
25 .\" %%%LICENSE_END
26 .\"
27 .TH CPU_SET 3 2021-03-22 "Linux" "Linux Programmer's Manual"
28 .SH NAME
29 CPU_SET, CPU_CLR, CPU_ISSET, CPU_ZERO, CPU_COUNT,
30 CPU_AND, CPU_OR, CPU_XOR, CPU_EQUAL,
31 CPU_ALLOC, CPU_ALLOC_SIZE, CPU_FREE,
32 CPU_SET_S, CPU_CLR_S, CPU_ISSET_S, CPU_ZERO_S,
33 CPU_COUNT_S, CPU_AND_S, CPU_OR_S, CPU_XOR_S, CPU_EQUAL_S \-
34 macros for manipulating CPU sets
35 .SH SYNOPSIS
36 .nf
37 .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */"
38 .B #include <sched.h>
39 .PP
40 .BI "void CPU_ZERO(cpu_set_t *" set );
41 .PP
42 .BI "void CPU_SET(int " cpu ", cpu_set_t *" set );
43 .BI "void CPU_CLR(int " cpu ", cpu_set_t *" set );
44 .BI "int CPU_ISSET(int " cpu ", cpu_set_t *" set );
45 .PP
46 .BI "int CPU_COUNT(cpu_set_t *" set );
47 .PP
48 .BI "void CPU_AND(cpu_set_t *" destset ,
49 .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
50 .BI "void CPU_OR(cpu_set_t *" destset ,
51 .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
52 .BI "void CPU_XOR(cpu_set_t *" destset ,
53 .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
54 .PP
55 .BI "int CPU_EQUAL(cpu_set_t *" set1 ", cpu_set_t *" set2 );
56 .PP
57 .BI "cpu_set_t *CPU_ALLOC(int " num_cpus );
58 .BI "void CPU_FREE(cpu_set_t *" set );
59 .BI "size_t CPU_ALLOC_SIZE(int " num_cpus );
60 .PP
61 .BI "void CPU_ZERO_S(size_t " setsize ", cpu_set_t *" set );
62 .PP
63 .BI "void CPU_SET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set );
64 .BI "void CPU_CLR_S(int " cpu ", size_t " setsize ", cpu_set_t *" set );
65 .BI "int CPU_ISSET_S(int " cpu ", size_t " setsize ", cpu_set_t *" set );
66 .PP
67 .BI "int CPU_COUNT_S(size_t " setsize ", cpu_set_t *" set );
68 .PP
69 .BI "void CPU_AND_S(size_t " setsize ", cpu_set_t *" destset ,
70 .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
71 .BI "void CPU_OR_S(size_t " setsize ", cpu_set_t *" destset ,
72 .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
73 .BI "void CPU_XOR_S(size_t " setsize ", cpu_set_t *" destset ,
74 .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 );
75 .PP
76 .BI "int CPU_EQUAL_S(size_t " setsize ", cpu_set_t *" set1 \
77 ", cpu_set_t *" set2 );
78 .fi
79 .SH DESCRIPTION
80 The
81 .I cpu_set_t
82 data structure represents a set of CPUs.
83 CPU sets are used by
84 .BR sched_setaffinity (2)
85 and similar interfaces.
86 .PP
87 The
88 .I cpu_set_t
89 data type is implemented as a bit mask.
90 However, the data structure should be treated as opaque:
91 all manipulation of CPU sets should be done via the macros
92 described in this page.
93 .PP
94 The following macros are provided to operate on the CPU set
95 .IR set :
96 .TP
97 .BR CPU_ZERO ()
98 Clears
99 .IR set ,
100 so that it contains no CPUs.
101 .TP
102 .BR CPU_SET ()
103 Add CPU
104 .I cpu
105 to
106 .IR set .
107 .TP
108 .BR CPU_CLR ()
109 Remove CPU
110 .I cpu
111 from
112 .IR set .
113 .TP
114 .BR CPU_ISSET ()
115 Test to see if CPU
116 .I cpu
117 is a member of
118 .IR set .
119 .TP
120 .BR CPU_COUNT ()
121 Return the number of CPUs in
122 .IR set .
123 .PP
124 Where a
125 .I cpu
126 argument is specified, it should not produce side effects,
127 since the above macros may evaluate the argument more than once.
128 .PP
129 The first CPU on the system corresponds to a
130 .I cpu
131 value of 0, the next CPU corresponds to a
132 .I cpu
133 value of 1, and so on.
134 No assumptions should be made about particular CPUs being
135 available, or the set of CPUs being contiguous, since CPUs can
136 be taken offline dynamically or be otherwise absent.
137 The constant
138 .B CPU_SETSIZE
139 (currently 1024) specifies a value one greater than the maximum CPU
140 number that can be stored in
141 .IR cpu_set_t .
142 .PP
143 The following macros perform logical operations on CPU sets:
144 .TP
145 .BR CPU_AND ()
146 Store the intersection of the sets
147 .I srcset1
148 and
149 .I srcset2
150 in
151 .I destset
152 (which may be one of the source sets).
153 .TP
154 .BR CPU_OR ()
155 Store the union of the sets
156 .I srcset1
157 and
158 .I srcset2
159 in
160 .I destset
161 (which may be one of the source sets).
162 .TP
163 .BR CPU_XOR ()
164 Store the XOR of the sets
165 .I srcset1
166 and
167 .I srcset2
168 in
169 .I destset
170 (which may be one of the source sets).
171 The XOR means the set of CPUs that are in either
172 .I srcset1
173 or
174 .IR srcset2 ,
175 but not both.
176 .TP
177 .BR CPU_EQUAL ()
178 Test whether two CPU set contain exactly the same CPUs.
179 .SS Dynamically sized CPU sets
180 Because some applications may require the ability to dynamically
181 size CPU sets (e.g., to allocate sets larger than that
182 defined by the standard
183 .I cpu_set_t
184 data type), glibc nowadays provides a set of macros to support this.
185 .PP
186 The following macros are used to allocate and deallocate CPU sets:
187 .TP
188 .BR CPU_ALLOC ()
189 Allocate a CPU set large enough to hold CPUs
190 in the range 0 to
191 .IR num_cpus\-1 .
192 .TP
193 .BR CPU_ALLOC_SIZE ()
194 Return the size in bytes of the CPU set that would be needed to
195 hold CPUs in the range 0 to
196 .IR num_cpus\-1 .
197 This macro provides the value that can be used for the
198 .I setsize
199 argument in the
200 .BR CPU_*_S ()
201 macros described below.
202 .TP
203 .BR CPU_FREE ()
204 Free a CPU set previously allocated by
205 .BR CPU_ALLOC ().
206 .PP
207 The macros whose names end with "_S" are the analogs of
208 the similarly named macros without the suffix.
209 These macros perform the same tasks as their analogs,
210 but operate on the dynamically allocated CPU set(s) whose size is
211 .I setsize
212 bytes.
213 .SH RETURN VALUE
214 .BR CPU_ISSET ()
215 and
216 .BR CPU_ISSET_S ()
217 return nonzero if
218 .I cpu
219 is in
220 .IR set ;
221 otherwise, it returns 0.
222 .PP
223 .BR CPU_COUNT ()
224 and
225 .BR CPU_COUNT_S ()
226 return the number of CPUs in
227 .IR set .
228 .PP
229 .BR CPU_EQUAL ()
230 and
231 .BR CPU_EQUAL_S ()
232 return nonzero if the two CPU sets are equal; otherwise they return 0.
233 .PP
234 .BR CPU_ALLOC ()
235 returns a pointer on success, or NULL on failure.
236 (Errors are as for
237 .BR malloc (3).)
238 .PP
239 .BR CPU_ALLOC_SIZE ()
240 returns the number of bytes required to store a
241 CPU set of the specified cardinality.
242 .PP
243 The other functions do not return a value.
244 .SH VERSIONS
245 The
246 .BR CPU_ZERO (),
247 .BR CPU_SET (),
248 .BR CPU_CLR (),
249 and
250 .BR CPU_ISSET ()
251 macros were added in glibc 2.3.3.
252 .PP
253 .BR CPU_COUNT ()
254 first appeared in glibc 2.6.
255 .PP
256 .BR CPU_AND (),
257 .BR CPU_OR (),
258 .BR CPU_XOR (),
259 .BR CPU_EQUAL (),
260 .BR CPU_ALLOC (),
261 .BR CPU_ALLOC_SIZE (),
262 .BR CPU_FREE (),
263 .BR CPU_ZERO_S (),
264 .BR CPU_SET_S (),
265 .BR CPU_CLR_S (),
266 .BR CPU_ISSET_S (),
267 .BR CPU_AND_S (),
268 .BR CPU_OR_S (),
269 .BR CPU_XOR_S (),
270 and
271 .BR CPU_EQUAL_S ()
272 first appeared in glibc 2.7.
273 .SH CONFORMING TO
274 These interfaces are Linux-specific.
275 .SH NOTES
276 To duplicate a CPU set, use
277 .BR memcpy (3).
278 .PP
279 Since CPU sets are bit masks allocated in units of long words,
280 the actual number of CPUs in a dynamically
281 allocated CPU set will be rounded up to the next multiple of
282 .IR "sizeof(unsigned long)" .
283 An application should consider the contents of these extra bits
284 to be undefined.
285 .PP
286 Notwithstanding the similarity in the names,
287 note that the constant
288 .B CPU_SETSIZE
289 indicates the number of CPUs in the
290 .I cpu_set_t
291 data type (thus, it is effectively a count of the bits in the bit mask),
292 while the
293 .I setsize
294 argument of the
295 .BR CPU_*_S ()
296 macros is a size in bytes.
297 .PP
298 The data types for arguments and return values shown
299 in the SYNOPSIS are hints what about is expected in each case.
300 However, since these interfaces are implemented as macros,
301 the compiler won't necessarily catch all type errors
302 if you violate the suggestions.
303 .SH BUGS
304 On 32-bit platforms with glibc 2.8 and earlier,
305 .BR CPU_ALLOC ()
306 allocates twice as much space as is required, and
307 .BR CPU_ALLOC_SIZE ()
308 returns a value twice as large as it should.
309 This bug should not affect the semantics of a program,
310 but does result in wasted memory
311 and less efficient operation of the macros that
312 operate on dynamically allocated CPU sets.
313 These bugs are fixed in glibc 2.9.
314 .\" http://sourceware.org/bugzilla/show_bug.cgi?id=7029
315 .SH EXAMPLES
316 The following program demonstrates the use of some of the macros
317 used for dynamically allocated CPU sets.
318 .PP
319 .EX
320 #define _GNU_SOURCE
321 #include <sched.h>
322 #include <stdlib.h>
323 #include <unistd.h>
324 #include <stdio.h>
325 #include <assert.h>
327 int
328 main(int argc, char *argv[])
329 {
330 cpu_set_t *cpusetp;
331 size_t size;
332 int num_cpus;
334 if (argc < 2) {
335 fprintf(stderr, "Usage: %s <num\-cpus>\en", argv[0]);
336 exit(EXIT_FAILURE);
337 }
339 num_cpus = atoi(argv[1]);
341 cpusetp = CPU_ALLOC(num_cpus);
342 if (cpusetp == NULL) {
343 perror("CPU_ALLOC");
344 exit(EXIT_FAILURE);
345 }
347 size = CPU_ALLOC_SIZE(num_cpus);
349 CPU_ZERO_S(size, cpusetp);
350 for (int cpu = 0; cpu < num_cpus; cpu += 2)
351 CPU_SET_S(cpu, size, cpusetp);
353 printf("CPU_COUNT() of set: %d\en", CPU_COUNT_S(size, cpusetp));
355 CPU_FREE(cpusetp);
356 exit(EXIT_SUCCESS);
357 }
358 .EE
359 .SH SEE ALSO
360 .BR sched_setaffinity (2),
361 .BR pthread_attr_setaffinity_np (3),
362 .BR pthread_setaffinity_np (3),
363 .BR cpuset (7)