Hardware Locality (hwloc): The bitmap API

Hardware Locality (hwloc) 2.14.0rc1

Macros | Typedefs | Functions
The bitmap API

## Macros
#define | hwloc_bitmap_foreach_begin(id, bitmap)
#define | hwloc_bitmap_foreach_end()

## Typedefs
typedef struct hwloc_bitmap_s * | hwloc_bitmap_t
typedef const struct hwloc_bitmap_s * | hwloc_const_bitmap_t

## Functions
hwloc_bitmap_t | hwloc_bitmap_alloc (void)
hwloc_bitmap_t | hwloc_bitmap_alloc_full (void)
void | hwloc_bitmap_free (hwloc_bitmap_t bitmap)
hwloc_bitmap_t | hwloc_bitmap_dup (hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_copy (hwloc_bitmap_t dst, hwloc_const_bitmap_t src)
int | hwloc_bitmap_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
int | hwloc_bitmap_list_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_list_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_list_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
int | hwloc_bitmap_taskset_snprintf (char *restrict buf, size_t buflen, hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_taskset_asprintf (char **strp, hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_taskset_sscanf (hwloc_bitmap_t bitmap, const char *restrict string)
void | hwloc_bitmap_zero (hwloc_bitmap_t bitmap)
void | hwloc_bitmap_fill (hwloc_bitmap_t bitmap)
int | hwloc_bitmap_only (hwloc_bitmap_t bitmap, unsigned id)
int | hwloc_bitmap_allbut (hwloc_bitmap_t bitmap, unsigned id)
int | hwloc_bitmap_from_ulong (hwloc_bitmap_t bitmap, unsigned long mask)
int | hwloc_bitmap_from_ith_ulong (hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
int | hwloc_bitmap_from_ulongs (hwloc_bitmap_t bitmap, unsigned nr, const unsigned long *masks)
int | hwloc_bitmap_set (hwloc_bitmap_t bitmap, unsigned id)
int | hwloc_bitmap_set_range (hwloc_bitmap_t bitmap, unsigned begin, int end)
int | hwloc_bitmap_set_ith_ulong (hwloc_bitmap_t bitmap, unsigned i, unsigned long mask)
int | hwloc_bitmap_clr (hwloc_bitmap_t bitmap, unsigned id)
int | hwloc_bitmap_clr_range (hwloc_bitmap_t bitmap, unsigned begin, int end)
int | hwloc_bitmap_singlify (hwloc_bitmap_t bitmap)
unsigned long | hwloc_bitmap_to_ulong (hwloc_const_bitmap_t bitmap)
unsigned long | hwloc_bitmap_to_ith_ulong (hwloc_const_bitmap_t bitmap, unsigned i)
int | hwloc_bitmap_to_ulongs (hwloc_const_bitmap_t bitmap, unsigned nr, unsigned long *masks)
int | hwloc_bitmap_nr_ulongs (hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_isset (hwloc_const_bitmap_t bitmap, unsigned id)
int | hwloc_bitmap_iszero (hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_isfull (hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_first (hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_next (hwloc_const_bitmap_t bitmap, int prev)
int | hwloc_bitmap_last (hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_weight (hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_first_unset (hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_next_unset (hwloc_const_bitmap_t bitmap, int prev)
int | hwloc_bitmap_last_unset (hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_or (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
int | hwloc_bitmap_and (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
int | hwloc_bitmap_andnot (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
int | hwloc_bitmap_xor (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
int | hwloc_bitmap_not (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap)
int | hwloc_bitmap_intersects (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
int | hwloc_bitmap_isincluded (hwloc_const_bitmap_t sub_bitmap, hwloc_const_bitmap_t super_bitmap)
int | hwloc_bitmap_isequal (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
int | hwloc_bitmap_compare_first (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
int | hwloc_bitmap_compare (hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)

## Detailed Description

The hwloc_bitmap_t 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.

Bitmaps are used by hwloc for sets of OS processors (which may actually be hardware threads) as by hwloc_cpuset_t (a typedef for hwloc_bitmap_t), or sets of NUMA memory nodes as hwloc_nodeset_t (also a typedef for hwloc_bitmap_t). Those are used for cpuset and nodeset fields in the hwloc_obj structure, see Object Sets (hwloc_cpuset_t and hwloc_nodeset_t).

Both CPU and node sets are always indexed by OS physical number. However users should usually not build CPU and node sets manually (e.g. with hwloc_bitmap_set()). One should rather use existing object sets and combine them with hwloc_bitmap_or(), etc. For instance, binding the current thread on a pair of cores may be performed with:

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);
hwloc_obj_t
struct hwloc_obj * hwloc_obj_t
Convenience typedef; a pointer to a struct hwloc_obj.
Definition hwloc.h:637
hwloc_set_cpubind
int hwloc_set_cpubind(hwloc_topology_t topology, hwloc_const_cpuset_t set, int flags)
Bind current process or thread on CPUs given in physical bitmap set.
HWLOC_CPUBIND_THREAD
@ HWLOC_CPUBIND_THREAD
Bind current thread of current process.
Definition hwloc.h:1262
hwloc_bitmap_or
int hwloc_bitmap_or(hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap1, hwloc_const_bitmap_t bitmap2)
Or bitmaps bitmap1 and bitmap2 and store the result in bitmap res.
hwloc_bitmap_free
void hwloc_bitmap_free(hwloc_bitmap_t bitmap)
Free bitmap bitmap.
hwloc_bitmap_t
struct hwloc_bitmap_s * hwloc_bitmap_t
Set of bits represented as an opaque pointer to an internal bitmap.
Definition bitmap.h:70
hwloc_bitmap_alloc
hwloc_bitmap_t hwloc_bitmap_alloc(void)
Allocate a new empty bitmap.
hwloc_obj::cpuset
hwloc_cpuset_t cpuset
CPUs covered by this object.
Definition hwloc.h:553

Note
  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 (`errno` would be set to `ENOMEM`). See also Error reporting in the API.
  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.

## Macro Definition Documentation

## ◆ hwloc_bitmap_foreach_begin

#define hwloc_bitmap_foreach_begin | ( |  | id,
|  |  | bitmap )

Loop macro iterating on bitmap `bitmap`.

The loop must start with hwloc_bitmap_foreach_begin() and end with hwloc_bitmap_foreach_end() followed by a terminating ';'.

`id` is the loop variable; it should be an unsigned int. The first iteration will set `id` 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 `id` such that hwloc_bitmap_isset(bitmap, id) is true.

The assert prevents the loop from being infinite if the bitmap is infinitely set.

## ◆ hwloc_bitmap_foreach_end

#define hwloc_bitmap_foreach_end | ( |  | ) |

End of loop macro iterating on a bitmap.

Needs a terminating ';'.

See also
  hwloc_bitmap_foreach_begin()

## Typedef Documentation

## ◆ hwloc_bitmap_t

typedef struct hwloc_bitmap_s* hwloc_bitmap_t

Set of bits represented as an opaque pointer to an internal bitmap.

## ◆ hwloc_const_bitmap_t

typedef const struct hwloc_bitmap_s* hwloc_const_bitmap_t

a non-modifiable hwloc_bitmap_t

## Function Documentation

## ◆ hwloc_bitmap_allbut()

int hwloc_bitmap_allbut | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | id )

Fill the bitmap `and` clear the index `id`.

## ◆ hwloc_bitmap_alloc()

hwloc_bitmap_t hwloc_bitmap_alloc | ( | void |  | ) |

Allocate a new empty bitmap.

Returns
  A valid bitmap or `NULL`.

The bitmap should be freed by a corresponding call to hwloc_bitmap_free().

## ◆ hwloc_bitmap_alloc_full()

hwloc_bitmap_t hwloc_bitmap_alloc_full | ( | void |  | ) |

Allocate a new full bitmap.

Returns
  A valid bitmap or `NULL`.

The bitmap should be freed by a corresponding call to hwloc_bitmap_free().

## ◆ hwloc_bitmap_and()

int hwloc_bitmap_and | ( | hwloc_bitmap_t | res,
|  | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2 )

And bitmaps `bitmap1` and `bitmap2` and store the result in bitmap `res`.

`res` can be the same as `bitmap1` or `bitmap2`

## ◆ hwloc_bitmap_andnot()

int hwloc_bitmap_andnot | ( | hwloc_bitmap_t | res,
|  | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2 )

And bitmap `bitmap1` and the negation of `bitmap2` and store the result in bitmap `res`.

`res` can be the same as `bitmap1` or `bitmap2`

## ◆ hwloc_bitmap_asprintf()

int hwloc_bitmap_asprintf | ( | char ** | strp,
|  | hwloc_const_bitmap_t | bitmap )

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 "0xffffffff,0x00000006,0x00000002".

Returns
  the number of characters that were written (not including the ending `\0`).
  -1 on error, for instance with `errno` set to `ENOMEM` on failure to allocate the output string.

Note
  If the bitmap is a CPU or nodeset, it contains physical indexes. This should be clearly indicated when displaying such bitmaps to end users. See also How do I convert between logical and OS/physical indexes?

## ◆ hwloc_bitmap_clr()

int hwloc_bitmap_clr | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | id )

Remove index `id` from bitmap `bitmap`.

## ◆ hwloc_bitmap_clr_range()

int hwloc_bitmap_clr_range | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | begin,
|  | int | end )

Remove indexes from `begin` to `end` in bitmap `bitmap`.

If `end` is `-1`, the range is infinite.

## ◆ hwloc_bitmap_compare()

int hwloc_bitmap_compare | ( | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2 )

Compare bitmaps `bitmap1` and `bitmap2` 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.

Returns
  -1 if `bitmap1` is considered smaller than `bitmap2`.
  1 if `bitmap1` is considered larger than `bitmap2`.
  0 if bitmaps are equal (contrary to hwloc_bitmap_compare_first()).

For instance comparing binary bitmaps 0011 and 0110 returns -1 (hence 0011 is considered smaller than 0110). Comparing 00101 and 01010 returns -1 too.

Note
  This is different from the non-existing hwloc_bitmap_compare_last() which would only compare the highest index of each bitmap.

## ◆ hwloc_bitmap_compare_first()

int hwloc_bitmap_compare_first | ( | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2 )

Compare bitmaps `bitmap1` and `bitmap2` 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).

Returns
  -1 if `bitmap1` is considered smaller than `bitmap2`.
  1 if `bitmap1` is considered larger than `bitmap2`.

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.

Returns
  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.

## ◆ hwloc_bitmap_copy()

int hwloc_bitmap_copy | ( | hwloc_bitmap_t | dst,
|  | hwloc_const_bitmap_t | src )

Copy the contents of bitmap `src` into the already allocated bitmap `dst`.

## ◆ hwloc_bitmap_dup()

hwloc_bitmap_t hwloc_bitmap_dup | ( | hwloc_const_bitmap_t | bitmap | ) |

Duplicate bitmap `bitmap` by allocating a new bitmap and copying `bitmap` contents.

If `bitmap` is `NULL`, `NULL` is returned.

## ◆ hwloc_bitmap_fill()

void hwloc_bitmap_fill | ( | hwloc_bitmap_t | bitmap | ) |

Fill bitmap `bitmap` with all possible indexes (even if those objects don't exist or are otherwise unavailable).

## ◆ hwloc_bitmap_first()

int hwloc_bitmap_first | ( | hwloc_const_bitmap_t | bitmap | ) |

Compute the first index (least significant bit) in bitmap `bitmap`.

Returns
  the first index set in `bitmap`.
  -1 if `bitmap` is empty.

## ◆ hwloc_bitmap_first_unset()

int hwloc_bitmap_first_unset | ( | hwloc_const_bitmap_t | bitmap | ) |

Compute the first unset index (least significant bit) in bitmap `bitmap`.

Returns
  the first unset index in `bitmap`.
  -1 if `bitmap` is full.

## ◆ hwloc_bitmap_free()

void hwloc_bitmap_free | ( | hwloc_bitmap_t | bitmap | ) |

Free bitmap `bitmap`.

If `bitmap` is `NULL`, no operation is performed.

## ◆ hwloc_bitmap_from_ith_ulong()

int hwloc_bitmap_from_ith_ulong | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | i,
|  | unsigned long | mask )

Setup bitmap `bitmap` from unsigned long `mask` used as `i` -th subset.

## ◆ hwloc_bitmap_from_ulong()

int hwloc_bitmap_from_ulong | ( | hwloc_bitmap_t | bitmap,
|  | unsigned long | mask )

Setup bitmap `bitmap` from unsigned long `mask`.

## ◆ hwloc_bitmap_from_ulongs()

int hwloc_bitmap_from_ulongs | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | nr,
|  | const unsigned long * | masks )

Setup bitmap `bitmap` from unsigned longs `masks` used as first `nr` subsets.

## ◆ hwloc_bitmap_intersects()

int hwloc_bitmap_intersects | ( | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2 )

Test whether bitmaps `bitmap1` and `bitmap2` intersects.

Returns
  1 if bitmaps intersect, 0 otherwise.

Note
  The empty bitmap does not intersect any other bitmap.

## ◆ hwloc_bitmap_isequal()

int hwloc_bitmap_isequal | ( | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2 )

Test whether bitmap `bitmap1` is equal to bitmap `bitmap2`.

Returns
  1 if bitmaps are equal, 0 otherwise.

## ◆ hwloc_bitmap_isfull()

int hwloc_bitmap_isfull | ( | hwloc_const_bitmap_t | bitmap | ) |

Test whether bitmap `bitmap` is completely full.

Returns
  1 if bitmap is full, 0 otherwise.

Note
  A full bitmap is always infinitely set.

## ◆ hwloc_bitmap_isincluded()

int hwloc_bitmap_isincluded | ( | hwloc_const_bitmap_t | sub_bitmap,
|  | hwloc_const_bitmap_t | super_bitmap )

Test whether bitmap `sub_bitmap` is part of bitmap `super_bitmap`.

Returns
  1 if `sub_bitmap` is included in `super_bitmap`, 0 otherwise.

Note
  The empty bitmap is considered included in any other bitmap.

## ◆ hwloc_bitmap_isset()

int hwloc_bitmap_isset | ( | hwloc_const_bitmap_t | bitmap,
|  | unsigned | id )

Test whether index `id` is part of bitmap `bitmap`.

Returns
  1 if the bit at index `id` is set in bitmap `bitmap`, 0 otherwise.

## ◆ hwloc_bitmap_iszero()

int hwloc_bitmap_iszero | ( | hwloc_const_bitmap_t | bitmap | ) |

Test whether bitmap `bitmap` is empty.

Returns
  1 if bitmap is empty, 0 otherwise.

## ◆ hwloc_bitmap_last()

int hwloc_bitmap_last | ( | hwloc_const_bitmap_t | bitmap | ) |

Compute the last index (most significant bit) in bitmap `bitmap`.

Returns
  the last index set in `bitmap`.
  -1 if `bitmap` is empty, or if `bitmap` is infinitely set.

## ◆ hwloc_bitmap_last_unset()

int hwloc_bitmap_last_unset | ( | hwloc_const_bitmap_t | bitmap | ) |

Compute the last unset index (most significant bit) in bitmap `bitmap`.

Returns
  the last index unset in `bitmap`.
  -1 if `bitmap` is full, or if `bitmap` is not infinitely set.

## ◆ hwloc_bitmap_list_asprintf()

int hwloc_bitmap_list_asprintf | ( | char ** | strp,
|  | hwloc_const_bitmap_t | bitmap )

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 "1,33-34,64-95". The last range may not have an ending index if the bitmap is infinitely set.

Returns
  the number of characters that were written (not including the ending `\0`).
  -1 on error, for instance with `errno` set to `ENOMEM` on failure to allocate the output string.

Note
  If the bitmap is a CPU or nodeset, it contains physical indexes. This should be clearly indicated when displaying such bitmaps to end users. See also How do I convert between logical and OS/physical indexes?

## ◆ hwloc_bitmap_list_snprintf()

int hwloc_bitmap_list_snprintf | ( | char *restrict | buf,
|  | size_t | buflen,
|  | hwloc_const_bitmap_t | bitmap )

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 "1,33-34,64-95". The last range may not have an ending index if the bitmap is infinitely set.

Up to `buflen` characters may be written in buffer `buf`.

If `buflen` is 0, `buf` may safely be `NULL`.

Returns
  the number of characters that were actually written if not truncating, or that would have been written (not including the ending `\0`).
  -1 on error.

Note
  If the bitmap is a CPU or nodeset, it contains physical indexes. This should be clearly indicated when displaying such bitmaps to end users. See also How do I convert between logical and OS/physical indexes?

## ◆ hwloc_bitmap_list_sscanf()

int hwloc_bitmap_list_sscanf | ( | hwloc_bitmap_t | bitmap,
|  | const char *restrict | string )

Parse a list string and stores it in bitmap `bitmap`.

Lists are comma-separated indexes or ranges. Ranges are dash separated indexes. String "1,33-34,64-95" 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.

Returns
  0 on success, -1 on error.

Note
  If the bitmap is a CPU or nodeset, the input string must contain physical indexes.

## ◆ hwloc_bitmap_next()

int hwloc_bitmap_next | ( | hwloc_const_bitmap_t | bitmap,
|  | int | prev )

Compute the next index in bitmap `bitmap` which is after index `prev`.

Returns
  the first index set in `bitmap` if `prev` is `-1`.
  the next index set in `bitmap` if `prev` is not `-1`.
  -1 if no index with higher index is set in `bitmap`.

## ◆ hwloc_bitmap_next_unset()

int hwloc_bitmap_next_unset | ( | hwloc_const_bitmap_t | bitmap,
|  | int | prev )

Compute the next unset index in bitmap `bitmap` which is after index `prev`.

Returns
  the first index unset in `bitmap` if `prev` is `-1`.
  the next index unset in `bitmap` if `prev` is not `-1`.
  -1 if no index with higher index is unset in `bitmap`.

## ◆ hwloc_bitmap_not()

int hwloc_bitmap_not | ( | hwloc_bitmap_t | res,
|  | hwloc_const_bitmap_t | bitmap )

Negate bitmap `bitmap` and store the result in bitmap `res`.

`res` can be the same as `bitmap`

## ◆ hwloc_bitmap_nr_ulongs()

int hwloc_bitmap_nr_ulongs | ( | hwloc_const_bitmap_t | bitmap | ) |

Return the number of unsigned longs required for storing bitmap `bitmap` 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 `nr` parameter to pass to hwloc_bitmap_to_ulongs() (or which calls to hwloc_bitmap_to_ith_ulong() are needed) to entirely convert a bitmap into multiple unsigned longs.

When called on the output of hwloc_topology_get_topology_cpuset(), the returned number is large enough for all cpusets of the topology.

Returns
  the number of unsigned longs required.
  -1 if `bitmap` is infinite.

## ◆ hwloc_bitmap_only()

int hwloc_bitmap_only | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | id )

Empty the bitmap `bitmap` and add bit `id`.

## ◆ hwloc_bitmap_or()

int hwloc_bitmap_or | ( | hwloc_bitmap_t | res,
|  | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2 )

Or bitmaps `bitmap1` and `bitmap2` and store the result in bitmap `res`.

`res` can be the same as `bitmap1` or `bitmap2`

## ◆ hwloc_bitmap_set()

int hwloc_bitmap_set | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | id )

Add index `id` in bitmap `bitmap`.

## ◆ hwloc_bitmap_set_ith_ulong()

int hwloc_bitmap_set_ith_ulong | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | i,
|  | unsigned long | mask )

Replace `i` -th subset of bitmap `bitmap` with unsigned long `mask`.

## ◆ hwloc_bitmap_set_range()

int hwloc_bitmap_set_range | ( | hwloc_bitmap_t | bitmap,
|  | unsigned | begin,
|  | int | end )

Add indexes from `begin` to `end` in bitmap `bitmap`.

If `end` is `-1`, the range is infinite.

## ◆ hwloc_bitmap_singlify()

int hwloc_bitmap_singlify | ( | hwloc_bitmap_t | bitmap | ) |

Keep a single index among those set in bitmap `bitmap`.

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.

Note
  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. hwloc_distrib() may be used for generating CPU sets to distribute multiple tasks below a single multi-PU object.
  This function cannot be applied to an object set directly. It should be applied to a copy (which may be obtained with hwloc_bitmap_dup()).

## ◆ hwloc_bitmap_snprintf()

int hwloc_bitmap_snprintf | ( | char *restrict | buf,
|  | size_t | buflen,
|  | hwloc_const_bitmap_t | bitmap )

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 "0xffffffff,0x00000006,0x00000002".

Up to `buflen` characters may be written in buffer `buf`.

If `buflen` is 0, `buf` may safely be `NULL`.

Returns
  the number of characters that were actually written if not truncating, or that would have been written (not including the ending `\0`).
  -1 on error.

Note
  If the bitmap is a CPU or nodeset, it contains physical indexes. This should be clearly indicated when displaying such bitmaps to end users. See also How do I convert between logical and OS/physical indexes?

## ◆ hwloc_bitmap_sscanf()

int hwloc_bitmap_sscanf | ( | hwloc_bitmap_t | bitmap,
|  | const char *restrict | string )

Parse a bitmap string as the default hwloc format and stores it in bitmap `bitmap`.

The input string should be a comma-separared list of hexadecimal 32-bit blocks. String "0xffffffff,0x6,0x2" is parsed as a bitmap containing all bits between 64 and 95, and bits 33, 34 and 1.

Returns
  0 on success, -1 on error.

Note
  If the bitmap is a CPU or nodeset, the input string must contain physical indexes.

## ◆ hwloc_bitmap_taskset_asprintf()

int hwloc_bitmap_taskset_asprintf | ( | char ** | strp,
|  | hwloc_const_bitmap_t | bitmap )

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 "0xffffffff0000000600000002".

Returns
  the number of characters that were written (not including the ending `\0`).
  -1 on error, for instance with `errno` set to `ENOMEM` on failure to allocate the output string.

Note
  If the bitmap is a CPU or nodeset, it contains physical indexes. This should be clearly indicated when displaying such bitmaps to end users. See also How do I convert between logical and OS/physical indexes?

## ◆ hwloc_bitmap_taskset_snprintf()

int hwloc_bitmap_taskset_snprintf | ( | char *restrict | buf,
|  | size_t | buflen,
|  | hwloc_const_bitmap_t | bitmap )

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 "0xffffffff0000000600000002".

Up to `buflen` characters may be written in buffer `buf`.

If `buflen` is 0, `buf` may safely be `NULL`.

Returns
  the number of characters that were actually written if not truncating, or that would have been written (not including the ending `\0`).
  -1 on error.

Note
  If the bitmap is a CPU or nodeset, it contains physical indexes. This should be clearly indicated when displaying such bitmaps to end users. See also How do I convert between logical and OS/physical indexes?

## ◆ hwloc_bitmap_taskset_sscanf()

int hwloc_bitmap_taskset_sscanf | ( | hwloc_bitmap_t | bitmap,
|  | const char *restrict | string )

Parse a taskset-specific bitmap string and stores it in bitmap `bitmap`.

The taskset program manipulates bitmap strings that contain a single (possible very long) hexadecimal number starting with 0x. String "0xffffffff0000000600000002" is parsed as a bitmap containing all bits between 64 and 95, and bits 33, 34 and 1.

Returns
  0 on success, -1 on error.

Note
  If the bitmap is a CPU or nodeset, the input string must contain physical indexes.

## ◆ hwloc_bitmap_to_ith_ulong()

unsigned long hwloc_bitmap_to_ith_ulong | ( | hwloc_const_bitmap_t | bitmap,
|  | unsigned | i )

Convert the `i` -th subset of bitmap `bitmap` into unsigned long mask.

## ◆ hwloc_bitmap_to_ulong()

unsigned long hwloc_bitmap_to_ulong | ( | hwloc_const_bitmap_t | bitmap | ) |

Convert the beginning part of bitmap `bitmap` into unsigned long `mask`.

## ◆ hwloc_bitmap_to_ulongs()

int hwloc_bitmap_to_ulongs | ( | hwloc_const_bitmap_t | bitmap,
|  | unsigned | nr,
|  | unsigned long * | masks )

Convert the first `nr` subsets of bitmap `bitmap` into the array of `nr` unsigned long `masks`.

`nr` may be determined earlier with hwloc_bitmap_nr_ulongs().

Returns
  0

## ◆ hwloc_bitmap_weight()

int hwloc_bitmap_weight | ( | hwloc_const_bitmap_t | bitmap | ) |

Compute the "weight" of bitmap `bitmap` (i.e., number of indexes that are in the bitmap).

Returns
  the number of indexes that are in the bitmap.
  -1 if `bitmap` is infinitely set.

## ◆ hwloc_bitmap_xor()

int hwloc_bitmap_xor | ( | hwloc_bitmap_t | res,
|  | hwloc_const_bitmap_t | bitmap1,
|  | hwloc_const_bitmap_t | bitmap2 )

Xor bitmaps `bitmap1` and `bitmap2` and store the result in bitmap `res`.

`res` can be the same as `bitmap1` or `bitmap2`

## ◆ hwloc_bitmap_zero()

void hwloc_bitmap_zero | ( | hwloc_bitmap_t | bitmap | ) |

Empty the bitmap `bitmap`.