BITSTRING(3)

💖 BITSTRING(3) — bit-string manipulation macros, bestie edition 💖

okay so this is bitstring.h, the library that gives you the bit-string manipulation macros, and honestly? iconic. the whole friend group is here: bit_alloc, bit_clear, bit_decl, bit_ffs, bit_nclear, bit_nset, bit_set, bitstr_size, bit_test. all of them. no gatekeeping.

---

✨ SYNOPSIS ✨

like, literally just include the header and you're in:

#include <bitstring.h>

then the whole cast, in order:

name = bit_alloc(nbits)
bitstr_t *name;
int nbits;

bit_decl(name, nbits)
bitstr_t name;
int nbits;

bit_clear(name, bit)
bitstr_t name;
int bit;

bit_ffc(name, nbits, value)
bitstr_t name;
int nbits, *value;

bit_ffs(name, nbits, value)
bitstr_t name;
int nbits, *value;

bit_nclear(name, start, stop)
bitstr_t name;
int start, stop;

bit_nset(name, start, stop)
bitstr_t name;
int start, stop;

bit_set(name, bit)
bitstr_t name;
int bit;

bitstr_size(nbits)
int nbits;

bit_test(name, bit)
bitstr_t name;
int bit;

---

🦋 DESCRIPTION 🦋

so these macros operate on strings of bits. that's the whole vibe. let's go one by one 💅

• bit_alloc — returns a pointer of type bitstr_t * to enough space to store nbits bits. slay. but if no space is available it hands you NULL instead, which is the group-chat equivalent of being left on read 😭
• bit_decl — this is the macro that allocates enough space to store nbits bits on the stack. stack girlie behavior, we respect it.
• bitstr_size — returns the number of elements of type bitstr_t that you need to store nbits bits. super useful for copying bit strings, so keep it in your back pocket fr fr.
• bit_clear and bit_set — clear or set the zero-based numbered bit bit, in the bit string name. zero-based!! don't come at me with your 1-indexed nonsense bestie.
• bit_nset and bit_nclear — set or clear the zero-based numbered bits from start to stop, in the bit string name. it's giving bulk edit energy 🔥
• bit_test — evaluates to zero if the zero-based numbered bit bit of bit string name is set, and non-zero otherwise. yes, that's backwards from what your brain wants. yes, it's still correct. no cap.
• bit_ffs — sets *value to the zero-based number of the first bit set in the array of nbits bits referenced by name. and if no bits are set, *value gets set to -1. iykyk.
• bit_ffc — sets *value to the zero-based number of the first bit not set in the array of nbits bits referenced by name. if all the bits are set, value is set to -1. (yep, the manpage says value here, not *value — we're keeping it exactly as written 🎀)

---

🌸 EXAMPLE 🌸

here's a whole lil printer-availability situation, verbatim, because i would never do you dirty by paraphrasing code:

#include <limits.h>
#include <bitstring.h>

#define   LPR_BUSY_BIT        0
#define   LPR_FORMAT_BIT      1
#define   LPR_DOWNLOAD_BIT    2
#define   LPR_AVAILABLE_BIT   9
#define   LPR_MAX_BITS        10

make_lpr_available()
{
     bitstr_t bit_decl(bitlist, LPR_MAX_BITS);
     ...
     bit_nclear(bitlist, 0, LPR_MAX_BITS - 1);
     ...
     if (!bit_test(bitlist, LPR_BUSY_BIT)) {
          bit_clear(bitlist, LPR_FORMAT_BIT);
          bit_clear(bitlist, LPR_DOWNLOAD_BIT);
          bit_set(bitlist, LPR_AVAILABLE_BIT);
     }
}

---

🎀 SEE ALSO 🎀

• malloc(3) — where the actual memory magic comes from, king behavior 👑

---

💀 heads up: bit_test returning zero when the bit is set is the kind of thing that will ruin your whole afternoon if you forget it. write it on your mirror. zero means set. periodt.

---

🫶 okay that's the whole page, bestie — this one's from the 4th Berkeley Distribution, dated December 13, 1989, and it's been serving BITSTRING(3) realness ever since. mwah 💋✨