BITS(3) BSD Library Functions Manual BITS(3)NAME
__BIT, __BITS, __SHIFTIN, __SHIFTOUT, __SHIFTOUT_MASK — macros for pre‐
paring bitmasks and operating on bit fields
SYNOPSIS
#include <sys/param.h>
#include <sys/cdefs.h>
uintmax_t
__BIT(n);
uintmax_t
__BITS(m, n);
__SHIFTIN(v, mask);
__SHIFTOUT(v, mask);
__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() and __BITS() to define bitmasks:
__BIT(n)
Return a bitmask with bit n set, where the least signifi‐
cant 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 signif‐
icant bit is bit 0.
__SHIFTIN(), __SHIFTOUT(), and __SHIFTOUT_MASK() help read and write bit‐
fields 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 right‐
most 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 bit‐
field 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 ALSObitops(3), cdefs(3)HISTORY
The bits macros first appeared in atw(4), with different names and imple‐
mentation. 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().
BUGS__BIT() and __BITS() can only express 32-bit bitmasks.
BSD October 17, 2012 BSD
