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);
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 would have written if the buffer was 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 ‘=’.
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>"
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.