SNPRINTB(3) | Library Functions Manual | SNPRINTB(3) |
snprintb
, snprintb_m
—
#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);
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
f\B\L
F\B\L
=\V
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
*FMT
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).
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.
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^%d\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"
snprintb
() will fail if:
EINVAL
]snprintf
() failed.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.
April 27, 2019 | NetBSD 9.0 |