__BITS(3) - NetBSD Manual Pages

Command:
Section:
Arch:
Collection:
>>>
BITS(3)                 NetBSD 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 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.

           __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 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 ALSO

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

NetBSD 10.1                    January 22, 2022                    NetBSD 10.1