.TH "The bitmap API" 3 "Tue Oct 7 2014" "Version 1.10.0" "Hardware Locality (hwloc)" \" -*- nroff -*-
.ad l
.nh
.SH NAME
The bitmap API \- 
.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 
.br
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 "void \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 "void \fBhwloc_bitmap_only\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
.br
.ti -1c
.RI "void \fBhwloc_bitmap_allbut\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
.br
.ti -1c
.RI "void \fBhwloc_bitmap_from_ulong\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned long mask)"
.br
.ti -1c
.RI "void \fBhwloc_bitmap_from_ith_ulong\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned i, unsigned long mask)"
.br
.ti -1c
.RI "void \fBhwloc_bitmap_set\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
.br
.ti -1c
.RI "void \fBhwloc_bitmap_set_range\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned begin, int end)"
.br
.ti -1c
.RI "void \fBhwloc_bitmap_set_ith_ulong\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned i, unsigned long mask)"
.br
.ti -1c
.RI "void \fBhwloc_bitmap_clr\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned id)"
.br
.ti -1c
.RI "void \fBhwloc_bitmap_clr_range\fP (\fBhwloc_bitmap_t\fP bitmap, unsigned begin, int end)"
.br
.ti -1c
.RI "void \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_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 "void \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 "void \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 "void \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 "void \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 "void \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 objects, typically OS processors -- which may actually be hardware threads (represented by \fBhwloc_cpuset_t\fP, which is a typedef for \fBhwloc_bitmap_t\fP) -- or memory nodes (represented by \fBhwloc_nodeset_t\fP, which is also a typedef for \fBhwloc_bitmap_t\fP)\&.
.PP
\fIBoth CPU and node sets are always indexed by OS physical number\&.\fP
.PP
\fBNote:\fP
.RS 4
CPU sets and nodesets are described in \fBObject Sets (hwloc_cpuset_t and hwloc_nodeset_t)\fP\&.
.RE
.PP
A bitmap may be of infinite size\&.
.PP
\fBNote:\fP
.RS 4
Several examples of using the bitmap API are available under the doc/examples/ directory in the source tree\&. Regression tests such as tests/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\&. \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 that 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 infinite\&. 
.SS "#define hwloc_bitmap_foreach_end()"
\fBValue:\fP
.PP
.nf
} \
} while (0)
.fi
.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 "void hwloc_bitmap_allbut (\fBhwloc_bitmap_t\fPbitmap, unsignedid)"

.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 "void hwloc_bitmap_and (\fBhwloc_bitmap_t\fPres, \fBhwloc_const_bitmap_t\fPbitmap1, \fBhwloc_const_bitmap_t\fPbitmap2)"

.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 "void hwloc_bitmap_andnot (\fBhwloc_bitmap_t\fPres, \fBhwloc_const_bitmap_t\fPbitmap1, \fBhwloc_const_bitmap_t\fPbitmap2)"

.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\fPbitmap)"

.PP
Stringify a bitmap into a newly allocated string\&. 
.SS "void hwloc_bitmap_clr (\fBhwloc_bitmap_t\fPbitmap, unsignedid)"

.PP
Remove index \fCid\fP from bitmap \fCbitmap\fP\&. 
.SS "void hwloc_bitmap_clr_range (\fBhwloc_bitmap_t\fPbitmap, unsignedbegin, intend)"

.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\fPbitmap1, \fBhwloc_const_bitmap_t\fPbitmap2)"

.PP
Compare bitmaps \fCbitmap1\fP and \fCbitmap2\fP using their highest index\&. Higher most significant bit is higher\&. The empty bitmap is considered lower than anything\&. 
.SS "int hwloc_bitmap_compare_first (\fBhwloc_const_bitmap_t\fPbitmap1, \fBhwloc_const_bitmap_t\fPbitmap2)"

.PP
Compare bitmaps \fCbitmap1\fP and \fCbitmap2\fP using their lowest index\&. Smaller least significant bit is smaller\&. The empty bitmap is considered higher than anything\&. 
.SS "void hwloc_bitmap_copy (\fBhwloc_bitmap_t\fPdst, \fBhwloc_const_bitmap_t\fPsrc)"

.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\fPbitmap)"

.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\fPbitmap)"

.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\fPbitmap)"

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

.SS "void hwloc_bitmap_free (\fBhwloc_bitmap_t\fPbitmap)"

.PP
Free bitmap \fCbitmap\fP\&. If \fCbitmap\fP is \fCNULL\fP, no operation is performed\&. 
.SS "void hwloc_bitmap_from_ith_ulong (\fBhwloc_bitmap_t\fPbitmap, unsignedi, unsigned longmask)"

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

