]>
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 | .\" | |
93015253 | 5 | .\" %%%LICENSE_START(VERBATIM) |
a9cdb1db MK |
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. | |
4b72fb64 | 25 | .\" %%%LICENSE_END |
a9cdb1db | 26 | .\" |
4b8c67d9 | 27 | .TH CPU_SET 3 2017-09-15 "Linux" "Linux Programmer's Manual" |
a9cdb1db | 28 | .SH NAME |
94934ae7 | 29 | CPU_SET, CPU_CLR, CPU_ISSET, CPU_ZERO, CPU_COUNT, |
a113945f | 30 | CPU_AND, CPU_OR, CPU_XOR, CPU_EQUAL, |
488d0e98 MK |
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 \- | |
a9cdb1db MK |
34 | macros for manipulating CPU sets |
35 | .SH SYNOPSIS | |
36 | .nf | |
86b91fdf | 37 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
a9cdb1db | 38 | .B #include <sched.h> |
68e4db0a | 39 | .PP |
df79be82 | 40 | .BI "void CPU_ZERO(cpu_set_t *" set ); |
68e4db0a | 41 | .PP |
a9cdb1db | 42 | .BI "void CPU_SET(int " cpu ", cpu_set_t *" set ); |
df79be82 | 43 | .BI "void CPU_CLR(int " cpu ", cpu_set_t *" set ); |
df79be82 | 44 | .BI "int CPU_ISSET(int " cpu ", cpu_set_t *" set ); |
68e4db0a | 45 | .PP |
1b6ece46 | 46 | .BI "int CPU_COUNT(cpu_set_t *" set ); |
68e4db0a | 47 | .PP |
a113945f | 48 | .BI "void CPU_AND(cpu_set_t *" destset , |
94934ae7 | 49 | .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); |
a113945f | 50 | .BI "void CPU_OR(cpu_set_t *" destset , |
94934ae7 | 51 | .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); |
a113945f | 52 | .BI "void CPU_XOR(cpu_set_t *" destset , |
94934ae7 | 53 | .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); |
68e4db0a | 54 | .PP |
94934ae7 | 55 | .BI "int CPU_EQUAL(cpu_set_t *" set1 ", cpu_set_t *" set2 ); |
68e4db0a | 56 | .PP |
488d0e98 | 57 | .BI "cpu_set_t *CPU_ALLOC(int " num_cpus ); |
314c72c3 | 58 | .BI "void CPU_FREE(cpu_set_t *" set ); |
aa633a58 | 59 | .BI "size_t CPU_ALLOC_SIZE(int " num_cpus ); |
68e4db0a | 60 | .PP |
488d0e98 | 61 | .BI "void CPU_ZERO_S(size_t " setsize ", cpu_set_t *" set ); |
68e4db0a | 62 | .PP |
488d0e98 MK |
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 ); | |
68e4db0a | 66 | .PP |
1b6ece46 | 67 | .BI "int CPU_COUNT_S(size_t " setsize ", cpu_set_t *" set ); |
68e4db0a | 68 | .PP |
a113945f | 69 | .BI "void CPU_AND_S(size_t " setsize ", cpu_set_t *" destset , |
488d0e98 | 70 | .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); |
a113945f | 71 | .BI "void CPU_OR_S(size_t " setsize ", cpu_set_t *" destset , |
488d0e98 | 72 | .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); |
a113945f | 73 | .BI "void CPU_XOR_S(size_t " setsize ", cpu_set_t *" destset , |
488d0e98 | 74 | .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); |
68e4db0a | 75 | .PP |
488d0e98 MK |
76 | .BI "int CPU_EQUAL_S(size_t " setsize ", cpu_set_t *" set1 \ |
77 | ", cpu_set_t *" set2 ); | |
a9cdb1db MK |
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. | |
847e0d88 | 86 | .PP |
69241990 MK |
87 | The |
88 | .I cpu_set_t | |
77227d36 | 89 | data type is implemented as a bit mask. |
69241990 MK |
90 | However, the data structure treated as considered opaque: |
91 | all manipulation of CPU sets should be done via the macros | |
92 | described in this page. | |
847e0d88 | 93 | .PP |
a9cdb1db MK |
94 | The following macros are provided to operate on the CPU set |
95 | .IR set : | |
488d0e98 | 96 | .TP 17 |
a9cdb1db | 97 | .BR CPU_ZERO () |
94934ae7 MK |
98 | Clears |
99 | .IR set , | |
a9cdb1db MK |
100 | so that it contains no CPUs. |
101 | .TP | |
102 | .BR CPU_SET () | |
94934ae7 | 103 | Add CPU |
a9cdb1db MK |
104 | .I cpu |
105 | to | |
106 | .IR set . | |
107 | .TP | |
108 | .BR CPU_CLR () | |
94934ae7 | 109 | Remove CPU |
a9cdb1db MK |
110 | .I cpu |
111 | from | |
112 | .IR set . | |
113 | .TP | |
114 | .BR CPU_ISSET () | |
94934ae7 | 115 | Test to see if CPU |
a9cdb1db MK |
116 | .I cpu |
117 | is a member of | |
118 | .IR set . | |
639c5cc8 MK |
119 | .TP |
120 | .BR CPU_COUNT () | |
94934ae7 | 121 | Return the number of CPUs in |
639c5cc8 | 122 | .IR set . |
a9cdb1db MK |
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 | |
a6eb4055 | 129 | The first CPU on the system corresponds to a |
a9cdb1db MK |
130 | .I cpu |
131 | value of 0, the next CPU corresponds to a | |
132 | .I cpu | |
133 | value of 1, and so on. | |
a6eb4055 CM |
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. | |
a9cdb1db MK |
137 | The constant |
138 | .B CPU_SETSIZE | |
f7eec897 | 139 | (currently 1024) specifies a value one greater than the maximum CPU |
488d0e98 MK |
140 | number that can be stored in |
141 | .IR cpu_set_t . | |
847e0d88 | 142 | .PP |
488d0e98 MK |
143 | The following macros perform logical operations on CPU sets: |
144 | .TP 17 | |
94934ae7 | 145 | .BR CPU_AND () |
9ccbb26c | 146 | Store the intersection of the sets |
94934ae7 MK |
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 () | |
9ccbb26c | 155 | Store the union of the sets |
94934ae7 MK |
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 () | |
9ccbb26c | 164 | Store the XOR of the sets |
94934ae7 MK |
165 | .I srcset1 |
166 | and | |
167 | .I srcset2 | |
168 | in | |
169 | .I destset | |
170 | (which may be one of the source sets). | |
9ccbb26c MK |
171 | The XOR means the set of CPUs that are in either |
172 | .I srcset1 | |
173 | or | |
174 | .IR srcset2 , | |
175 | but not both. | |
94934ae7 MK |
176 | .TP |
177 | .BR CPU_EQUAL () | |
488d0e98 MK |
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. | |
847e0d88 | 185 | .PP |
488d0e98 MK |
186 | The following macros are used to allocate and deallocate CPU sets: |
187 | .TP 17 | |
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 . | |
69241990 | 197 | This macro provides the value that can be used for the |
488d0e98 | 198 | .I setsize |
69241990 | 199 | argument in the |
488d0e98 MK |
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 | |
214c1dd2 | 207 | The macros whose names end with "_S" are the analogs of |
488d0e98 MK |
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. | |
47297adb | 213 | .SH RETURN VALUE |
a9cdb1db | 214 | .BR CPU_ISSET () |
488d0e98 MK |
215 | and |
216 | .BR CPU_ISSET_S () | |
c7094399 | 217 | return nonzero if |
a9cdb1db MK |
218 | .I cpu |
219 | is in | |
220 | .IR set ; | |
221 | otherwise, it returns 0. | |
847e0d88 | 222 | .PP |
639c5cc8 | 223 | .BR CPU_COUNT () |
488d0e98 MK |
224 | and |
225 | .BR CPU_COUNT_S () | |
226 | return the number of CPUs in | |
639c5cc8 | 227 | .IR set . |
847e0d88 | 228 | .PP |
94934ae7 | 229 | .BR CPU_EQUAL () |
488d0e98 MK |
230 | and |
231 | .BR CPU_EQUAL_S () | |
cf486e4a | 232 | return nonzero if the two CPU sets are equal; otherwise they return 0. |
847e0d88 | 233 | .PP |
488d0e98 MK |
234 | .BR CPU_ALLOC () |
235 | returns a pointer on success, or NULL on failure. | |
236 | (Errors are as for | |
237 | .BR malloc (3).) | |
847e0d88 | 238 | .PP |
488d0e98 MK |
239 | .BR CPU_ALLOC_SIZE () |
240 | returns the number of bytes required to store a | |
241 | CPU set of the specified cardinality. | |
847e0d88 | 242 | .PP |
a9cdb1db | 243 | The other functions do not return a value. |
a9cdb1db MK |
244 | .SH VERSIONS |
245 | The | |
246 | .BR CPU_ZERO (), | |
a9cdb1db | 247 | .BR CPU_SET (), |
df79be82 | 248 | .BR CPU_CLR (), |
a9cdb1db MK |
249 | and |
250 | .BR CPU_ISSET () | |
251 | macros were added in glibc 2.3.3. | |
847e0d88 | 252 | .PP |
639c5cc8 MK |
253 | .BR CPU_COUNT () |
254 | first appeared in glibc 2.6. | |
847e0d88 | 255 | .PP |
94934ae7 MK |
256 | .BR CPU_AND (), |
257 | .BR CPU_OR (), | |
258 | .BR CPU_XOR (), | |
488d0e98 MK |
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 (), | |
94934ae7 | 270 | and |
488d0e98 | 271 | .BR CPU_EQUAL_S () |
94934ae7 | 272 | first appeared in glibc 2.7. |
47297adb | 273 | .SH CONFORMING TO |
a9cdb1db | 274 | These interfaces are Linux-specific. |
69241990 MK |
275 | .SH NOTES |
276 | To duplicate a CPU set, use | |
277 | .BR memcpy (3). | |
847e0d88 | 278 | .PP |
77227d36 | 279 | Since CPU sets are bit masks allocated in units of long words, |
69241990 MK |
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)" . | |
50ee5bc1 | 283 | An application should consider the contents of these extra bits |
69241990 | 284 | to be undefined. |
847e0d88 | 285 | .PP |
2fac1703 MK |
286 | Notwithstanding the similarity in the names, |
287 | note that the constant | |
69241990 | 288 | .B CPU_SETSIZE |
2fac1703 | 289 | indicates the number of CPUs in the |
69241990 | 290 | .I cpu_set_t |
77227d36 | 291 | data type (thus, it is effectively a count of the bits in the bit mask), |
69241990 MK |
292 | while the |
293 | .I setsize | |
294 | argument of the | |
295 | .BR CPU_*_S () | |
296 | macros is a size in bytes. | |
847e0d88 | 297 | .PP |
f4efb1e2 MK |
298 | The data types for arguments and return values shown |
299 | in the SYNOPSIS are hints what about is expected in each case. | |
de90951b | 300 | However, since these interfaces are implemented as macros, |
f4efb1e2 MK |
301 | the compiler won't necessarily catch all type errors |
302 | if you violate the suggestions. | |
22cb459d MK |
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 | |
488d0e98 MK |
315 | .SH EXAMPLE |
316 | The following program demonstrates the use of some of the macros | |
317 | used for dynamically allocated CPU sets. | |
847e0d88 | 318 | .PP |
207050fa | 319 | .EX |
488d0e98 MK |
320 | #define _GNU_SOURCE |
321 | #include <sched.h> | |
322 | #include <stdlib.h> | |
323 | #include <unistd.h> | |
324 | #include <stdio.h> | |
325 | #include <assert.h> | |
326 | ||
327 | int | |
328 | main(int argc, char *argv[]) | |
329 | { | |
330 | cpu_set_t *cpusetp; | |
331 | size_t size; | |
332 | int num_cpus, cpu; | |
333 | ||
334 | if (argc < 2) { | |
335 | fprintf(stderr, "Usage: %s <num\-cpus>\\n", argv[0]); | |
336 | exit(EXIT_FAILURE); | |
337 | } | |
338 | ||
339 | num_cpus = atoi(argv[1]); | |
340 | ||
341 | cpusetp = CPU_ALLOC(num_cpus); | |
342 | if (cpusetp == NULL) { | |
343 | perror("CPU_ALLOC"); | |
344 | exit(EXIT_FAILURE); | |
345 | } | |
346 | ||
347 | size = CPU_ALLOC_SIZE(num_cpus); | |
348 | ||
349 | CPU_ZERO_S(size, cpusetp); | |
350 | for (cpu = 0; cpu < num_cpus; cpu += 2) | |
351 | CPU_SET_S(cpu, size, cpusetp); | |
352 | ||
353 | printf("CPU_COUNT() of set: %d\\n", CPU_COUNT_S(size, cpusetp)); | |
354 | ||
355 | CPU_FREE(cpusetp); | |
356 | exit(EXIT_SUCCESS); | |
357 | } | |
207050fa | 358 | .EE |
47297adb | 359 | .SH SEE ALSO |
a9cdb1db | 360 | .BR sched_setaffinity (2), |
a9cdb1db MK |
361 | .BR pthread_attr_setaffinity_np (3), |
362 | .BR pthread_setaffinity_np (3), | |
363 | .BR cpuset (7) |