use the bitmask_snprintf info which is more complete, and adjust it for
reality.
This commit is contained in:
christos
parent
abe4c2aeb6
commit
930983f9c3
@ -1,4 +1,4 @@
|
||||
.\" $NetBSD: snprintb.3,v 1.6 2008/04/30 13:10:52 martin Exp $
|
||||
.\" $NetBSD: snprintb.3,v 1.7 2008/12/16 23:19:16 christos Exp $
|
||||
.\"
|
||||
.\" Copyright (c) 1998 The NetBSD Foundation, Inc.
|
||||
.\" All rights reserved.
|
||||
@ -27,18 +27,16 @@
|
||||
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
|
||||
.\" POSSIBILITY OF SUCH DAMAGE.
|
||||
.\"
|
||||
.Dd July 28, 2000
|
||||
.Dd December 16, 2008
|
||||
.Dt SNPRINTB 3
|
||||
.Os
|
||||
.Sh NAME
|
||||
.Nm snprintb
|
||||
.Nd bitmask output conversion
|
||||
.Sh LIBRARY
|
||||
.Lb libutil
|
||||
.Sh SYNOPSIS
|
||||
.In util.h
|
||||
.Ft int
|
||||
.Fn "snprintb" "char *buf" "size_t buflen" "const char *fmt" "uint64_t val"
|
||||
.Fn "snprintb" "char *buf" "size_t buflen" "const char *fmt" "u_quad_t val"
|
||||
.Sh DESCRIPTION
|
||||
The
|
||||
.Fn snprintb
|
||||
@ -53,16 +51,39 @@ of size
|
||||
.Fa 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
|
||||
.Fa buf
|
||||
is too small to hold the formatted output,
|
||||
.Fn 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.
|
||||
.Pp
|
||||
The decoding directive string
|
||||
.Fa fmt
|
||||
describes how the bitfield is to be interpreted and displayed.
|
||||
It follows two possible syntaxes, referred to as
|
||||
.Dq old
|
||||
and
|
||||
.Dq new .
|
||||
The main advantage of the
|
||||
.Dq new
|
||||
formatting is that it is capable of handling multi-bit fields.
|
||||
.Pp
|
||||
The first character of
|
||||
.Fa fmt
|
||||
may be
|
||||
.Li \e177 ,
|
||||
indicating that the remainder of the format string follows the
|
||||
.Dq new
|
||||
syntax.
|
||||
The second character
|
||||
.Pq 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
|
||||
.Pq "in C escape-character format"
|
||||
.Pq in C escape-character format
|
||||
are
|
||||
.Li \e10
|
||||
.Pq octal ,
|
||||
@ -75,51 +96,131 @@ and
|
||||
The remaining characters in
|
||||
.Fa fmt
|
||||
are interpreted as a list of bit-position\(endescription pairs.
|
||||
A bit-position\(endescription pair begins with a binary character value
|
||||
that represents the position of the bit being described.
|
||||
From here the syntaxes diverge.
|
||||
.Pp
|
||||
The
|
||||
.Dq old
|
||||
format syntax is series of bit-position\(endescription 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
|
||||
.Pq "octal 40, hexadecimal 20, the ASCII space character"
|
||||
.Pq octal 40, hexadecimal 20, the ASCII space character
|
||||
describes the most significant bit.
|
||||
.Pp
|
||||
The remaining characters in a bit-position\(endescription 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
|
||||
.Pq "distinguishable by its value being \*[Le] 32" ,
|
||||
.Pq distinguishable by its value being \*[Le] 32 ,
|
||||
or the end of the decoding directive string itself.
|
||||
.Pp
|
||||
For the
|
||||
.Dq new
|
||||
format syntax, a bit-position\(endescription 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
|
||||
.Dq old
|
||||
syntax where it is one.
|
||||
.Bl -tag -width "xxxxx"
|
||||
.It Cm b\eB
|
||||
Describes a bit position.
|
||||
The bit-position
|
||||
.Fa B
|
||||
indicates the corresponding bit, as in the
|
||||
.Dq old
|
||||
format.
|
||||
.It Cm f\eB\eL
|
||||
Describes a multi-bit field beginning at bit-position
|
||||
.Fa B
|
||||
and having a bit-length of
|
||||
.Fa L .
|
||||
The remaining characters are printed as a description of the field
|
||||
followed by
|
||||
.Sq \&=
|
||||
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
|
||||
.Ar fmt .
|
||||
.It Cm F\eB\eL
|
||||
Describes a multi-bit field like
|
||||
.Sq f ,
|
||||
but just extracts the value for use with the
|
||||
.Sq \&=
|
||||
and
|
||||
.Sq \&:
|
||||
formatting directives described below.
|
||||
.It Cm \&=\eV
|
||||
The field previously extracted by the last
|
||||
.Sq f
|
||||
or
|
||||
.Sq F
|
||||
operator is compared to the byte
|
||||
.Sq Cm V
|
||||
.Pq for values 0 through 255 .
|
||||
If they are equal,
|
||||
.Sq \&=
|
||||
followed by the string following
|
||||
.Sq Cm V
|
||||
is printed.
|
||||
This and the
|
||||
.Sq \&:
|
||||
operator may be repeated to annotate multiple possible values.
|
||||
.It Cm :\eV
|
||||
Operates like the
|
||||
.Sq \&=
|
||||
operator, but omits the leading
|
||||
.Sq \&= .
|
||||
.El
|
||||
.Pp
|
||||
Finally, each field is delimited by a NUL
|
||||
.Pq Sq \e0
|
||||
character.
|
||||
By convention, the format string has an additional NUL character at
|
||||
the end, following that delimiting the last bit-position\(endescription
|
||||
pair.
|
||||
.Sh RETURN VALUES
|
||||
The
|
||||
.Fn snprintb
|
||||
function returns the number of characters that are required to format the
|
||||
value
|
||||
.Fa val
|
||||
given the format string
|
||||
.Fa fmt
|
||||
excluding the terminating NUL.
|
||||
The returned string in
|
||||
.Fa buf
|
||||
is always NUL-terminated.
|
||||
function returns the number of bytes that would have written to the buffer
|
||||
if there was adequate space, excluding the terminating NUL, or -1 in case
|
||||
an error occurred.
|
||||
.Sh EXAMPLES
|
||||
Two examples of the old formatting style:
|
||||
.Bd -literal -offset indent
|
||||
snprintb(buf, buflen, "\e10\e2BITTWO\e1BITONE", 3)
|
||||
snprintb(3, "\e10\e2BITTWO\e1BITONE", buf, buflen)
|
||||
\(rA "3\*[Lt]BITTWO,BITONE\*[Gt]"
|
||||
|
||||
snprintb(buf, buflen
|
||||
snprintb(0xe860,
|
||||
"\e20\ex10NOTBOOT\ex0fFPP\ex0eSDVMA\ex0cVIDEO"
|
||||
"\ex0bLORES\ex0aFPA\ex09DIAG\ex07CACHE"
|
||||
"\ex06IOCACHE\ex05LOOPBACK\ex04DBGCACHE",
|
||||
0xe860)
|
||||
\(rA "0xe860\*[Lt]NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE\*[Gt]"
|
||||
buf, buflen)
|
||||
\(rA "e860\*[Lt]NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE\*[Gt]"
|
||||
.Ed
|
||||
.Pp
|
||||
An example of the new formatting style:
|
||||
.Bd -literal -offset indent
|
||||
snprintb(0x800f0701,
|
||||
"\e177\e020b\e0LSB\e0b\e1_BITONE\e0f\e4\e4NIBBLE2\e0"
|
||||
"f\ex10\e4BURST\e0=\e4FOUR\e0=\exfSIXTEEN\e0"
|
||||
"b\ex1fMSB\e0\e0",
|
||||
buf, buflen)
|
||||
\(rA "800f0701\*[Lt]LSB,NIBBLE2=0,BURST=f=SIXTEEN,MSB\*[Gt]"
|
||||
.Ed
|
||||
.Pp
|
||||
.Sh ERRORS
|
||||
If the buffer
|
||||
.Fa buf
|
||||
is too small to hold the formatted output,
|
||||
.Fn snprintb
|
||||
will still return the buffer, containing a truncated string.
|
||||
will fail if:
|
||||
.Bl -tag -width Er
|
||||
.It Bq Er EINVAL
|
||||
The leading character does not describe a supported format,
|
||||
or
|
||||
.Fn snprintf
|
||||
failed.
|
||||
.El
|
||||
.Sh SEE ALSO
|
||||
.Xr printf 3
|
||||
.Xr snprintf 3
|
||||
.Sh HISTORY
|
||||
The
|
||||
@ -131,13 +232,13 @@ format string for the kernel
|
||||
function in
|
||||
.Nx 1.5
|
||||
and earlier releases.
|
||||
It got implemented as
|
||||
.Fn bitmap_snprintf
|
||||
for
|
||||
.Nx 1.6
|
||||
and this version was used to implement
|
||||
.Fn snprintb .
|
||||
.Sh BUGS
|
||||
.Fn snprintb
|
||||
supports a new extended form of formatting string, which is not yet
|
||||
described here.
|
||||
It was called
|
||||
.Fn bitmask_snprintf
|
||||
in
|
||||
.Nx 5.0
|
||||
and earlier releases.
|
||||
.Sh AUTHORS
|
||||
The
|
||||
.Dq new
|
||||
format was the invention of
|
||||
.An Chris Torek .
|
||||
|
||||
Loading…
Reference in New Issue
Block a user