BITS(3) Library Functions Manual BITS(3)

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

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

These macros 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.

Use (), (), and () to define bitmasks:

__BIT(n)
Return a bitmask with bit n set, where the least significant bit is bit 0.
__BITS(m, n)
Return a bitmask with bits m through n, inclusive, set. It does not matter whether m > n or m <= n. The least significant bit is bit 0.
__MASK(n)
Return a bitmask with the first n bits set. That is, bits 0 through n - 1, inclusive, set.

(), (), and () help read and write bitfields from words:

__SHIFTIN(v, mask)
Left-shift bits v into the bitfield defined by mask, and return them. No side-effects.
__SHIFTOUT(v, mask)
Extract and return the bitfield selected by mask from v, right-shifting the bits so that the rightmost selected bit is at bit 0. No side-effects.
__SHIFTOUT_MASK(mask)
Right-shift the bits in mask so that 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).

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

bitops(3), cdefs(3)

The bits macros first appeared in atw(4), with different names and implementation. In their current form these macros appeared in NetBSD 4.0.

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

January 22, 2022 NetBSD 11.0