Module Name: src
Committed By: uwe
Date: Sun Jan 21 23:44:30 UTC 2024
Modified Files:
src/lib/libutil: snprintb.3
Log Message:
snprintb(3): try to improve narration
Try to make the narration more coherent. Make the old and new
syntaxes easy to distinguish and go out of our way to highlight that
the old syntax uses 1-based bit positions.
To generate a diff of this commit:
cvs rdiff -u -r1.26 -r1.27 src/lib/libutil/snprintb.3
Please note that diffs are not public domain; they are subject to the
copyright notices on the relevant files.
Modified files:
Index: src/lib/libutil/snprintb.3
diff -u src/lib/libutil/snprintb.3:1.26 src/lib/libutil/snprintb.3:1.27
--- src/lib/libutil/snprintb.3:1.26 Sun Jan 21 22:06:46 2024
+++ src/lib/libutil/snprintb.3 Sun Jan 21 23:44:30 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: snprintb.3,v 1.26 2024/01/21 22:06:46 rillig Exp $
+.\" $NetBSD: snprintb.3,v 1.27 2024/01/21 23:44:30 uwe Exp $
.\"
.\" Copyright (c) 1998 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -57,14 +57,46 @@ 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.
+The buffer is always
+.Tn NUL Ns -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 it would have written if the buffer were long enough excluding the
-terminating NUL.
+terminating
+.Tn NUL .
+.Pp
+The
+.Fn snprintb_m
+function accepts an additional
+.Fa max
+argument.
+If this argument is zero, the
+.Fn snprintb_m
+function returns exactly the same results in the
+.Fa buf
+as the
+.Fn snprintb
+function.
+If the
+.Fa max
+argument has a non-zero value, it represents the maximum length of a
+formatted string.
+If the formatted string would require more than
+.Fa max
+characters, the
+.Fn snprintb_m
+function returns multiple formatted strings in the output buffer
+.Fa buf .
+Each string is
+.Tn NUL Ns -terminated ,
+and the last string is followed by an
+additional
+.Tn NUL
+character
+.Pq or, if you prefer, a zero-length string .
.Pp
The decoding directive string
.Fa fmt
@@ -80,7 +112,7 @@ formatting is that it is capable of hand
The first character of
.Fa fmt
may be
-.Li \e177 ,
+.Ql \e177 ,
indicating that the remainder of the format string follows the
.Dq new
syntax.
@@ -91,142 +123,143 @@ output numeral base in which the bitfiel
Recognized radix values
.Pq in C escape-character format
are
-.Li \e10
+.Ql \e10
.Pq octal ,
-.Li \e12
+.Ql \e12
.Pq decimal ,
and
-.Li \e20
+.Ql \e20
.Pq hexadecimal .
.Pp
The remaining characters in
.Fa fmt
are interpreted as a list of bit-position\(endescription pairs.
From here the syntaxes diverge.
+.
+.Ss Old Syntax
.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.
+.Pp
+Each description begins with a binary character value that represents
+the position of the bit being described.
+.Pp
+.Sy NB :
+the bit positions in the old syntax are
+.Em 1-based\^ !
+A bit position value of 1
+.Pq Ql \e1
+describes the least significant bit.
Whereas a position value of 32
-.Pq octal 40, hexadecimal 20, the ASCII space character
+.Po octal
+.Ql \e040 ,
+hexadecimal
+.Ql \ex20 ,
+the ASCII space character
+.Pc
describes the most significant bit.
+The old syntax is limited to 32-bit values.
+.Pp
+The remaining characters are the description to print should the bit
+being described be set.
.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 ,
or the end of the decoding directive string itself.
+.
+.Ss New Syntax
.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
+format syntax, a field description begins with a field type followed
+by a binary field position and possibly a field length.
+The bit positions are 0-based,
+the least significant bit is bit-position zero.
+Each description is terminated by a
+.Tn NUL
+byte.
+.
+.Bl -tag -width Cm
+.
+.It Cm b\e Ns Ar B
+Describes a single bit at bit-position
+.Ar B .
+The remaining characters are the description to print should the bit
+being described be set.
+This field description is similar in function to the old format.
+When converting old formats to the new syntax don't forget that the
+new syntax uses zero-based bit positions.
+.
+.It Cm f\e Ns Ar B Ns Cm \e Ns Ar L
Describes a multi-bit field beginning at bit-position
-.Fa B
+.Ar B
and having a bit-length of
-.Fa L .
+.Ar L .
The remaining characters are printed as a description of the field
followed by
-.Sq \&=
+.Ql \&=
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
+.
+.It Cm F\e Ns Ar B Ns Cm \e Ns Ar L
Describes a multi-bit field like
-.Sq f ,
+.Sq Cm f ,
but just extracts the value for use with the
-.Sq \&=
+.Sq Cm \&=
and
-.Sq \&:
+.Sq Cm \&:
formatting directives described below.
-.It Cm \&=\eV
+.
+.It Cm \&=\e Ns Ar V
The field previously extracted by the last
-.Sq f
+.Sq Cm f
or
-.Sq F
-operator is compared to the byte
-.Sq Cm V
+.Sq Cm F
+directive is compared to the byte value
+.Ar V
.Pq for values 0 through 255 .
If they are equal,
-.Sq \&=
+.Ql \&=
followed by the string following
-.Sq Cm V
+.Ar V
is printed.
This and the
-.Sq \&:
-operator may be repeated to annotate multiple possible values.
-.It Cm :\eV
+.Sq Cm \&:
+directive may be repeated to annotate multiple possible values.
+.
+.It Cm \&:\e Ns Ar V
Operates like the
-.Sq \&=
-operator, but omits the leading
-.Sq \&= .
-.It Cm *FMT
+.Sq Cm \&=
+directive, but omits the leading
+.Ql \&= .
+.
+.It Cm * Ns Ar FMT
This provides a
.Dq default
-case that prints
-.Ar FMT
-using
+case that prints the extracted field value using
.Xr printf 3
+format
+.Ar FMT
when other
-.Sq \&:
+.Sq Cm \&:
or
-.Sq \&=
-have not matched.
+.Sq Cm \&=
+directives have not matched.
.Ar FMT
may contain a
-.Ft uintmax_t
+.Vt uintmax_t
format specification that prints the value that
did not match, since the field can be more than 32 bits wide.
.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.
-.Pp
-The
-.Fn snprintb_m
-function accepts an additional
-.Fa max
-argument.
-If this argument is zero, the
-.Fn snprintb_m
-function returns exactly the same results in the
-.Fa buf
-as the
-.Fn snprintb
-function.
-If the
-.Fa 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
-.Fa max
-characters, the
-.Fn snprintb_m
-function returns multiple formatted strings in the output buffer
-.Fa 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).
+The new format string is terminated by an additional
+.Tn NUL
+character at the end, following that delimiting the last
+bit-position\(endescription pair.
.Sh RETURN VALUES
The
.Fn snprintb
