Debian Codegraph @

doc/doxygen-doc/man/man3/hwlocality_bitmap.3

raw
1 .TH "hwlocality_bitmap" 3 "Version 2.14.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
2 .ad l
3 .nh
4 .SH NAME
5 hwlocality_bitmap \- The bitmap API
6 .SH SYNOPSIS
7 .br
8 .PP
9 .SS "Macros"
10
11 .in +1c
12 .ti -1c
13 .RI "#define \fBhwloc_bitmap_foreach_begin\fP(id, bitmap)"
14 .br
15 .ti -1c
16 .RI "#define \fBhwloc_bitmap_foreach_end\fP()"
17 .br
18 .in -1c
19 .SS "Typedefs"
20
21 .in +1c
22 .ti -1c
23 .RI "typedef struct hwloc_bitmap_s * \fBhwloc_bitmap_t\fP"
24 .br
25 .ti -1c
26 .RI "typedef const struct hwloc_bitmap_s * \fBhwloc_const_bitmap_t\fP"
27 .br
28 .in -1c
29 .SS "Functions"
30
31 .in +1c
32 .ti -1c
33 .RI "\fBhwloc_bitmap_t\fP \fBhwloc_bitmap_alloc\fP (void)"
34 .br
35 .ti -1c
36 .RI "\fBhwloc_bitmap_t\fP \fBhwloc_bitmap_alloc_full\fP (void)"
37 .br
38 .ti -1c
39 .RI "void \fBhwloc_bitmap_free\fP (\fBhwloc_bitmap_t\fP bitmap)"
40 .br
41 .ti -1c
42 .RI "\fBhwloc_bitmap_t\fP \fBhwloc_bitmap_dup\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
43 .br
44 .ti -1c
45 .RI "int \fBhwloc_bitmap_copy\fP (\fBhwloc_bitmap_t\fP dst, \fBhwloc_const_bitmap_t\fP src)"
46 .br
47 .ti -1c
48 .RI "int \fBhwloc_bitmap_snprintf\fP (char *restrict buf, size_t buflen, \fBhwloc_const_bitmap_t\fP bitmap)"
49 .br
50 .ti -1c
51 .RI "int \fBhwloc_bitmap_asprintf\fP (char **strp, \fBhwloc_const_bitmap_t\fP bitmap)"
52 .br
53 .ti -1c
54 .RI "int \fBhwloc_bitmap_sscanf\fP (\fBhwloc_bitmap_t\fP bitmap, const char *restrict string)"
55 .br
56 .ti -1c
57 .RI "int \fBhwloc_bitmap_list_snprintf\fP (char *restrict buf, size_t buflen, \fBhwloc_const_bitmap_t\fP bitmap)"
58 .br
59 .ti -1c
60 .RI "int \fBhwloc_bitmap_list_asprintf\fP (char **strp, \fBhwloc_const_bitmap_t\fP bitmap)"
61 .br
62 .ti -1c
63 .RI "int \fBhwloc_bitmap_list_sscanf\fP (\fBhwloc_bitmap_t\fP bitmap, const char *restrict string)"
64 .br
65 .ti -1c
66 .RI "int \fBhwloc_bitmap_taskset_snprintf\fP (char *restrict buf, size_t buflen, \fBhwloc_const_bitmap_t\fP bitmap)"
67 .br
68 .ti -1c
69 .RI "int \fBhwloc_bitmap_taskset_asprintf\fP (char **strp, \fBhwloc_const_bitmap_t\fP bitmap)"
70 .br
71 .ti -1c
72 .RI "int \fBhwloc_bitmap_taskset_sscanf\fP (\fBhwloc_bitmap_t\fP bitmap, const char *restrict string)"
73 .br
74 .ti -1c
75 .RI "void \fBhwloc_bitmap_zero\fP (\fBhwloc_bitmap_t\fP bitmap)"
76 .br
77 .ti -1c
78 .RI "void \fBhwloc_bitmap_fill\fP (\fBhwloc_bitmap_t\fP bitmap)"
79 .br
80 .ti -1c
81 .RI "int \fBhwloc_bitmap_only\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
82 .br
83 .ti -1c
84 .RI "int \fBhwloc_bitmap_allbut\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
85 .br
86 .ti -1c
87 .RI "int \fBhwloc_bitmap_from_ulong\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned long mask)"
88 .br
89 .ti -1c
90 .RI "int \fBhwloc_bitmap_from_ith_ulong\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned i, unsigned long mask)"
91 .br
92 .ti -1c
93 .RI "int \fBhwloc_bitmap_from_ulongs\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned nr, const unsigned long *masks)"
94 .br
95 .ti -1c
96 .RI "int \fBhwloc_bitmap_set\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
97 .br
98 .ti -1c
99 .RI "int \fBhwloc_bitmap_set_range\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned begin, int end)"
100 .br
101 .ti -1c
102 .RI "int \fBhwloc_bitmap_set_ith_ulong\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned i, unsigned long mask)"
103 .br
104 .ti -1c
105 .RI "int \fBhwloc_bitmap_clr\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
106 .br
107 .ti -1c
108 .RI "int \fBhwloc_bitmap_clr_range\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned begin, int end)"
109 .br
110 .ti -1c
111 .RI "int \fBhwloc_bitmap_singlify\fP (\fBhwloc_bitmap_t\fP bitmap)"
112 .br
113 .ti -1c
114 .RI "unsigned long \fBhwloc_bitmap_to_ulong\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
115 .br
116 .ti -1c
117 .RI "unsigned long \fBhwloc_bitmap_to_ith_ulong\fP (\fBhwloc_const_bitmap_t\fP bitmap, unsigned i)"
118 .br
119 .ti -1c
120 .RI "int \fBhwloc_bitmap_to_ulongs\fP (\fBhwloc_const_bitmap_t\fP bitmap, unsigned nr, unsigned long *masks)"
121 .br
122 .ti -1c
123 .RI "int \fBhwloc_bitmap_nr_ulongs\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
124 .br
125 .ti -1c
126 .RI "int \fBhwloc_bitmap_isset\fP (\fBhwloc_const_bitmap_t\fP bitmap, unsigned id)"
127 .br
128 .ti -1c
129 .RI "int \fBhwloc_bitmap_iszero\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
130 .br
131 .ti -1c
132 .RI "int \fBhwloc_bitmap_isfull\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
133 .br
134 .ti -1c
135 .RI "int \fBhwloc_bitmap_first\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
136 .br
137 .ti -1c
138 .RI "int \fBhwloc_bitmap_next\fP (\fBhwloc_const_bitmap_t\fP bitmap, int prev)"
139 .br
140 .ti -1c
141 .RI "int \fBhwloc_bitmap_last\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
142 .br
143 .ti -1c
144 .RI "int \fBhwloc_bitmap_weight\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
145 .br
146 .ti -1c
147 .RI "int \fBhwloc_bitmap_first_unset\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
148 .br
149 .ti -1c
150 .RI "int \fBhwloc_bitmap_next_unset\fP (\fBhwloc_const_bitmap_t\fP bitmap, int prev)"
151 .br
152 .ti -1c
153 .RI "int \fBhwloc_bitmap_last_unset\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
154 .br
155 .ti -1c
156 .RI "int \fBhwloc_bitmap_or\fP (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
157 .br
158 .ti -1c
159 .RI "int \fBhwloc_bitmap_and\fP (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
160 .br
161 .ti -1c
162 .RI "int \fBhwloc_bitmap_andnot\fP (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
163 .br
164 .ti -1c
165 .RI "int \fBhwloc_bitmap_xor\fP (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
166 .br
167 .ti -1c
168 .RI "int \fBhwloc_bitmap_not\fP (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap)"
169 .br
170 .ti -1c
171 .RI "int \fBhwloc_bitmap_intersects\fP (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
172 .br
173 .ti -1c
174 .RI "int \fBhwloc_bitmap_isincluded\fP (\fBhwloc_const_bitmap_t\fP sub_bitmap, \fBhwloc_const_bitmap_t\fP super_bitmap)"
175 .br
176 .ti -1c
177 .RI "int \fBhwloc_bitmap_isequal\fP (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
178 .br
179 .ti -1c
180 .RI "int \fBhwloc_bitmap_compare_first\fP (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
181 .br
182 .ti -1c
183 .RI "int \fBhwloc_bitmap_compare\fP (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
184 .br
185 .in -1c
186 .SH "Detailed Description"
187 .PP
188 The \fBhwloc_bitmap_t\fP type represents a set of integers (positive or null)\&. A bitmap may be of infinite size (all bits are set after some point)\&. A bitmap may even be full if all bits are set\&.
189
190 .PP
191 Bitmaps are used by hwloc for sets of OS processors (which may actually be hardware threads) as by \fBhwloc_cpuset_t\fP (a typedef for \fBhwloc_bitmap_t\fP), or sets of NUMA memory nodes as \fBhwloc_nodeset_t\fP (also a typedef for \fBhwloc_bitmap_t\fP)\&. Those are used for cpuset and nodeset fields in the \fBhwloc_obj\fP structure, see \fBObject Sets (hwloc_cpuset_t and hwloc_nodeset_t)\fP\&.
192
193 .PP
194 \fIBoth CPU and node sets are always indexed by OS physical number\&.\fP However users should usually not build CPU and node sets manually (e\&.g\&. with \fBhwloc_bitmap_set()\fP)\&. One should rather use existing object sets and combine them with \fBhwloc_bitmap_or()\fP, etc\&. For instance, binding the current thread on a pair of cores may be performed with:
195 .PP
196 .nf
197 hwloc_obj_t core1 = \&.\&.\&. , core2 = \&.\&.\&. ;
198 hwloc_bitmap_t set = hwloc_bitmap_alloc();
199 hwloc_bitmap_or(set, core1\->cpuset, core2\->cpuset);
200 hwloc_set_cpubind(topology, set, HWLOC_CPUBIND_THREAD);
201 hwloc_bitmap_free(set);
202
203 .fi
204 .PP
205
206 .PP
207 \fBNote\fP
208 .RS 4
209 Most functions below return 0 on success and -1 on error\&. The usual error case would be an internal failure to realloc/extend the storage of the bitmap (\fRerrno\fP would be set to \fRENOMEM\fP)\&. See also \fBError reporting in the API\fP\&.
210
211 .PP
212 Several examples of using the bitmap API are available under the doc/examples/ directory in the source tree\&. Regression tests such as tests/hwloc/hwloc_bitmap*\&.c also make intensive use of this API\&.
213 .RE
214 .PP
215
216 .SH "Macro Definition Documentation"
217 .PP
218 .SS "#define hwloc_bitmap_foreach_begin( id, bitmap)"
219
220 .PP
221 Loop macro iterating on bitmap \fRbitmap\fP\&. The loop must start with \fBhwloc_bitmap_foreach_begin()\fP and end with \fBhwloc_bitmap_foreach_end()\fP followed by a terminating ';'\&.
222
223 .PP
224 \fRid\fP is the loop variable; it should be an unsigned int\&. The first iteration will set \fRid\fP to the lowest index in the bitmap\&. Successive iterations will iterate through, in order, all remaining indexes set in the bitmap\&. To be specific: each iteration will return a value for \fRid\fP such that hwloc_bitmap_isset(bitmap, id) is true\&.
225
226 .PP
227 The assert prevents the loop from being infinite if the bitmap is infinitely set\&.
228 .SS "#define hwloc_bitmap_foreach_end()"
229
230 .PP
231 End of loop macro iterating on a bitmap\&. Needs a terminating ';'\&.
232
233 .PP
234 \fBSee also\fP
235 .RS 4
236 \fBhwloc_bitmap_foreach_begin()\fP
237 .RE
238 .PP
239
240 .SH "Typedef Documentation"
241 .PP
242 .SS "typedef struct hwloc_bitmap_s* \fBhwloc_bitmap_t\fP"
243
244 .PP
245 Set of bits represented as an opaque pointer to an internal bitmap\&.
246 .SS "typedef const struct hwloc_bitmap_s* \fBhwloc_const_bitmap_t\fP"
247
248 .PP
249 a non-modifiable \fBhwloc_bitmap_t\fP
250 .SH "Function Documentation"
251 .PP
252 .SS "int hwloc_bitmap_allbut (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
253
254 .PP
255 Fill the bitmap \fRand\fP clear the index \fRid\fP\&.
256 .SS "\fBhwloc_bitmap_t\fP hwloc_bitmap_alloc (void )"
257
258 .PP
259 Allocate a new empty bitmap\&.
260 .PP
261 \fBReturns\fP
262 .RS 4
263 A valid bitmap or \fRNULL\fP\&.
264 .RE
265 .PP
266 The bitmap should be freed by a corresponding call to \fBhwloc_bitmap_free()\fP\&.
267 .SS "\fBhwloc_bitmap_t\fP hwloc_bitmap_alloc_full (void )"
268
269 .PP
270 Allocate a new full bitmap\&.
271 .PP
272 \fBReturns\fP
273 .RS 4
274 A valid bitmap or \fRNULL\fP\&.
275 .RE
276 .PP
277 The bitmap should be freed by a corresponding call to \fBhwloc_bitmap_free()\fP\&.
278 .SS "int hwloc_bitmap_and (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
279
280 .PP
281 And bitmaps \fRbitmap1\fP and \fRbitmap2\fP and store the result in bitmap \fRres\fP\&. \fRres\fP can be the same as \fRbitmap1\fP or \fRbitmap2\fP
282 .SS "int hwloc_bitmap_andnot (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
283
284 .PP
285 And bitmap \fRbitmap1\fP and the negation of \fRbitmap2\fP and store the result in bitmap \fRres\fP\&. \fRres\fP can be the same as \fRbitmap1\fP or \fRbitmap2\fP
286 .SS "int hwloc_bitmap_asprintf (char ** strp, \fBhwloc_const_bitmap_t\fP bitmap)"
287
288 .PP
289 Stringify a bitmap into a newly allocated string in the default hwloc format\&. Print the bits set inside a bitmap as a comma-separated list of hexadecimal 32-bit blocks\&. A bitmap containing bits 1, 33, 34, and all from 64 to 95 is printed as \fR"0xffffffff,0x00000006,0x00000002"\fP\&.
290
291 .PP
292 \fBReturns\fP
293 .RS 4
294 the number of characters that were written (not including the ending \fR\\0\fP)\&.
295
296 .PP
297 -1 on error, for instance with \fRerrno\fP set to \fRENOMEM\fP on failure to allocate the output string\&.
298 .RE
299 .PP
300 \fBNote\fP
301 .RS 4
302 \fBIf the bitmap is a CPU or nodeset, it contains physical indexes\&.\fP This should be clearly indicated when displaying such bitmaps to end users\&. See also \fBHow do I convert between logical and OS/physical indexes?\fP
303 .RE
304 .PP
305
306 .SS "int hwloc_bitmap_clr (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
307
308 .PP
309 Remove index \fRid\fP from bitmap \fRbitmap\fP\&.
310 .SS "int hwloc_bitmap_clr_range (\fBhwloc_bitmap_t\fP bitmap, unsigned begin, int end)"
311
312 .PP
313 Remove indexes from \fRbegin\fP to \fRend\fP in bitmap \fRbitmap\fP\&. If \fRend\fP is \fR-1\fP, the range is infinite\&.
314 .SS "int hwloc_bitmap_compare (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
315
316 .PP
317 Compare bitmaps \fRbitmap1\fP and \fRbitmap2\fP in lexicographic order\&. Lexicographic comparison of bitmaps, starting for their highest indexes\&. Compare last indexes first, then second, etc\&. The empty bitmap is considered lower than anything\&.
318
319 .PP
320 \fBReturns\fP
321 .RS 4
322 -1 if \fRbitmap1\fP is considered smaller than \fRbitmap2\fP\&.
323
324 .PP
325 1 if \fRbitmap1\fP is considered larger than \fRbitmap2\fP\&.
326
327 .PP
328 0 if bitmaps are equal (contrary to \fBhwloc_bitmap_compare_first()\fP)\&.
329 .RE
330 .PP
331 For instance comparing binary bitmaps 0011 and 0110 returns -1 (hence 0011 is considered smaller than 0110)\&. Comparing 00101 and 01010 returns -1 too\&.
332
333 .PP
334 \fBNote\fP
335 .RS 4
336 This is different from the non-existing hwloc_bitmap_compare_last() which would only compare the highest index of each bitmap\&.
337 .RE
338 .PP
339
340 .SS "int hwloc_bitmap_compare_first (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
341
342 .PP
343 Compare bitmaps \fRbitmap1\fP and \fRbitmap2\fP using their lowest index\&. A bitmap is considered smaller if its least significant bit is smaller\&. The empty bitmap is considered higher than anything (because its least significant bit does not exist)\&.
344
345 .PP
346 \fBReturns\fP
347 .RS 4
348 -1 if \fRbitmap1\fP is considered smaller than \fRbitmap2\fP\&.
349
350 .PP
351 1 if \fRbitmap1\fP is considered larger than \fRbitmap2\fP\&.
352 .RE
353 .PP
354 For instance comparing binary bitmaps 0011 and 0110 returns -1 (hence 0011 is considered smaller than 0110) because least significant bit of 0011 (0001) is smaller than least significant bit of 0110 (0010)\&. Comparing 01001 and 00110 would also return -1 for the same reason\&.
355
356 .PP
357 \fBReturns\fP
358 .RS 4
359 0 if bitmaps are considered equal, even if they are not strictly equal\&. They just need to have the same least significant bit\&. For instance, comparing binary bitmaps 0010 and 0110 returns 0 because they have the same least significant bit\&.
360 .RE
361 .PP
362
363 .SS "int hwloc_bitmap_copy (\fBhwloc_bitmap_t\fP dst, \fBhwloc_const_bitmap_t\fP src)"
364
365 .PP
366 Copy the contents of bitmap \fRsrc\fP into the already allocated bitmap \fRdst\fP\&.
367 .SS "\fBhwloc_bitmap_t\fP hwloc_bitmap_dup (\fBhwloc_const_bitmap_t\fP bitmap)"
368
369 .PP
370 Duplicate bitmap \fRbitmap\fP by allocating a new bitmap and copying \fRbitmap\fP contents\&. If \fRbitmap\fP is \fRNULL\fP, \fRNULL\fP is returned\&.
371 .SS "void hwloc_bitmap_fill (\fBhwloc_bitmap_t\fP bitmap)"
372
373 .PP
374 Fill bitmap \fRbitmap\fP with all possible indexes (even if those objects don't exist or are otherwise unavailable)\&.
375 .SS "int hwloc_bitmap_first (\fBhwloc_const_bitmap_t\fP bitmap)"
376
377 .PP
378 Compute the first index (least significant bit) in bitmap \fRbitmap\fP\&.
379 .PP
380 \fBReturns\fP
381 .RS 4
382 the first index set in \fRbitmap\fP\&.
383
384 .PP
385 -1 if \fRbitmap\fP is empty\&.
386 .RE
387 .PP
388
389 .SS "int hwloc_bitmap_first_unset (\fBhwloc_const_bitmap_t\fP bitmap)"
390
391 .PP
392 Compute the first unset index (least significant bit) in bitmap \fRbitmap\fP\&.
393 .PP
394 \fBReturns\fP
395 .RS 4
396 the first unset index in \fRbitmap\fP\&.
397
398 .PP
399 -1 if \fRbitmap\fP is full\&.
400 .RE
401 .PP
402
403 .SS "void hwloc_bitmap_free (\fBhwloc_bitmap_t\fP bitmap)"
404
405 .PP
406 Free bitmap \fRbitmap\fP\&. If \fRbitmap\fP is \fRNULL\fP, no operation is performed\&.
407 .SS "int hwloc_bitmap_from_ith_ulong (\fBhwloc_bitmap_t\fP bitmap, unsigned i, unsigned long mask)"
408
409 .PP
410 Setup bitmap \fRbitmap\fP from unsigned long \fRmask\fP used as \fRi\fP -th subset\&.
411 .SS "int hwloc_bitmap_from_ulong (\fBhwloc_bitmap_t\fP bitmap, unsigned long mask)"
412
413 .PP
414 Setup bitmap \fRbitmap\fP from unsigned long \fRmask\fP\&.
415 .SS "int hwloc_bitmap_from_ulongs (\fBhwloc_bitmap_t\fP bitmap, unsigned nr, const unsigned long * masks)"
416
417 .PP
418 Setup bitmap \fRbitmap\fP from unsigned longs \fRmasks\fP used as first \fRnr\fP subsets\&.
419 .SS "int hwloc_bitmap_intersects (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
420
421 .PP
422 Test whether bitmaps \fRbitmap1\fP and \fRbitmap2\fP intersects\&.
423 .PP
424 \fBReturns\fP
425 .RS 4
426 1 if bitmaps intersect, 0 otherwise\&.
427 .RE
428 .PP
429 \fBNote\fP
430 .RS 4
431 The empty bitmap does not intersect any other bitmap\&.
432 .RE
433 .PP
434
435 .SS "int hwloc_bitmap_isequal (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
436
437 .PP
438 Test whether bitmap \fRbitmap1\fP is equal to bitmap \fRbitmap2\fP\&.
439 .PP
440 \fBReturns\fP
441 .RS 4
442 1 if bitmaps are equal, 0 otherwise\&.
443 .RE
444 .PP
445
446 .SS "int hwloc_bitmap_isfull (\fBhwloc_const_bitmap_t\fP bitmap)"
447
448 .PP
449 Test whether bitmap \fRbitmap\fP is completely full\&.
450 .PP
451 \fBReturns\fP
452 .RS 4
453 1 if bitmap is full, 0 otherwise\&.
454 .RE
455 .PP
456 \fBNote\fP
457 .RS 4
458 A full bitmap is always infinitely set\&.
459 .RE
460 .PP
461
462 .SS "int hwloc_bitmap_isincluded (\fBhwloc_const_bitmap_t\fP sub_bitmap, \fBhwloc_const_bitmap_t\fP super_bitmap)"
463
464 .PP
465 Test whether bitmap \fRsub_bitmap\fP is part of bitmap \fRsuper_bitmap\fP\&.
466 .PP
467 \fBReturns\fP
468 .RS 4
469 1 if \fRsub_bitmap\fP is included in \fRsuper_bitmap\fP, 0 otherwise\&.
470 .RE
471 .PP
472 \fBNote\fP
473 .RS 4
474 The empty bitmap is considered included in any other bitmap\&.
475 .RE
476 .PP
477
478 .SS "int hwloc_bitmap_isset (\fBhwloc_const_bitmap_t\fP bitmap, unsigned id)"
479
480 .PP
481 Test whether index \fRid\fP is part of bitmap \fRbitmap\fP\&.
482 .PP
483 \fBReturns\fP
484 .RS 4
485 1 if the bit at index \fRid\fP is set in bitmap \fRbitmap\fP, 0 otherwise\&.
486 .RE
487 .PP
488
489 .SS "int hwloc_bitmap_iszero (\fBhwloc_const_bitmap_t\fP bitmap)"
490
491 .PP
492 Test whether bitmap \fRbitmap\fP is empty\&.
493 .PP
494 \fBReturns\fP
495 .RS 4
496 1 if bitmap is empty, 0 otherwise\&.
497 .RE
498 .PP
499
500 .SS "int hwloc_bitmap_last (\fBhwloc_const_bitmap_t\fP bitmap)"
501
502 .PP
503 Compute the last index (most significant bit) in bitmap \fRbitmap\fP\&.
504 .PP
505 \fBReturns\fP
506 .RS 4
507 the last index set in \fRbitmap\fP\&.
508
509 .PP
510 -1 if \fRbitmap\fP is empty, or if \fRbitmap\fP is infinitely set\&.
511 .RE
512 .PP
513
514 .SS "int hwloc_bitmap_last_unset (\fBhwloc_const_bitmap_t\fP bitmap)"
515
516 .PP
517 Compute the last unset index (most significant bit) in bitmap \fRbitmap\fP\&.
518 .PP
519 \fBReturns\fP
520 .RS 4
521 the last index unset in \fRbitmap\fP\&.
522
523 .PP
524 -1 if \fRbitmap\fP is full, or if \fRbitmap\fP is not infinitely set\&.
525 .RE
526 .PP
527
528 .SS "int hwloc_bitmap_list_asprintf (char ** strp, \fBhwloc_const_bitmap_t\fP bitmap)"
529
530 .PP
531 Stringify a bitmap into a newly allocated list string\&. Lists are comma-separated indexes or ranges\&. Ranges are dash separated indexes\&. A bitmap containing bits 1, 33, 34, and all from 64 to 95 is printed as \fR"1,33-34,64-95"\fP\&. The last range may not have an ending index if the bitmap is infinitely set\&.
532
533 .PP
534 \fBReturns\fP
535 .RS 4
536 the number of characters that were written (not including the ending \fR\\0\fP)\&.
537
538 .PP
539 -1 on error, for instance with \fRerrno\fP set to \fRENOMEM\fP on failure to allocate the output string\&.
540 .RE
541 .PP
542 \fBNote\fP
543 .RS 4
544 \fBIf the bitmap is a CPU or nodeset, it contains physical indexes\&.\fP This should be clearly indicated when displaying such bitmaps to end users\&. See also \fBHow do I convert between logical and OS/physical indexes?\fP
545 .RE
546 .PP
547
548 .SS "int hwloc_bitmap_list_snprintf (char *restrict buf, size_t buflen, \fBhwloc_const_bitmap_t\fP bitmap)"
549
550 .PP
551 Stringify a bitmap in the list format\&. Lists are comma-separated indexes or ranges\&. Ranges are dash separated indexes\&. A bitmap containing bits 1, 33, 34, and all from 64 to 95 is printed as \fR"1,33-34,64-95"\fP\&. The last range may not have an ending index if the bitmap is infinitely set\&.
552
553 .PP
554 Up to \fRbuflen\fP characters may be written in buffer \fRbuf\fP\&.
555
556 .PP
557 If \fRbuflen\fP is 0, \fRbuf\fP may safely be \fRNULL\fP\&.
558
559 .PP
560 \fBReturns\fP
561 .RS 4
562 the number of characters that were actually written if not truncating, or that would have been written (not including the ending \fR\\0\fP)\&.
563
564 .PP
565 -1 on error\&.
566 .RE
567 .PP
568 \fBNote\fP
569 .RS 4
570 \fBIf the bitmap is a CPU or nodeset, it contains physical indexes\&.\fP This should be clearly indicated when displaying such bitmaps to end users\&. See also \fBHow do I convert between logical and OS/physical indexes?\fP
571 .RE
572 .PP
573
574 .SS "int hwloc_bitmap_list_sscanf (\fBhwloc_bitmap_t\fP bitmap, const char *restrict string)"
575
576 .PP
577 Parse a list string and stores it in bitmap \fRbitmap\fP\&. Lists are comma-separated indexes or ranges\&. Ranges are dash separated indexes\&. String \fR"1,33-34,64-95"\fP is parsed as a bitmap containing bits 1, 33, 34, and all from 64 to 95\&. The last range may not have an ending index if the bitmap is infinitely set\&.
578
579 .PP
580 \fBReturns\fP
581 .RS 4
582 0 on success, -1 on error\&.
583 .RE
584 .PP
585 \fBNote\fP
586 .RS 4
587 \fBIf the bitmap is a CPU or nodeset, the input string must contain physical indexes\&.\fP
588 .RE
589 .PP
590
591 .SS "int hwloc_bitmap_next (\fBhwloc_const_bitmap_t\fP bitmap, int prev)"
592
593 .PP
594 Compute the next index in bitmap \fRbitmap\fP which is after index \fRprev\fP\&.
595 .PP
596 \fBReturns\fP
597 .RS 4
598 the first index set in \fRbitmap\fP if \fRprev\fP is \fR-1\fP\&.
599
600 .PP
601 the next index set in \fRbitmap\fP if \fRprev\fP is not \fR-1\fP\&.
602
603 .PP
604 -1 if no index with higher index is set in \fRbitmap\fP\&.
605 .RE
606 .PP
607
608 .SS "int hwloc_bitmap_next_unset (\fBhwloc_const_bitmap_t\fP bitmap, int prev)"
609
610 .PP
611 Compute the next unset index in bitmap \fRbitmap\fP which is after index \fRprev\fP\&.
612 .PP
613 \fBReturns\fP
614 .RS 4
615 the first index unset in \fRbitmap\fP if \fRprev\fP is \fR-1\fP\&.
616
617 .PP
618 the next index unset in \fRbitmap\fP if \fRprev\fP is not \fR-1\fP\&.
619
620 .PP
621 -1 if no index with higher index is unset in \fRbitmap\fP\&.
622 .RE
623 .PP
624
625 .SS "int hwloc_bitmap_not (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap)"
626
627 .PP
628 Negate bitmap \fRbitmap\fP and store the result in bitmap \fRres\fP\&. \fRres\fP can be the same as \fRbitmap\fP
629 .SS "int hwloc_bitmap_nr_ulongs (\fBhwloc_const_bitmap_t\fP bitmap)"
630
631 .PP
632 Return the number of unsigned longs required for storing bitmap \fRbitmap\fP entirely\&. This is the number of contiguous unsigned longs from the very first bit of the bitmap (even if unset) up to the last set bit\&. This is useful for knowing the \fRnr\fP parameter to pass to \fBhwloc_bitmap_to_ulongs()\fP (or which calls to \fBhwloc_bitmap_to_ith_ulong()\fP are needed) to entirely convert a bitmap into multiple unsigned longs\&.
633
634 .PP
635 When called on the output of \fBhwloc_topology_get_topology_cpuset()\fP, the returned number is large enough for all cpusets of the topology\&.
636
637 .PP
638 \fBReturns\fP
639 .RS 4
640 the number of unsigned longs required\&.
641
642 .PP
643 -1 if \fRbitmap\fP is infinite\&.
644 .RE
645 .PP
646
647 .SS "int hwloc_bitmap_only (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
648
649 .PP
650 Empty the bitmap \fRbitmap\fP and add bit \fRid\fP\&.
651 .SS "int hwloc_bitmap_or (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
652
653 .PP
654 Or bitmaps \fRbitmap1\fP and \fRbitmap2\fP and store the result in bitmap \fRres\fP\&. \fRres\fP can be the same as \fRbitmap1\fP or \fRbitmap2\fP
655 .SS "int hwloc_bitmap_set (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
656
657 .PP
658 Add index \fRid\fP in bitmap \fRbitmap\fP\&.
659 .SS "int hwloc_bitmap_set_ith_ulong (\fBhwloc_bitmap_t\fP bitmap, unsigned i, unsigned long mask)"
660
661 .PP
662 Replace \fRi\fP -th subset of bitmap \fRbitmap\fP with unsigned long \fRmask\fP\&.
663 .SS "int hwloc_bitmap_set_range (\fBhwloc_bitmap_t\fP bitmap, unsigned begin, int end)"
664
665 .PP
666 Add indexes from \fRbegin\fP to \fRend\fP in bitmap \fRbitmap\fP\&. If \fRend\fP is \fR-1\fP, the range is infinite\&.
667 .SS "int hwloc_bitmap_singlify (\fBhwloc_bitmap_t\fP bitmap)"
668
669 .PP
670 Keep a single index among those set in bitmap \fRbitmap\fP\&. May be useful before binding so that the process does not have a chance of migrating between multiple processors in the original mask\&. Instead of running the task on any PU inside the given CPU set, the operating system scheduler will be forced to run it on a single of these PUs\&. It avoids a migration overhead and cache-line ping-pongs between PUs\&.
671
672 .PP
673 \fBNote\fP
674 .RS 4
675 This function is NOT meant to distribute multiple processes within a single CPU set\&. It always return the same single bit when called multiple times on the same input set\&. \fBhwloc_distrib()\fP may be used for generating CPU sets to distribute multiple tasks below a single multi-PU object\&.
676
677 .PP
678 This function cannot be applied to an object set directly\&. It should be applied to a copy (which may be obtained with \fBhwloc_bitmap_dup()\fP)\&.
679 .RE
680 .PP
681
682 .SS "int hwloc_bitmap_snprintf (char *restrict buf, size_t buflen, \fBhwloc_const_bitmap_t\fP bitmap)"
683
684 .PP
685 Stringify a bitmap in the default hwloc format\&. Print the bits set inside a bitmap as a comma-separated list of hexadecimal 32-bit blocks\&. A bitmap containing bits 1, 33, 34, and all from 64 to 95 is printed as \fR"0xffffffff,0x00000006,0x00000002"\fP\&.
686
687 .PP
688 Up to \fRbuflen\fP characters may be written in buffer \fRbuf\fP\&.
689
690 .PP
691 If \fRbuflen\fP is 0, \fRbuf\fP may safely be \fRNULL\fP\&.
692
693 .PP
694 \fBReturns\fP
695 .RS 4
696 the number of characters that were actually written if not truncating, or that would have been written (not including the ending \fR\\0\fP)\&.
697
698 .PP
699 -1 on error\&.
700 .RE
701 .PP
702 \fBNote\fP
703 .RS 4
704 \fBIf the bitmap is a CPU or nodeset, it contains physical indexes\&.\fP This should be clearly indicated when displaying such bitmaps to end users\&. See also \fBHow do I convert between logical and OS/physical indexes?\fP
705 .RE
706 .PP
707
708 .SS "int hwloc_bitmap_sscanf (\fBhwloc_bitmap_t\fP bitmap, const char *restrict string)"
709
710 .PP
711 Parse a bitmap string as the default hwloc format and stores it in bitmap \fRbitmap\fP\&. The input string should be a comma-separared list of hexadecimal 32-bit blocks\&. String \fR"0xffffffff,0x6,0x2"\fP is parsed as a bitmap containing all bits between 64 and 95, and bits 33, 34 and 1\&.
712
713 .PP
714 \fBReturns\fP
715 .RS 4
716 0 on success, -1 on error\&.
717 .RE
718 .PP
719 \fBNote\fP
720 .RS 4
721 \fBIf the bitmap is a CPU or nodeset, the input string must contain physical indexes\&.\fP
722 .RE
723 .PP
724
725 .SS "int hwloc_bitmap_taskset_asprintf (char ** strp, \fBhwloc_const_bitmap_t\fP bitmap)"
726
727 .PP
728 Stringify a bitmap into a newly allocated taskset-specific string\&. The taskset program manipulates bitmap strings that contain a single (possible very long) hexadecimal number starting with 0x\&. A bitmap containing bits 1, 33, 34, and all from 64 to 95 is printed as \fR"0xffffffff0000000600000002"\fP\&.
729
730 .PP
731 \fBReturns\fP
732 .RS 4
733 the number of characters that were written (not including the ending \fR\\0\fP)\&.
734
735 .PP
736 -1 on error, for instance with \fRerrno\fP set to \fRENOMEM\fP on failure to allocate the output string\&.
737 .RE
738 .PP
739 \fBNote\fP
740 .RS 4
741 \fBIf the bitmap is a CPU or nodeset, it contains physical indexes\&.\fP This should be clearly indicated when displaying such bitmaps to end users\&. See also \fBHow do I convert between logical and OS/physical indexes?\fP
742 .RE
743 .PP
744
745 .SS "int hwloc_bitmap_taskset_snprintf (char *restrict buf, size_t buflen, \fBhwloc_const_bitmap_t\fP bitmap)"
746
747 .PP
748 Stringify a bitmap in the taskset-specific format\&. The taskset program manipulates bitmap strings that contain a single (possible very long) hexadecimal number starting with 0x\&. A bitmap containing bits 1, 33, 34, and all from 64 to 95 is printed as \fR"0xffffffff0000000600000002"\fP\&.
749
750 .PP
751 Up to \fRbuflen\fP characters may be written in buffer \fRbuf\fP\&.
752
753 .PP
754 If \fRbuflen\fP is 0, \fRbuf\fP may safely be \fRNULL\fP\&.
755
756 .PP
757 \fBReturns\fP
758 .RS 4
759 the number of characters that were actually written if not truncating, or that would have been written (not including the ending \fR\\0\fP)\&.
760
761 .PP
762 -1 on error\&.
763 .RE
764 .PP
765 \fBNote\fP
766 .RS 4
767 \fBIf the bitmap is a CPU or nodeset, it contains physical indexes\&.\fP This should be clearly indicated when displaying such bitmaps to end users\&. See also \fBHow do I convert between logical and OS/physical indexes?\fP
768 .RE
769 .PP
770
771 .SS "int hwloc_bitmap_taskset_sscanf (\fBhwloc_bitmap_t\fP bitmap, const char *restrict string)"
772
773 .PP
774 Parse a taskset-specific bitmap string and stores it in bitmap \fRbitmap\fP\&. The taskset program manipulates bitmap strings that contain a single (possible very long) hexadecimal number starting with 0x\&. String \fR"0xffffffff0000000600000002"\fP is parsed as a bitmap containing all bits between 64 and 95, and bits 33, 34 and 1\&.
775
776 .PP
777 \fBReturns\fP
778 .RS 4
779 0 on success, -1 on error\&.
780 .RE
781 .PP
782 \fBNote\fP
783 .RS 4
784 \fBIf the bitmap is a CPU or nodeset, the input string must contain physical indexes\&.\fP
785 .RE
786 .PP
787
788 .SS "unsigned long hwloc_bitmap_to_ith_ulong (\fBhwloc_const_bitmap_t\fP bitmap, unsigned i)"
789
790 .PP
791 Convert the \fRi\fP -th subset of bitmap \fRbitmap\fP into unsigned long mask\&.
792 .SS "unsigned long hwloc_bitmap_to_ulong (\fBhwloc_const_bitmap_t\fP bitmap)"
793
794 .PP
795 Convert the beginning part of bitmap \fRbitmap\fP into unsigned long \fRmask\fP\&.
796 .SS "int hwloc_bitmap_to_ulongs (\fBhwloc_const_bitmap_t\fP bitmap, unsigned nr, unsigned long * masks)"
797
798 .PP
799 Convert the first \fRnr\fP subsets of bitmap \fRbitmap\fP into the array of \fRnr\fP unsigned long \fRmasks\fP\&. \fRnr\fP may be determined earlier with \fBhwloc_bitmap_nr_ulongs()\fP\&.
800
801 .PP
802 \fBReturns\fP
803 .RS 4
804 0
805 .RE
806 .PP
807
808 .SS "int hwloc_bitmap_weight (\fBhwloc_const_bitmap_t\fP bitmap)"
809
810 .PP
811 Compute the "weight" of bitmap \fRbitmap\fP (i\&.e\&., number of indexes that are in the bitmap)\&.
812 .PP
813 \fBReturns\fP
814 .RS 4
815 the number of indexes that are in the bitmap\&.
816
817 .PP
818 -1 if \fRbitmap\fP is infinitely set\&.
819 .RE
820 .PP
821
822 .SS "int hwloc_bitmap_xor (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
823
824 .PP
825 Xor bitmaps \fRbitmap1\fP and \fRbitmap2\fP and store the result in bitmap \fRres\fP\&. \fRres\fP can be the same as \fRbitmap1\fP or \fRbitmap2\fP
826 .SS "void hwloc_bitmap_zero (\fBhwloc_bitmap_t\fP bitmap)"
827
828 .PP
829 Empty the bitmap \fRbitmap\fP\&.
830 .SH "Author"
831 .PP
832 Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.