SNPRINTB(3)             NetBSD Library Functions Manual            SNPRINTB(3)

NAME
     snprintb -- 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);

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 decoding directive string fmt describes how the bitfield is to be
     interpreted and displayed.  The first character of fmt is a binary char-
     acter 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-posi-
     tion-description pairs.  A bit-position-description pair 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 char-
     acters to print should the bit being described be set.  Description
     strings are delimited by the next bit position value character encoun-
     tered (distinguishable by its value being <= 32), or the end of the
     decoding directive string itself.

RETURN VALUES
     The snprintb() function returns the number of characters that are
     required to format the value val given the format string fmt excluding
     the terminating NUL.  The returned string in buf is always NUL-termi-
     nated.

EXAMPLES
     Two examples of the old formatting style:

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

           snprintb(buf, buflen
                  "\20\x10NOTBOOT\x0fFPP\x0eSDVMA\x0cVIDEO"
                  "\x0bLORES\x0aFPA\x09DIAG\x07CACHE"
                  "\x06IOCACHE\x05LOOPBACK\x04DBGCACHE",
                  0xe860)
           => "0xe860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>"

ERRORS
     If the buffer buf is too small to hold the formatted output, snprintb()
     will still return the buffer, containing a truncated string.

SEE ALSO
     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 got implemented as bitmap_snprintf() for NetBSD 1.6 and
     this version was used to implement snprintb().

BUGS
     snprintb() supports a new extended form of formatting string, which is
     not yet described here.

NetBSD 5.0_STABLE                July 28, 2000               NetBSD 5.0_STABLE
