Debian Codegraph @

upstream/debian-trixie/man3/CPU_SET.3

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