hwlocality_bitmap(3)

💖 hwlocality_bitmap(3) — The Bitmap API (part 1 of 3) 💖

okay bestie, this is the hwlocality_bitmap(3) page from the Library Functions Manual, and we’re doing it in three parts. This is part 1, so buckle up. We’re talking about the hwloc bitmap API: sets of integers, CPU sets, node sets, all the good stuff. No cap, it’s a long one. 🫶

---

✨ NAME ✨

hwlocality_bitmap — The bitmap API

That’s it. That’s the name. iconic. 💅

---

🦋 SYNOPSIS 🦋

Here’s the full roster, and yes, I’m keeping every single signature exactly as it appears because we do not mess with the source. 💖

🎀 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 🔥

okay so 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 🌀

🌟 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 — the classic "copy/paste" but make it C

int hwloc_bitmap_copy (hwloc_bitmap_t dst, hwloc_const_bitmap_t src)

Okay so literally just copy the contents of bitmap src into the already allocated bitmap dst. That's it. That's the whole function. No cap. Just make sure dst is already allocated before you call this or it's gonna be a whole situation 😭

---

🦋 hwloc_bitmap_dup — new bitmap, who dis

hwloc_bitmap_t hwloc_bitmap_dup (hwloc_const_bitmap_t bitmap)

Duplicate bitmap bitmap by allocating a new bitmap and copying bitmap contents into it. So like copy but it brings its own memory to the party ✨

And if bitmap is NULL? Then NULL is returned. Respectfully, nothing happens 💅

---

🌸 hwloc_bitmap_fill — fill 'er up

void hwloc_bitmap_fill (hwloc_bitmap_t bitmap)

Fill bitmap bitmap with all possible indexes — and yes, that's even if those objects don't exist or are otherwise unavailable. We're being generous with the vibes here, no vibe check required 👑

---

⭐ hwloc_bitmap_first — 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 — first but make it 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 — release your baggage bestie

void hwloc_bitmap_free (hwloc_bitmap_t bitmap)

Free bitmap bitmap. And if bitmap is NULL? No operation is performed. It's giving "respectfully, nothing" energy 🙈

---

💜 hwloc_bitmap_from_ith_ulong — slice of the ulong pie

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

Setup bitmap bitmap from unsigned long mask used as the i-th subset. iykyk 🍓

---

🌈 hwloc_bitmap_from_ulong — one ulong to rule them all

int hwloc_bitmap_from_ulong (hwloc_bitmap_t bitmap, unsigned long mask)

Setup bitmap bitmap from unsigned long mask. Simple, clean, iconic ✨

---

🔥 hwloc_bitmap_from_ulongs — ulongs, plural, as advertised

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

Setup bitmap bitmap from unsigned longs masks, used as the first nr subsets. Plural behavior for plural uh... longs 💅

---

🫶 hwloc_bitmap_intersects — do these even overlap

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. Not a single one. It's not that kind of bitmap.

---

🌺 hwloc_bitmap_isequal — same energy check

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 — absolutely booked and busy

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. Like, conceptually, no ceiling.

---

🌸 hwloc_bitmap_isincluded — sub/super relationship check

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. It's in every group chat, technically.

---

🦋 hwloc_bitmap_isset — is this bit in the building

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 — empty check

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 — last but definitely not least

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 — last and 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 — stringify, but allocate it for me

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 — stringify into my buffer

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. Good to know bestie 🫶

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 — parse the list back in

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 — what comes after

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 — next, but 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 — flip it and reverse it

int hwloc_bitmap_not (hwloc_bitmap_t res, hwloc_const_bitmap_t bitmap)

Negate bitmap bitmap and store the result in bitmap res. And plot twist: res can be the same as bitmap 🔥

---

🌈 hwloc_bitmap_nr_ulongs — how many longs do I need

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. Big fan of that 🫶

Returns:

• the number of unsigned longs required
• -1 if bitmap is infinite

---

⭐ hwloc_bitmap_only — clear the room, one guest incoming

int hwloc_bitmap_only (hwloc_bitmap_t bitmap, unsigned id)

