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