BITS(3)

BITS(3) | Library Functions Manual | BITS(3)

# 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

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 `__BIT`(), `__BITS`(), and `__MASK`() 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.

`__SHIFTIN`(), `__SHIFTOUT`(), and `__SHIFTOUT_MASK`() 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).

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

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

January 22, 2022 | NetBSD 10.1