.PP
Setup bitmap \fCbitmap\fP from unsigned long \fCmask\fP\&. 
.SS "int hwloc_bitmap_intersects (\fBhwloc_const_bitmap_t\fPbitmap1, \fBhwloc_const_bitmap_t\fPbitmap2)"

.PP
Test whether bitmaps \fCbitmap1\fP and \fCbitmap2\fP intersects\&. 
.SS "int hwloc_bitmap_isequal (\fBhwloc_const_bitmap_t\fPbitmap1, \fBhwloc_const_bitmap_t\fPbitmap2)"

.PP
Test whether bitmap \fCbitmap1\fP is equal to bitmap \fCbitmap2\fP\&. 
.SS "int hwloc_bitmap_isfull (\fBhwloc_const_bitmap_t\fPbitmap)"

.PP
Test whether bitmap \fCbitmap\fP is completely full\&. 
.SS "int hwloc_bitmap_isincluded (\fBhwloc_const_bitmap_t\fPsub_bitmap, \fBhwloc_const_bitmap_t\fPsuper_bitmap)"

.PP
Test whether bitmap \fCsub_bitmap\fP is part of bitmap \fCsuper_bitmap\fP\&. 
.SS "int hwloc_bitmap_isset (\fBhwloc_const_bitmap_t\fPbitmap, unsignedid)"

.PP
Test whether index \fCid\fP is part of bitmap \fCbitmap\fP\&. 
.SS "int hwloc_bitmap_iszero (\fBhwloc_const_bitmap_t\fPbitmap)"

.PP
Test whether bitmap \fCbitmap\fP is empty\&. 
.SS "int hwloc_bitmap_last (\fBhwloc_const_bitmap_t\fPbitmap)"

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

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

.PP
Stringify a bitmap into a newly allocated list string\&. 
.SS "int hwloc_bitmap_list_snprintf (char *restrictbuf, size_tbuflen, \fBhwloc_const_bitmap_t\fPbitmap)"

.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 a ending indexes if the bitmap is infinite\&.
.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\fPbitmap, const char *restrictstring)"

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

.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 bitmap\&. 
.RE
.PP

.SS "void hwloc_bitmap_not (\fBhwloc_bitmap_t\fPres, \fBhwloc_const_bitmap_t\fPbitmap)"

.PP
Negate bitmap \fCbitmap\fP and store the result in bitmap \fCres\fP\&. \fCres\fP can be the same as \fCbitmap\fP 
.SS "void hwloc_bitmap_only (\fBhwloc_bitmap_t\fPbitmap, unsignedid)"

.PP
Empty the bitmap \fCbitmap\fP and add bit \fCid\fP\&. 
.SS "void hwloc_bitmap_or (\fBhwloc_bitmap_t\fPres, \fBhwloc_const_bitmap_t\fPbitmap1, \fBhwloc_const_bitmap_t\fPbitmap2)"

.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 "void hwloc_bitmap_set (\fBhwloc_bitmap_t\fPbitmap, unsignedid)"

.PP
Add index \fCid\fP in bitmap \fCbitmap\fP\&. 
.SS "void hwloc_bitmap_set_ith_ulong (\fBhwloc_bitmap_t\fPbitmap, unsignedi, unsigned longmask)"

.PP
Replace \fCi\fP -th subset of bitmap \fCbitmap\fP with unsigned long \fCmask\fP\&. 
.SS "void hwloc_bitmap_set_range (\fBhwloc_bitmap_t\fPbitmap, unsignedbegin, intend)"

.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 "void hwloc_bitmap_singlify (\fBhwloc_bitmap_t\fPbitmap)"

.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 logical CPUs in the original mask\&. 
.SS "int hwloc_bitmap_snprintf (char *restrictbuf, size_tbuflen, \fBhwloc_const_bitmap_t\fPbitmap)"

.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\fPbitmap, const char *restrictstring)"

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

.PP
Stringify a bitmap into a newly allocated taskset-specific string\&. 
.SS "int hwloc_bitmap_taskset_snprintf (char *restrictbuf, size_tbuflen, \fBhwloc_const_bitmap_t\fPbitmap)"

.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\fPbitmap, const char *restrictstring)"

.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\fPbitmap, unsignedi)"

.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\fPbitmap)"

.PP
Convert the beginning part of bitmap \fCbitmap\fP into unsigned long \fCmask\fP\&. 
.SS "int hwloc_bitmap_weight (\fBhwloc_const_bitmap_t\fPbitmap)"

.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\&. 
.RE
.PP

.SS "void hwloc_bitmap_xor (\fBhwloc_bitmap_t\fPres, \fBhwloc_const_bitmap_t\fPbitmap1, \fBhwloc_const_bitmap_t\fPbitmap2)"

.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\fPbitmap)"

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