Updated: 2022/Sep/29

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


SNPRINTB(3)                Library Functions Manual                SNPRINTB(3)

NAME
     snprintb, snprintb_m - bitmask output conversion

LIBRARY
     System Utilities Library (libutil, -lutil)

SYNOPSIS
     #include <util.h>

     int
     snprintb(char *buf, size_t buflen, const char *fmt, uint64_t val);

     int
     snprintb_m(char *buf, size_t buflen, const char *fmt, uint64_t val,
         size_t max);

DESCRIPTION
     The snprintb() function formats a bitmask into a mnemonic form suitable
     for printing.

     This conversion is useful for decoding bit fields in device registers.
     It formats the integer val into the buffer buf, of size buflen, using a
     specified radix and an interpretation of the bits within that integer as
     though they were flags.  The buffer is always NUL-terminated.  If the
     buffer buf is too small to hold the formatted output, snprintb() will
     fill as much as it can, and return the number of bytes that it would have
     written if the buffer were long enough excluding the terminating NUL.

     The decoding directive string fmt describes how the bitfield is to be
     interpreted and displayed.  It follows two possible syntaxes, referred to
     as "old" and "new".  The main advantage of the "new" formatting is that
     it is capable of handling multi-bit fields.

     The first character of fmt may be \177, indicating that the remainder of
     the format string follows the "new" syntax.  The second character (the
     first for the old format) is a binary character representation of the
     output numeral base in which the bitfield will be printed before it is
     decoded.  Recognized radix values (in C escape-character format) are \10
     (octal), \12 (decimal), and \20 (hexadecimal).

     The remaining characters in fmt are interpreted as a list of bit-
     position-description pairs.  From here the syntaxes diverge.

     The "old" format syntax is series of bit-position-description pairs.
     Each begins with a binary character value that represents the position of
     the bit being described.  A bit position value of one describes the least
     significant bit.  Whereas a position value of 32 (octal 40, hexadecimal
     20, the ASCII space character) describes the most significant bit.

     The remaining characters in a bit-position-description pair are the
     characters to print should the bit being described be set.  Description
     strings are delimited by the next bit position value character
     encountered (distinguishable by its value being <= 32), or the end of the
     decoding directive string itself.

     For the "new" format syntax, a bit-position-description begins with a
     field type followed by a binary bit-position and possibly a field length.
     The least significant bit is bit-position zero, unlike the "old" syntax
     where it is one.

     b\B    Describes a bit position.  The bit-position B indicates the
            corresponding bit, as in the "old" format.

     f\B\L  Describes a multi-bit field beginning at bit-position B and having
            a bit-length of L.  The remaining characters are printed as a
            description of the field followed by `=' and the value of the
            field.  The value of the field is printed in the base specified as
            the second character of the decoding directive string fmt.

     F\B\L  Describes a multi-bit field like `f', but just extracts the value
            for use with the `=' and `:' formatting directives described
            below.

     =\V    The field previously extracted by the last `f' or `F' operator is
            compared to the byte `V' (for values 0 through 255).  If they are
            equal, `=' followed by the string following `V' is printed.  This
            and the `:' operator may be repeated to annotate multiple possible
            values.

     :\V    Operates like the `=' operator, but omits the leading `='.

     *FMT   This provides a "default" case that prints FMT using printf(3)
            when other `:' or `=' have not matched.  FMT may contain a
            uintmax_t format specification that prints the value that did not
            match, since the field can be more than 32 bits wide.

     Finally, each field is delimited by a NUL (`\0') character.  By
     convention, the format string has an additional NUL character at the end,
     following that delimiting the last bit-position-description pair.

     The snprintb_m() function accepts an additional max argument.  If this
     argument is zero, the snprintb_m() function returns exactly the same
     results in the buf as the snprintb() function.  If the max argument is
     present and has a non-zero value, it represents the maximum length of a
     formatted string.  If the formatted string would require more than max
     characters, the snprintb_m() function returns multiple formatted strings
     in the output buffer buf.  Each string is NUL-terminated, and the last
     string is followed by an additional NUL character (or, if you prefer, a
     zero-length string).

RETURN VALUES
     The snprintb() and snprintb_m() functions return the number of bytes that
     would have written to the buffer if there was adequate space, excluding
     the final terminating NUL, or -1 in case an error occurred.  For
     snprintb_m(), the NUL characters terminating each individual string are
     included in the total number of bytes.

EXAMPLES
     Two examples of the old formatting style:

           snprintb(buf, buflen, "\10\2BITTWO\1BITONE", 3)
           => "03<BITTWO,BITONE>"

           snprintb(buf, buflen,
                  "\20\x10NOTBOOT\x0f" "FPP\x0eSDVMA\x0cVIDEO"
                  "\x0bLORES\x0a" "FPA\x09" "DIAG\x07" "CACHE"
                  "\x06IOCACHE\x05LOOPBACK\x04" "DBGCACHE",
                  0xe860)
           => "0xe860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>"

     An example of the new formatting style:

           snprintb(buf, buflen,
                  "\177\020b\0LSB\0b\1_BITONE\0f\4\4NIBBLE2\0"
                  "f\x10\4BURST\0=\4FOUR\0=\xfSIXTEEN\0"
                  "b\x1fMSB\0\0",
                  0x800f0701)
           => "0x800f0701<LSB,NIBBLE2=0x0,BURST=0xf=SIXTEEN,MSB>"

     A more complex example from <sys/mman.h> that uses the both bit position
     `b' formatting as well as the `F' multi-field formatting with a default
     case:

           #define MAP_FMT "\177\020\
           b\0SHARED\0\
           b\1PRIVATE\0\
           b\2COPY\0\
           b\4FIXED\0\
           b\5RENAME\0\
           b\6NORESERVE\0\
           b\7INHERIT\0\
           b\11HASSEMAPHORE\0\
           b\12TRYFIXED\0\
           b\13WIRED\0\
           F\14\1\0\
           :\0FILE\0\
           :\1ANONYMOUS\0\
           b\15STACK\0\
           F\30\010\0\
           :\000ALIGN=NONE\0\
           :\012ALIGN=1KB\0\
           :\013ALIGN=2KB\0\
           :\014ALIGN=4KB\0\
           :\015ALIGN=8KB\0\
           :\016ALIGN=16KB\0\
           :\017ALIGN=32KB\0\
           :\020ALIGN=64KB\0\
           :\021ALIGN=128KB\0\
           :\022ALIGN=256KB\0\
           :\023ALIGN=512KB\0\
           :\024ALIGN=1MB\0\
           :\030ALIGN=16MB\0\
           :\034ALIGN=256MB\0\
           :\040ALIGN=4GB\0\
           :\044ALIGN=64GB\0\
           :\050ALIGN=1TB\0\
           :\054ALIGN=16TB\0\
           :\060ALIGN=256TB\0\
           :\064ALIGN=4PB\0\
           :\070ALIGN=64PB\0\
           :\074ALIGN=256PB\0\
           *ALIGN=2^%jd\0\
           "
           snprintb(buf, buflen, MAP_FMT, 0x0d001234)
           => "0xd001234<COPY,FIXED,RENAME,HASSEMAPHORE,ANONYMOUS,ALIGN=8KB>"
           snprintb(buf, buflen, MAP_FMT, 0x2e000000)
           => "0xd001234<0x2e000000<FILE,ALIGN=2^46>

     An example using snprintb_m:

           snprintb_m(buf, buflen,
                  "\177\020b\0LSB\0b\1_BITONE\0f\4\4NIBBLE2\0"
                  "f\x10\4BURST\0=\4FOUR\0=\xfSIXTEEN\0"
                  "b\x1fMSB\0\0",
                  0x800f0701, 34)
           => "0x800f0701<LSB,NIBBLE2=0x0>\00x800f0701<BURST=0xf=SIXTEEN,MSB>\0"

ERRORS
     snprintb() will fail if:

     [EINVAL]           The leading character does not describe a supported
                        format, or snprintf() failed.

SEE ALSO
     printf(3), snprintf(3)

HISTORY
     The snprintb() function was originally implemented as a non-standard %b
     format string for the kernel printf() function in NetBSD 1.5 and earlier
     releases.  It was called bitmask_snprintf() in NetBSD 5.0 and earlier
     releases.

AUTHORS
     The "new" format was the invention of Chris Torek.

NetBSD 10.99                   December 6, 2019                   NetBSD 10.99