Empty the bitmap bitmap and add bit id. So like, everyone out, only id stays. Main character energy 👑

---

🧚 hwloc_bitmap_or — the OR era

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. And yes, res can be the same as bitmap1 or bitmap2 💅

---

🍓 hwloc_bitmap_set — add a bit, add a vibe

int hwloc_bitmap_set (hwloc_bitmap_t bitmap, unsigned id)

Add index id in bitmap bitmap. That's it, that's the tweet ✨

---

🎀 hwloc_bitmap_set_ith_ulong — swap a subset

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

Replace the i-th subset of bitmap bitmap with unsigned long mask. Out with the old slice, in with the new 🦋

---

🌸 hwloc_bitmap_set_range — range add, infinite if you want

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

Add indexes from begin to end in bitmap bitmap. And if end is -1, the range is infinite. The audacity, honestly 💀

---

💜 hwloc_bitmap_singlify — one bit to rule them all

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. No more ping-ponging, we love to see it 🔥

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 — default hwloc format, hex blocks

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 — parse the default format back

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-separated 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 — taskset format, very long hex

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)

Okay so this one stringifies your bitmap in the taskset-specific format 💅 and the taskset program is out here manipulating bitmap strings that are literally just a single hexadecimal number (possibly very long, like no cap) starting with 0x. So a bitmap holding bits 1, 33, 34, and everything from 64 to 95 prints out as:

"0xffffffff0000000600000002"

You can write up to buflen characters into the buffer buf. And if buflen is 0, then buf may safely be NULL 🫶 (love that for you).

Returns

• the number of characters that were actually written if it's not truncating, or the number that would have been written (not counting the ending \0), or
• -1 on error 😭

Note — if the bitmap is a CPU or nodeset, it contains physical indexes. This should be clearly indicated when you're displaying such bitmaps to end users, fr. 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)

The reverse vibe check ✨ — this parses a taskset-specific bitmap string and stores it in the bitmap bitmap. Remember the taskset program deals in bitmap strings that are a single (possibly very long) hexadecimal number starting with 0x. So the string "0xffffffff0000000600000002" gets parsed as a bitmap containing all bits between 64 and 95, plus 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)

Converts the i-th subset of bitmap bitmap into an unsigned long mask. That's it, that's the whole thing 💜

---

🌸 hwloc_bitmap_to_ulong

unsigned long hwloc_bitmap_to_ulong (hwloc_const_bitmap_t bitmap)

Converts the beginning part of bitmap bitmap into an unsigned long mask. Just the beginning, bestie, not the whole thing 🌈

---

🎀 hwloc_bitmap_to_ulongs

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

Converts the first nr subsets of bitmap bitmap into the array of nr unsigned long masks. And guess what, you can figure out nr ahead of time with hwloc_bitmap_nr_ulongs() 👑 iykyk

Returns

0

---

⭐ hwloc_bitmap_weight

int hwloc_bitmap_weight (hwloc_const_bitmap_t bitmap)

Computes the "weight" of bitmap bitmap — aka the number of indexes that are in the bitmap. Literally just counting the slay 💅

Returns

• the number of indexes that are in the bitmap, or
• -1 if bitmap is infinitely set 🙈 (yes that's a real possibility, be careful)

---

🔥 hwloc_bitmap_xor

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

XORs bitmaps bitmap1 and bitmap2 and stores the result in bitmap res. And the cute part: res can be the same as bitmap1 or bitmap2 — no copies needed, main character energy ✨

---

🍓 hwloc_bitmap_zero

void hwloc_bitmap_zero (hwloc_bitmap_t bitmap)

Empties the bitmap bitmap. Poof, gone, nothing left 💀🎀

---

👑 Author

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

---

Okay bestie, that's the whole page — every last function, parsed and peddled 💖 This little masterpiece comes straight from Hardware Locality (hwloc), Version 2.15.0, and the page you just devoured is hwlocality_bitmap(3). Doxygen generated it automatically from the source code, so nobody hand-wrote this one for you, but I did rewrite it for you 🫶 Go forth and bitmap responsibly, mwah 💅✨