bitmask_snprintf(9) - NetBSD Manual Pages

BITMASK_SNPRINTF(9)          NetBSD Kernel Manual          BITMASK_SNPRINTF(9)


NAME

     bitmask_snprintf - bitmask output conversion


SYNOPSIS

     #include <sys/systm.h>

     void
     bitmask_snprintf(u_quad_t val, const char *fmt, char *buf,
             size_t buflen);


DESCRIPTION

     The bitmask_snprintf() 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 in-
     terpreted and displayed.  The first character of fmt is a binary charac-
     ter 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 de-
     scribed.  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 de-
     coding directive string itself.


RETURN VALUES

     The bitmask_snprintf() function returns the buffer buf.  The returned
     string is always NULL-terminated.


EXAMPLES

     Two examples of the old formatting style:

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

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


ERRORS

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


SEE ALSO

     printf(9)


CODE REFERENCES

     sys/kern/subr_prf.c


HISTORY

     The bitmask_snprintf() function was originally implemented as a non-stan-
     dard %b format string for the kernel printf() function in NetBSD 1.5 and
     earlier releases.


BUGS

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

NetBSD 1.6                       July 28, 2000                               2