.TH "hwlocality_bitmap" 3 "Thu Feb 11 2021" "Version 2.4.1" "Hardware Locality (hwloc)" \" -*- nroff -*-
.ad l
.nh
.SH NAME
hwlocality_bitmap \- The bitmap API
.SH SYNOPSIS
.br
.PP
.SS "Macros"

.in +1c
.ti -1c
.RI "#define \fBhwloc_bitmap_foreach_begin\fP(id,  bitmap)"
.br
.ti -1c
.RI "#define \fBhwloc_bitmap_foreach_end\fP()"
.br
.in -1c
.SS "Typedefs"

.in +1c
.ti -1c
.RI "typedef struct hwloc_bitmap_s * \fBhwloc_bitmap_t\fP"
.br
.ti -1c
.RI "typedef const struct hwloc_bitmap_s * \fBhwloc_const_bitmap_t\fP"
.br
.in -1c
.SS "Functions"

.in +1c
.ti -1c
.RI "\fBhwloc_bitmap_t\fP \fBhwloc_bitmap_alloc\fP (void)"
.br
.ti -1c
.RI "\fBhwloc_bitmap_t\fP \fBhwloc_bitmap_alloc_full\fP (void)"
.br
.ti -1c
.RI "void \fBhwloc_bitmap_free\fP (\fBhwloc_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "\fBhwloc_bitmap_t\fP \fBhwloc_bitmap_dup\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_copy\fP (\fBhwloc_bitmap_t\fP dst, \fBhwloc_const_bitmap_t\fP src)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_snprintf\fP (char *restrict buf, size_t buflen, \fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_asprintf\fP (char **strp, \fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_sscanf\fP (\fBhwloc_bitmap_t\fP bitmap, const char *restrict string)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_list_snprintf\fP (char *restrict buf, size_t buflen, \fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_list_asprintf\fP (char **strp, \fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_list_sscanf\fP (\fBhwloc_bitmap_t\fP bitmap, const char *restrict string)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_taskset_snprintf\fP (char *restrict buf, size_t buflen, \fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_taskset_asprintf\fP (char **strp, \fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_taskset_sscanf\fP (\fBhwloc_bitmap_t\fP bitmap, const char *restrict string)"
.br
.ti -1c
.RI "void \fBhwloc_bitmap_zero\fP (\fBhwloc_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "void \fBhwloc_bitmap_fill\fP (\fBhwloc_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_only\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_allbut\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_from_ulong\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned long mask)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_from_ith_ulong\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned i, unsigned long mask)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_from_ulongs\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned nr, const unsigned long *masks)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_set\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_set_range\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned begin, int end)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_set_ith_ulong\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned i, unsigned long mask)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_clr\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_clr_range\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned begin, int end)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_singlify\fP (\fBhwloc_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "unsigned long \fBhwloc_bitmap_to_ulong\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "unsigned long \fBhwloc_bitmap_to_ith_ulong\fP (\fBhwloc_const_bitmap_t\fP bitmap, unsigned i)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_to_ulongs\fP (\fBhwloc_const_bitmap_t\fP bitmap, unsigned nr, unsigned long *masks)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_nr_ulongs\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_isset\fP (\fBhwloc_const_bitmap_t\fP bitmap, unsigned id)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_iszero\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_isfull\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_first\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_next\fP (\fBhwloc_const_bitmap_t\fP bitmap, int prev)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_last\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_weight\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_first_unset\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_next_unset\fP (\fBhwloc_const_bitmap_t\fP bitmap, int prev)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_last_unset\fP (\fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_or\fP (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_and\fP (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_andnot\fP (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_xor\fP (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_not\fP (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_intersects\fP (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_isincluded\fP (\fBhwloc_const_bitmap_t\fP sub_bitmap, \fBhwloc_const_bitmap_t\fP super_bitmap)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_isequal\fP (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_compare_first\fP (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
.br
.ti -1c
.RI "int \fBhwloc_bitmap_compare\fP (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"
.br
.in -1c
.SH "Detailed Description"
.PP 
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\&.
.PP
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\&.
.PP
\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: 
.PP
.nf
hwloc_obj_t core1 = \&.\&.\&. , core2 = \&.\&.\&. ;
hwloc_bitmap_t set = hwloc_bitmap_alloc();
hwloc_bitmap_or(set, core1->cpuset, core2->cpuset);
hwloc_set_cpubind(topology, set, HWLOC_CPUBIND_THREAD);
hwloc_bitmap_free(set);

.fi
.PP
.PP
\fBNote\fP
.RS 4
Most functions below return an int that may be negative in case of error\&. The usual error case would be an internal failure to realloc/extend the storage of the bitmap (\fCerrno\fP would be set to \fCENOMEM\fP)\&.
.PP
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\&. 
.RE
.PP

.SH "Macro Definition Documentation"
.PP 
.SS "#define hwloc_bitmap_foreach_begin(id, bitmap)"

.PP
Loop macro iterating on bitmap \fCbitmap\fP\&. The loop must start with \fBhwloc_bitmap_foreach_begin()\fP and end with \fBhwloc_bitmap_foreach_end()\fP followed by a terminating ';'\&.
.PP
\fCindex\fP is the loop variable; it should be an unsigned int\&. The first iteration will set \fCindex\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 \fCindex\fP such that hwloc_bitmap_isset(bitmap, index) is true\&.
.PP
The assert prevents the loop from being infinite if the bitmap is infinitely set\&. 
.SS "#define hwloc_bitmap_foreach_end()"

.PP
End of loop macro iterating on a bitmap\&. Needs a terminating ';'\&.
.PP
\fBSee also\fP
.RS 4
\fBhwloc_bitmap_foreach_begin()\fP 
.RE
.PP

.SH "Typedef Documentation"
.PP 
.SS "typedef struct hwloc_bitmap_s* \fBhwloc_bitmap_t\fP"

.PP
Set of bits represented as an opaque pointer to an internal bitmap\&. 
.SS "typedef const struct hwloc_bitmap_s* \fBhwloc_const_bitmap_t\fP"

.PP
a non-modifiable \fBhwloc_bitmap_t\fP 
.SH "Function Documentation"
.PP 
.SS "int hwloc_bitmap_allbut (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"

.PP
Fill the bitmap \fCand\fP clear the index \fCid\fP\&. 
.SS "\fBhwloc_bitmap_t\fP hwloc_bitmap_alloc (void)"

.PP
Allocate a new empty bitmap\&. 
.PP
\fBReturns\fP
.RS 4
A valid bitmap or \fCNULL\fP\&.
.RE
.PP
The bitmap should be freed by a corresponding call to \fBhwloc_bitmap_free()\fP\&. 
.SS "\fBhwloc_bitmap_t\fP hwloc_bitmap_alloc_full (void)"

.PP
Allocate a new full bitmap\&. 
.SS "int hwloc_bitmap_and (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"

.PP
And bitmaps \fCbitmap1\fP and \fCbitmap2\fP and store the result in bitmap \fCres\fP\&. \fCres\fP can be the same as \fCbitmap1\fP or \fCbitmap2\fP 
.SS "int hwloc_bitmap_andnot (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"

.PP
And bitmap \fCbitmap1\fP and the negation of \fCbitmap2\fP and store the result in bitmap \fCres\fP\&. \fCres\fP can be the same as \fCbitmap1\fP or \fCbitmap2\fP 
.SS "int hwloc_bitmap_asprintf (char ** strp, \fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Stringify a bitmap into a newly allocated string\&. 
.PP
\fBReturns\fP
.RS 4
-1 on error\&. 
.RE
.PP

.SS "int hwloc_bitmap_clr (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"

.PP
Remove index \fCid\fP from bitmap \fCbitmap\fP\&. 
.SS "int hwloc_bitmap_clr_range (\fBhwloc_bitmap_t\fP bitmap, unsigned begin, int end)"

.PP
Remove indexes from \fCbegin\fP to \fCend\fP in bitmap \fCbitmap\fP\&. If \fCend\fP is \fC-1\fP, the range is infinite\&. 
.SS "int hwloc_bitmap_compare (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"

.PP
Compare bitmaps \fCbitmap1\fP and \fCbitmap2\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\&.
.PP
\fBReturns\fP
.RS 4
-1 if \fCbitmap1\fP is considered smaller than \fCbitmap2\fP\&. 
.PP
1 if \fCbitmap1\fP is considered larger than \fCbitmap2\fP\&. 
.PP
0 if bitmaps are equal (contrary to \fBhwloc_bitmap_compare_first()\fP)\&.
.RE
.PP
For instance comparing binary bitmaps 0011 and 0110 returns -1 (hence 0011 is considered smaller than 0110)\&. Comparing 00101 and 01010 returns -1 too\&.
.PP
\fBNote\fP
.RS 4
This is different from the non-existing hwloc_bitmap_compare_last() which would only compare the highest index of each bitmap\&. 
.RE
.PP

.SS "int hwloc_bitmap_compare_first (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"

.PP
Compare bitmaps \fCbitmap1\fP and \fCbitmap2\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)\&.
.PP
\fBReturns\fP
.RS 4
-1 if \fCbitmap1\fP is considered smaller than \fCbitmap2\fP\&. 
.PP
1 if \fCbitmap1\fP is considered larger than \fCbitmap2\fP\&.
.RE
.PP
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\&.
.PP
\fBReturns\fP
.RS 4
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\&. 
.RE
.PP

.SS "int hwloc_bitmap_copy (\fBhwloc_bitmap_t\fP dst, \fBhwloc_const_bitmap_t\fP src)"

.PP
Copy the contents of bitmap \fCsrc\fP into the already allocated bitmap \fCdst\fP\&. 
.SS "\fBhwloc_bitmap_t\fP hwloc_bitmap_dup (\fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Duplicate bitmap \fCbitmap\fP by allocating a new bitmap and copying \fCbitmap\fP contents\&. If \fCbitmap\fP is \fCNULL\fP, \fCNULL\fP is returned\&. 
.SS "void hwloc_bitmap_fill (\fBhwloc_bitmap_t\fP bitmap)"

.PP
Fill bitmap \fCbitmap\fP with all possible indexes (even if those objects don't exist or are otherwise unavailable) 
.SS "int hwloc_bitmap_first (\fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Compute the first index (least significant bit) in bitmap \fCbitmap\fP\&. 
.PP
\fBReturns\fP
.RS 4
-1 if no index is set in \fCbitmap\fP\&. 
.RE
.PP

.SS "int hwloc_bitmap_first_unset (\fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Compute the first unset index (least significant bit) in bitmap \fCbitmap\fP\&. 
.PP
\fBReturns\fP
.RS 4
-1 if no index is unset in \fCbitmap\fP\&. 
.RE
.PP

.SS "void hwloc_bitmap_free (\fBhwloc_bitmap_t\fP bitmap)"

.PP
Free bitmap \fCbitmap\fP\&. If \fCbitmap\fP is \fCNULL\fP, no operation is performed\&. 
.SS "int hwloc_bitmap_from_ith_ulong (\fBhwloc_bitmap_t\fP bitmap, unsigned i, unsigned long mask)"

.PP
Setup bitmap \fCbitmap\fP from unsigned long \fCmask\fP used as \fCi\fP -th subset\&. 
.SS "int hwloc_bitmap_from_ulong (\fBhwloc_bitmap_t\fP bitmap, unsigned long mask)"

.PP
Setup bitmap \fCbitmap\fP from unsigned long \fCmask\fP\&. 
.SS "int hwloc_bitmap_from_ulongs (\fBhwloc_bitmap_t\fP bitmap, unsigned nr, const unsigned long * masks)"

.PP
Setup bitmap \fCbitmap\fP from unsigned longs \fCmasks\fP used as first \fCnr\fP subsets\&. 
.SS "int hwloc_bitmap_intersects (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"

.PP
Test whether bitmaps \fCbitmap1\fP and \fCbitmap2\fP intersects\&. 
.PP
\fBReturns\fP
.RS 4
1 if bitmaps intersect, 0 otherwise\&. 
.RE
.PP

.SS "int hwloc_bitmap_isequal (\fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"

.PP
Test whether bitmap \fCbitmap1\fP is equal to bitmap \fCbitmap2\fP\&. 
.PP
\fBReturns\fP
.RS 4
1 if bitmaps are equal, 0 otherwise\&. 
.RE
.PP

.SS "int hwloc_bitmap_isfull (\fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Test whether bitmap \fCbitmap\fP is completely full\&. 
.PP
\fBReturns\fP
.RS 4
1 if bitmap is full, 0 otherwise\&.
.RE
.PP
\fBNote\fP
.RS 4
A full bitmap is always infinitely set\&. 
.RE
.PP

.SS "int hwloc_bitmap_isincluded (\fBhwloc_const_bitmap_t\fP sub_bitmap, \fBhwloc_const_bitmap_t\fP super_bitmap)"

.PP
Test whether bitmap \fCsub_bitmap\fP is part of bitmap \fCsuper_bitmap\fP\&. 
.PP
\fBReturns\fP
.RS 4
1 if \fCsub_bitmap\fP is included in \fCsuper_bitmap\fP, 0 otherwise\&.
.RE
.PP
\fBNote\fP
.RS 4
The empty bitmap is considered included in any other bitmap\&. 
.RE
.PP

.SS "int hwloc_bitmap_isset (\fBhwloc_const_bitmap_t\fP bitmap, unsigned id)"

.PP
Test whether index \fCid\fP is part of bitmap \fCbitmap\fP\&. 
.PP
\fBReturns\fP
.RS 4
1 if the bit at index \fCid\fP is set in bitmap \fCbitmap\fP, 0 otherwise\&. 
.RE
.PP

.SS "int hwloc_bitmap_iszero (\fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Test whether bitmap \fCbitmap\fP is empty\&. 
.PP
\fBReturns\fP
.RS 4
1 if bitmap is empty, 0 otherwise\&. 
.RE
.PP

.SS "int hwloc_bitmap_last (\fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Compute the last index (most significant bit) in bitmap \fCbitmap\fP\&. 
.PP
\fBReturns\fP
.RS 4
-1 if no index is set in \fCbitmap\fP, or if \fCbitmap\fP is infinitely set\&. 
.RE
.PP

.SS "int hwloc_bitmap_last_unset (\fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Compute the last unset index (most significant bit) in bitmap \fCbitmap\fP\&. 
.PP
\fBReturns\fP
.RS 4
-1 if no index is unset in \fCbitmap\fP, or if \fCbitmap\fP is infinitely set\&. 
.RE
.PP

.SS "int hwloc_bitmap_list_asprintf (char ** strp, \fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Stringify a bitmap into a newly allocated list string\&. 
.PP
\fBReturns\fP
.RS 4
-1 on error\&. 
.RE
.PP

.SS "int hwloc_bitmap_list_snprintf (char *restrict buf, size_t buflen, \fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Stringify a bitmap in the list format\&. Lists are comma-separated indexes or ranges\&. Ranges are dash separated indexes\&. The last range may not have an ending indexes if the bitmap is infinitely set\&.
.PP
Up to \fCbuflen\fP characters may be written in buffer \fCbuf\fP\&.
.PP
If \fCbuflen\fP is 0, \fCbuf\fP may safely be \fCNULL\fP\&.
.PP
\fBReturns\fP
.RS 4
the number of character that were actually written if not truncating, or that would have been written (not including the ending \\0)\&. 
.RE
.PP

.SS "int hwloc_bitmap_list_sscanf (\fBhwloc_bitmap_t\fP bitmap, const char *restrict string)"

.PP
Parse a list string and stores it in bitmap \fCbitmap\fP\&. 
.SS "int hwloc_bitmap_next (\fBhwloc_const_bitmap_t\fP bitmap, int prev)"

.PP
Compute the next index in bitmap \fCbitmap\fP which is after index \fCprev\fP\&. If \fCprev\fP is -1, the first index is returned\&.
.PP
\fBReturns\fP
.RS 4
-1 if no index with higher index is set in \fCbitmap\fP\&. 
.RE
.PP

.SS "int hwloc_bitmap_next_unset (\fBhwloc_const_bitmap_t\fP bitmap, int prev)"

.PP
Compute the next unset index in bitmap \fCbitmap\fP which is after index \fCprev\fP\&. If \fCprev\fP is -1, the first unset index is returned\&.
.PP
\fBReturns\fP
.RS 4
-1 if no index with higher index is unset in \fCbitmap\fP\&. 
.RE
.PP

.SS "int hwloc_bitmap_not (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Negate bitmap \fCbitmap\fP and store the result in bitmap \fCres\fP\&. \fCres\fP can be the same as \fCbitmap\fP 
.SS "int hwloc_bitmap_nr_ulongs (\fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Return the number of unsigned longs required for storing bitmap \fCbitmap\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 \fCnr\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\&.
.PP
When called on the output of \fBhwloc_topology_get_topology_cpuset()\fP, the returned number is large enough for all cpusets of the topology\&.
.PP
\fBReturns\fP
.RS 4
-1 if \fCbitmap\fP is infinite\&. 
.RE
.PP

.SS "int hwloc_bitmap_only (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"

.PP
Empty the bitmap \fCbitmap\fP and add bit \fCid\fP\&. 
.SS "int hwloc_bitmap_or (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"

.PP
Or bitmaps \fCbitmap1\fP and \fCbitmap2\fP and store the result in bitmap \fCres\fP\&. \fCres\fP can be the same as \fCbitmap1\fP or \fCbitmap2\fP 
.SS "int hwloc_bitmap_set (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"

.PP
Add index \fCid\fP in bitmap \fCbitmap\fP\&. 
.SS "int hwloc_bitmap_set_ith_ulong (\fBhwloc_bitmap_t\fP bitmap, unsigned i, unsigned long mask)"

.PP
Replace \fCi\fP -th subset of bitmap \fCbitmap\fP with unsigned long \fCmask\fP\&. 
.SS "int hwloc_bitmap_set_range (\fBhwloc_bitmap_t\fP bitmap, unsigned begin, int end)"

.PP
Add indexes from \fCbegin\fP to \fCend\fP in bitmap \fCbitmap\fP\&. If \fCend\fP is \fC-1\fP, the range is infinite\&. 
.SS "int hwloc_bitmap_singlify (\fBhwloc_bitmap_t\fP bitmap)"

.PP
Keep a single index among those set in bitmap \fCbitmap\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\&.
.PP
\fBNote\fP
.RS 4
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\&.
.PP
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)\&. 
.RE
.PP

.SS "int hwloc_bitmap_snprintf (char *restrict buf, size_t buflen, \fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Stringify a bitmap\&. Up to \fCbuflen\fP characters may be written in buffer \fCbuf\fP\&.
.PP
If \fCbuflen\fP is 0, \fCbuf\fP may safely be \fCNULL\fP\&.
.PP
\fBReturns\fP
.RS 4
the number of character that were actually written if not truncating, or that would have been written (not including the ending \\0)\&. 
.RE
.PP

.SS "int hwloc_bitmap_sscanf (\fBhwloc_bitmap_t\fP bitmap, const char *restrict string)"

.PP
Parse a bitmap string and stores it in bitmap \fCbitmap\fP\&. 
.SS "int hwloc_bitmap_taskset_asprintf (char ** strp, \fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Stringify a bitmap into a newly allocated taskset-specific string\&. 
.PP
\fBReturns\fP
.RS 4
-1 on error\&. 
.RE
.PP

.SS "int hwloc_bitmap_taskset_snprintf (char *restrict buf, size_t buflen, \fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Stringify a bitmap in the taskset-specific format\&. The taskset command manipulates bitmap strings that contain a single (possible very long) hexadecimal number starting with 0x\&.
.PP
Up to \fCbuflen\fP characters may be written in buffer \fCbuf\fP\&.
.PP
If \fCbuflen\fP is 0, \fCbuf\fP may safely be \fCNULL\fP\&.
.PP
\fBReturns\fP
.RS 4
the number of character that were actually written if not truncating, or that would have been written (not including the ending \\0)\&. 
.RE
.PP

.SS "int hwloc_bitmap_taskset_sscanf (\fBhwloc_bitmap_t\fP bitmap, const char *restrict string)"

.PP
Parse a taskset-specific bitmap string and stores it in bitmap \fCbitmap\fP\&. 
.SS "unsigned long hwloc_bitmap_to_ith_ulong (\fBhwloc_const_bitmap_t\fP bitmap, unsigned i)"

.PP
Convert the \fCi\fP -th subset of bitmap \fCbitmap\fP into unsigned long mask\&. 
.SS "unsigned long hwloc_bitmap_to_ulong (\fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Convert the beginning part of bitmap \fCbitmap\fP into unsigned long \fCmask\fP\&. 
.SS "int hwloc_bitmap_to_ulongs (\fBhwloc_const_bitmap_t\fP bitmap, unsigned nr, unsigned long * masks)"

.PP
Convert the first \fCnr\fP subsets of bitmap \fCbitmap\fP into the array of \fCnr\fP unsigned long \fCmasks\fP\&. \fCnr\fP may be determined earlier with \fBhwloc_bitmap_nr_ulongs()\fP\&.
.PP
\fBReturns\fP
.RS 4
0 
.RE
.PP

.SS "int hwloc_bitmap_weight (\fBhwloc_const_bitmap_t\fP bitmap)"

.PP
Compute the 'weight' of bitmap \fCbitmap\fP (i\&.e\&., number of indexes that are in the bitmap)\&. 
.PP
\fBReturns\fP
.RS 4
the number of indexes that are in the bitmap\&.
.PP
-1 if \fCbitmap\fP is infinitely set\&. 
.RE
.PP

.SS "int hwloc_bitmap_xor (\fBhwloc_bitmap_t\fP res, \fBhwloc_const_bitmap_t\fP bitmap1, \fBhwloc_const_bitmap_t\fP bitmap2)"

.PP
Xor bitmaps \fCbitmap1\fP and \fCbitmap2\fP and store the result in bitmap \fCres\fP\&. \fCres\fP can be the same as \fCbitmap1\fP or \fCbitmap2\fP 
.SS "void hwloc_bitmap_zero (\fBhwloc_bitmap_t\fP bitmap)"

.PP
Empty the bitmap \fCbitmap\fP\&. 
.SH "Author"
.PP 
Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code\&.