]>
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 | .\" | |
5fbde956 | 5 | .\" SPDX-License-Identifier: Linux-man-pages-copyleft |
a9cdb1db | 6 | .\" |
ab47278f | 7 | .TH CPU_SET 3 (date) "Linux man-pages (unreleased)" |
a9cdb1db | 8 | .SH NAME |
94934ae7 | 9 | CPU_SET, CPU_CLR, CPU_ISSET, CPU_ZERO, CPU_COUNT, |
a113945f | 10 | CPU_AND, CPU_OR, CPU_XOR, CPU_EQUAL, |
488d0e98 MK |
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 \- | |
a9cdb1db | 14 | macros for manipulating CPU sets |
b813014f AC |
15 | .SH LIBRARY |
16 | Standard C library | |
17 | .RI ( libc ", " \-lc ) | |
a9cdb1db MK |
18 | .SH SYNOPSIS |
19 | .nf | |
86b91fdf | 20 | .BR "#define _GNU_SOURCE" " /* See feature_test_macros(7) */" |
a9cdb1db | 21 | .B #include <sched.h> |
c6d039a3 | 22 | .P |
df79be82 | 23 | .BI "void CPU_ZERO(cpu_set_t *" set ); |
c6d039a3 | 24 | .P |
a9cdb1db | 25 | .BI "void CPU_SET(int " cpu ", cpu_set_t *" set ); |
df79be82 | 26 | .BI "void CPU_CLR(int " cpu ", cpu_set_t *" set ); |
df79be82 | 27 | .BI "int CPU_ISSET(int " cpu ", cpu_set_t *" set ); |
c6d039a3 | 28 | .P |
1b6ece46 | 29 | .BI "int CPU_COUNT(cpu_set_t *" set ); |
c6d039a3 | 30 | .P |
a113945f | 31 | .BI "void CPU_AND(cpu_set_t *" destset , |
94934ae7 | 32 | .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); |
a113945f | 33 | .BI "void CPU_OR(cpu_set_t *" destset , |
94934ae7 | 34 | .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); |
a113945f | 35 | .BI "void CPU_XOR(cpu_set_t *" destset , |
94934ae7 | 36 | .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); |
c6d039a3 | 37 | .P |
94934ae7 | 38 | .BI "int CPU_EQUAL(cpu_set_t *" set1 ", cpu_set_t *" set2 ); |
c6d039a3 | 39 | .P |
488d0e98 | 40 | .BI "cpu_set_t *CPU_ALLOC(int " num_cpus ); |
314c72c3 | 41 | .BI "void CPU_FREE(cpu_set_t *" set ); |
aa633a58 | 42 | .BI "size_t CPU_ALLOC_SIZE(int " num_cpus ); |
c6d039a3 | 43 | .P |
488d0e98 | 44 | .BI "void CPU_ZERO_S(size_t " setsize ", cpu_set_t *" set ); |
c6d039a3 | 45 | .P |
488d0e98 MK |
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 ); | |
c6d039a3 | 49 | .P |
1b6ece46 | 50 | .BI "int CPU_COUNT_S(size_t " setsize ", cpu_set_t *" set ); |
c6d039a3 | 51 | .P |
a113945f | 52 | .BI "void CPU_AND_S(size_t " setsize ", cpu_set_t *" destset , |
488d0e98 | 53 | .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); |
a113945f | 54 | .BI "void CPU_OR_S(size_t " setsize ", cpu_set_t *" destset , |
488d0e98 | 55 | .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); |
a113945f | 56 | .BI "void CPU_XOR_S(size_t " setsize ", cpu_set_t *" destset , |
488d0e98 | 57 | .BI " cpu_set_t *" srcset1 ", cpu_set_t *" srcset2 ); |
c6d039a3 | 58 | .P |
488d0e98 MK |
59 | .BI "int CPU_EQUAL_S(size_t " setsize ", cpu_set_t *" set1 \ |
60 | ", cpu_set_t *" set2 ); | |
a9cdb1db MK |
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. | |
c6d039a3 | 69 | .P |
69241990 MK |
70 | The |
71 | .I cpu_set_t | |
77227d36 | 72 | data type is implemented as a bit mask. |
60bcc5ab | 73 | However, the data structure should be treated as opaque: |
69241990 MK |
74 | all manipulation of CPU sets should be done via the macros |
75 | described in this page. | |
c6d039a3 | 76 | .P |
a9cdb1db MK |
77 | The following macros are provided to operate on the CPU set |
78 | .IR set : | |
0019177e | 79 | .TP |
a9cdb1db | 80 | .BR CPU_ZERO () |
94934ae7 MK |
81 | Clears |
82 | .IR set , | |
a9cdb1db MK |
83 | so that it contains no CPUs. |
84 | .TP | |
85 | .BR CPU_SET () | |
94934ae7 | 86 | Add CPU |
a9cdb1db MK |
87 | .I cpu |
88 | to | |
89 | .IR set . | |
90 | .TP | |
91 | .BR CPU_CLR () | |
94934ae7 | 92 | Remove CPU |
a9cdb1db MK |
93 | .I cpu |
94 | from | |
95 | .IR set . | |
96 | .TP | |
97 | .BR CPU_ISSET () | |
94934ae7 | 98 | Test to see if CPU |
a9cdb1db MK |
99 | .I cpu |
100 | is a member of | |
101 | .IR set . | |
639c5cc8 MK |
102 | .TP |
103 | .BR CPU_COUNT () | |
94934ae7 | 104 | Return the number of CPUs in |
639c5cc8 | 105 | .IR set . |
c6d039a3 | 106 | .P |
a9cdb1db MK |
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. | |
c6d039a3 | 111 | .P |
a6eb4055 | 112 | The first CPU on the system corresponds to a |
a9cdb1db MK |
113 | .I cpu |
114 | value of 0, the next CPU corresponds to a | |
115 | .I cpu | |
116 | value of 1, and so on. | |
a6eb4055 CM |
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. | |
a9cdb1db MK |
120 | The constant |
121 | .B CPU_SETSIZE | |
f7eec897 | 122 | (currently 1024) specifies a value one greater than the maximum CPU |
488d0e98 MK |
123 | number that can be stored in |
124 | .IR cpu_set_t . | |
c6d039a3 | 125 | .P |
488d0e98 | 126 | The following macros perform logical operations on CPU sets: |
0019177e | 127 | .TP |
94934ae7 | 128 | .BR CPU_AND () |
9ccbb26c | 129 | Store the intersection of the sets |
94934ae7 MK |
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 () | |
9ccbb26c | 138 | Store the union of the sets |
94934ae7 MK |
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 () | |
9ccbb26c | 147 | Store the XOR of the sets |
94934ae7 MK |
148 | .I srcset1 |
149 | and | |
150 | .I srcset2 | |
151 | in | |
152 | .I destset | |
153 | (which may be one of the source sets). | |
9ccbb26c MK |
154 | The XOR means the set of CPUs that are in either |
155 | .I srcset1 | |
156 | or | |
157 | .IR srcset2 , | |
158 | but not both. | |
94934ae7 MK |
159 | .TP |
160 | .BR CPU_EQUAL () | |
488d0e98 MK |
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. | |
c6d039a3 | 168 | .P |
488d0e98 | 169 | The following macros are used to allocate and deallocate CPU sets: |
0019177e | 170 | .TP |
488d0e98 MK |
171 | .BR CPU_ALLOC () |
172 | Allocate a CPU set large enough to hold CPUs | |
173 | in the range 0 to | |
cd415e73 | 174 | .IR num_cpus\-1 . |
488d0e98 MK |
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 | |
cd415e73 | 179 | .IR num_cpus\-1 . |
69241990 | 180 | This macro provides the value that can be used for the |
488d0e98 | 181 | .I setsize |
69241990 | 182 | argument in the |
488d0e98 MK |
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 (). | |
c6d039a3 | 189 | .P |
214c1dd2 | 190 | The macros whose names end with "_S" are the analogs of |
488d0e98 MK |
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. | |
47297adb | 196 | .SH RETURN VALUE |
a9cdb1db | 197 | .BR CPU_ISSET () |
488d0e98 MK |
198 | and |
199 | .BR CPU_ISSET_S () | |
c7094399 | 200 | return nonzero if |
a9cdb1db MK |
201 | .I cpu |
202 | is in | |
203 | .IR set ; | |
204 | otherwise, it returns 0. | |
c6d039a3 | 205 | .P |
639c5cc8 | 206 | .BR CPU_COUNT () |
488d0e98 MK |
207 | and |
208 | .BR CPU_COUNT_S () | |
209 | return the number of CPUs in | |
639c5cc8 | 210 | .IR set . |
c6d039a3 | 211 | .P |
94934ae7 | 212 | .BR CPU_EQUAL () |
488d0e98 MK |
213 | and |
214 | .BR CPU_EQUAL_S () | |
cf486e4a | 215 | return nonzero if the two CPU sets are equal; otherwise they return 0. |
c6d039a3 | 216 | .P |
488d0e98 MK |
217 | .BR CPU_ALLOC () |
218 | returns a pointer on success, or NULL on failure. | |
219 | (Errors are as for | |
220 | .BR malloc (3).) | |
c6d039a3 | 221 | .P |
488d0e98 MK |
222 | .BR CPU_ALLOC_SIZE () |
223 | returns the number of bytes required to store a | |
224 | CPU set of the specified cardinality. | |
c6d039a3 | 225 | .P |
a9cdb1db | 226 | The other functions do not return a value. |
4131356c AC |
227 | .SH STANDARDS |
228 | Linux. | |
229 | .SH HISTORY | |
a9cdb1db MK |
230 | The |
231 | .BR CPU_ZERO (), | |
a9cdb1db | 232 | .BR CPU_SET (), |
df79be82 | 233 | .BR CPU_CLR (), |
a9cdb1db MK |
234 | and |
235 | .BR CPU_ISSET () | |
236 | macros were added in glibc 2.3.3. | |
c6d039a3 | 237 | .P |
639c5cc8 MK |
238 | .BR CPU_COUNT () |
239 | first appeared in glibc 2.6. | |
c6d039a3 | 240 | .P |
94934ae7 MK |
241 | .BR CPU_AND (), |
242 | .BR CPU_OR (), | |
243 | .BR CPU_XOR (), | |
488d0e98 MK |
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 (), | |
94934ae7 | 255 | and |
488d0e98 | 256 | .BR CPU_EQUAL_S () |
94934ae7 | 257 | first appeared in glibc 2.7. |
69241990 MK |
258 | .SH NOTES |
259 | To duplicate a CPU set, use | |
260 | .BR memcpy (3). | |
c6d039a3 | 261 | .P |
77227d36 | 262 | Since CPU sets are bit masks allocated in units of long words, |
69241990 MK |
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)" . | |
50ee5bc1 | 266 | An application should consider the contents of these extra bits |
69241990 | 267 | to be undefined. |
c6d039a3 | 268 | .P |
2fac1703 MK |
269 | Notwithstanding the similarity in the names, |
270 | note that the constant | |
69241990 | 271 | .B CPU_SETSIZE |
2fac1703 | 272 | indicates the number of CPUs in the |
69241990 | 273 | .I cpu_set_t |
77227d36 | 274 | data type (thus, it is effectively a count of the bits in the bit mask), |
69241990 MK |
275 | while the |
276 | .I setsize | |
277 | argument of the | |
278 | .BR CPU_*_S () | |
279 | macros is a size in bytes. | |
c6d039a3 | 280 | .P |
f4efb1e2 MK |
281 | The data types for arguments and return values shown |
282 | in the SYNOPSIS are hints what about is expected in each case. | |
de90951b | 283 | However, since these interfaces are implemented as macros, |
f4efb1e2 MK |
284 | the compiler won't necessarily catch all type errors |
285 | if you violate the suggestions. | |
22cb459d MK |
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 | |
a14af333 | 298 | .SH EXAMPLES |
488d0e98 MK |
299 | The following program demonstrates the use of some of the macros |
300 | used for dynamically allocated CPU sets. | |
c6d039a3 | 301 | .P |
b0b6ab4e | 302 | .\" SRC BEGIN (CPU_SET.c) |
207050fa | 303 | .EX |
488d0e98 MK |
304 | #define _GNU_SOURCE |
305 | #include <sched.h> | |
ad3868f0 | 306 | #include <stdio.h> |
488d0e98 MK |
307 | #include <stdlib.h> |
308 | #include <unistd.h> | |
fe5dba13 | 309 | \& |
488d0e98 | 310 | #include <assert.h> |
fe5dba13 | 311 | \& |
488d0e98 MK |
312 | int |
313 | main(int argc, char *argv[]) | |
314 | { | |
315 | cpu_set_t *cpusetp; | |
b42296e4 | 316 | size_t size, num_cpus; |
fe5dba13 | 317 | \& |
488d0e98 | 318 | if (argc < 2) { |
d1a71985 | 319 | fprintf(stderr, "Usage: %s <num\-cpus>\en", argv[0]); |
488d0e98 MK |
320 | exit(EXIT_FAILURE); |
321 | } | |
fe5dba13 | 322 | \& |
488d0e98 | 323 | num_cpus = atoi(argv[1]); |
fe5dba13 | 324 | \& |
488d0e98 MK |
325 | cpusetp = CPU_ALLOC(num_cpus); |
326 | if (cpusetp == NULL) { | |
327 | perror("CPU_ALLOC"); | |
328 | exit(EXIT_FAILURE); | |
329 | } | |
fe5dba13 | 330 | \& |
488d0e98 | 331 | size = CPU_ALLOC_SIZE(num_cpus); |
fe5dba13 | 332 | \& |
488d0e98 | 333 | CPU_ZERO_S(size, cpusetp); |
b42296e4 | 334 | for (size_t cpu = 0; cpu < num_cpus; cpu += 2) |
488d0e98 | 335 | CPU_SET_S(cpu, size, cpusetp); |
fe5dba13 | 336 | \& |
d1a71985 | 337 | printf("CPU_COUNT() of set: %d\en", CPU_COUNT_S(size, cpusetp)); |
fe5dba13 | 338 | \& |
488d0e98 MK |
339 | CPU_FREE(cpusetp); |
340 | exit(EXIT_SUCCESS); | |
341 | } | |
207050fa | 342 | .EE |
b0b6ab4e | 343 | .\" SRC END |
47297adb | 344 | .SH SEE ALSO |
a9cdb1db | 345 | .BR sched_setaffinity (2), |
a9cdb1db MK |
346 | .BR pthread_attr_setaffinity_np (3), |
347 | .BR pthread_setaffinity_np (3), | |
348 | .BR cpuset (7) |