---
name: "hwlocality_bitmap"
section: "3"
platform: "linux"
package: "hwloc"
version: "2.15.0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux"]
url: "https://new.carta.tech/hwlocality_bitmap"
---

# hwlocality\_bitmap(3)

The bitmap API

## NAME

hwlocality\_bitmap - The bitmap API

## SYNOPSIS

### 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);
```

**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

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

### #define hwloc\_bitmap\_foreach\_end()

End of loop macro iterating on a bitmap. Needs a terminating ';'.

**See also**

**hwloc\_bitmap\_foreach\_begin()**

## Typedef Documentation

### typedef struct hwloc\_bitmap\_s\* hwloc\_bitmap\_t

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

### typedef const struct hwloc\_bitmap\_s\* hwloc\_const\_bitmap\_t

a non-modifiable **hwloc\_bitmap\_t**

## Function Documentation

### int hwloc\_bitmap\_allbut (hwloc\_bitmap\_t bitmap, unsigned id)

Fill the bitmap and clear the index id.

### 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\_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()**.

### 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

### 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

### 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?**

### int hwloc\_bitmap\_clr (hwloc\_bitmap\_t bitmap, unsigned id)

Remove index id from bitmap bitmap.

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

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

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

### 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\_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.

### 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).

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

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

### void hwloc\_bitmap\_free (hwloc\_bitmap\_t bitmap)

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

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

### int hwloc\_bitmap\_from\_ulong (hwloc\_bitmap\_t bitmap, unsigned long mask)

Setup bitmap bitmap from unsigned long mask.

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

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

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

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

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

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

### int hwloc\_bitmap\_iszero (hwloc\_const\_bitmap\_t bitmap)

Test whether bitmap bitmap is empty.

**Returns**

1 if bitmap is empty, 0 otherwise.

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

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

### 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?**

### 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?**

### 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.**

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

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

### 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

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

### int hwloc\_bitmap\_only (hwloc\_bitmap\_t bitmap, unsigned id)

Empty the bitmap bitmap and add bit id.

### 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

### int hwloc\_bitmap\_set (hwloc\_bitmap\_t bitmap, unsigned id)

Add index id in bitmap bitmap.

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

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

### 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()**).

### 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?**

### 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.**

### 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?**

### 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?**

### 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.**

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

### unsigned long hwloc\_bitmap\_to\_ulong (hwloc\_const\_bitmap\_t bitmap)

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

### 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

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

### 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

### void hwloc\_bitmap\_zero (hwloc\_bitmap\_t bitmap)

Empty the bitmap bitmap.

## Author

Generated automatically by Doxygen for Hardware Locality (hwloc) from the source code.