Debian Codegraph @

upstream/debian-unstable/man3/CPU_SET.3

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