BITS(3)

✨ BITS(3) ✨

okay bestie, welcome to the Library Functions Manual page for the bits macros. this is the group chat where bitmasks get cute and bitfields get handled. no cap, it's giving useful. 💅

🌸 NAME 🌸

__BIT, __BITS, __MASK, __SHIFTIN, __SHIFTOUT, __SHIFTOUT_MASK — macros for preparing bitmasks and operating on bit fields

🎀 SYNOPSIS 🎀

#include <sys/param.h>
#include <sys/cdefs.h>

uintmax_t
__BIT(n);

uintmax_t
__BITS(m, n);

uintmax_t
__MASK(n);

uintmax_t
__SHIFTIN(v, mask);

uintmax_t
__SHIFTOUT(v, mask);

uintmax_t
__SHIFTOUT_MASK(mask);

🦋 DESCRIPTION 🦋

okay so these macros are literally the main characters when you need to prepare bitmasks, extract bitfields from words, and insert bitfields into words. A “bitfield” is a span of consecutive bits defined by a bitmask, where 1s select the bits in the bitfield. fr fr. 🫶

Use __BIT(), __BITS(), and __MASK() to define bitmasks:

• __BIT(n) — gives you back a bitmask with bit n set, and the least significant bit is bit 0. 👑
• __BITS(m, n) — gives you back a bitmask with bits m through n, inclusive, set. no stress about whether m > n or m <= n, it does not matter. the least significant bit is bit 0. ✨
• __MASK(n) — gives you back a bitmask with the first n bits set, aka bits 0 through n - 1, inclusive. 💖

__SHIFTIN(), __SHIFTOUT(), and __SHIFTOUT_MASK() help read and write bitfields from words:

• __SHIFTIN(v, mask) — left-shifts bits v into the bitfield defined by mask, then returns them. no side-effects. it's giving clean. 🌈
• __SHIFTOUT(v, mask) — pulls out and returns the bitfield selected by mask from v, right-shifting the bits so the rightmost selected bit is at bit 0. no side-effects. 🎀
• __SHIFTOUT_MASK(mask) — right-shifts the bits in mask so the rightmost non-zero bit is at bit 0. this is useful for finding the greatest unsigned value that a bitfield can hold. no side-effects. note that __SHIFTOUT_MASK(m) = __SHIFTOUT(m, m). 💅

🌟 EXAMPLES 🌟

the following example demonstrates basic usage of the bits macros:

uint32_t bits, mask, val;

bits = __BITS(2, 3);                    /* 00001100 */
mask = __BIT(2) | __BIT(3);             /* 00001100 */

val = __SHIFTIN(0x03, mask);            /* 00001100 */
val = __SHIFTOUT(0xf, mask);            /* 00000011 */

🌈 SEE ALSO 🌈

• bitops(3)
• cdefs(3)

📜 HISTORY 📜

the bits macros first appeared in atw(4), with different names and implementation. in their current form these macros appeared in NetBSD 4.0. lowkey iconic. 🧚

👑 AUTHORS 👑

the bits macros were written by David Young <dyoung@NetBSD.org>. Matt Thomas <matt@NetBSD.org> suggested important improvements to the implementation, and contributed the macro names SHIFTIN() and SHIFTOUT(). 💖

---

okay that's the whole page, bestie 🫶 — source/version: Debian, date: January 22, 2022, manual: BITS(3). slay. ✨