Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

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

NetBSD 10.99                   January 22, 2022                   NetBSD 10.99