Module Name: src
Committed By: rillig
Date: Mon Apr 8 21:28:36 UTC 2024
Modified Files:
src/lib/libutil: snprintb.3
src/tests/lib/libutil: t_snprintb.c
Log Message:
snprintb.3: provide examples for hexadecimal character escapes
Suggested by uwe@, in reaction to the previous commit, which preferred
octal in the examples. Hexadecimal escapes are more familiar to most
programmers, and the chance of mistaking \x14 for decimal 14 is less
than the chance of mistaking octal \014 for decimal 14.
To generate a diff of this commit:
cvs rdiff -u -r1.38 -r1.39 src/lib/libutil/snprintb.3
cvs rdiff -u -r1.35 -r1.36 src/tests/lib/libutil/t_snprintb.c
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.38 src/lib/libutil/snprintb.3:1.39
--- src/lib/libutil/snprintb.3:1.38 Sun Apr 7 14:28:26 2024
+++ src/lib/libutil/snprintb.3 Mon Apr 8 21:28:35 2024
@@ -1,4 +1,4 @@
-.\" $NetBSD: snprintb.3,v 1.38 2024/04/07 14:28:26 rillig Exp $
+.\" $NetBSD: snprintb.3,v 1.39 2024/04/08 21:28:35 rillig Exp $
.\"
.\" Copyright (c) 1998, 2024 The NetBSD Foundation, Inc.
.\" All rights reserved.
@@ -27,7 +27,7 @@
.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
.\" POSSIBILITY OF SUCH DAMAGE.
.\"
-.Dd April 7, 2024
+.Dd April 8, 2024
.Dt SNPRINTB 3
.Os
.Sh NAME
@@ -118,7 +118,10 @@ the bit positions are 0-based.
If the first character of
.Fa fmt
is
-.Ql \e177 ,
+.Pq in C escape-character format
+.Ql \e177
+or
+.Ql \ex7f ,
the remainder of the
.Fa fmt
argument follows the
@@ -131,14 +134,18 @@ The next character
format
.Pc
specifies the numeral base in which to print the numbers in the output.
-The possible values
-.Pq in C escape-character format
-are
+The possible values are
.Ql \e010
+or
+.Ql \ex08
for octal,
.Ql \e012
+or
+.Ql \ex0a
for decimal, and
.Ql \e020
+or
+.Ql \ex10
for hexadecimal.
.Pp
The remaining characters in the
@@ -160,8 +167,12 @@ and a description that is printed if the
The bit position is a 1-based single-byte binary value,
ranging from
.Ql \e001
+or
+.Ql \ex01
(1) for the least significant bit up to
.Ql \e040
+or
+.Ql \ex20
(32) for the most significant bit.
.Pp
The description is delimited by the next character whose value is 32 or less
@@ -182,8 +193,12 @@ followed by a
The bit positions are 0-based,
ranging from
.Ql \e000
+or
+.Ql \ex00
(0) for the least significant bit to
.Ql \e077
+or
+.Ql \ex3f
(63) for the most significant bit.
.
.Bl -tag -width Cm
@@ -212,6 +227,26 @@ and
.Sq Cm \&*
conversions below.
.
+.It Cm \&= Ar cmp Ar descr
+Compares the field value from the previous
+.Sq Cm f
+conversion to the single-byte value
+.Ar cmp ,
+ranging from
+.Ql \e000
+or
+.Ql \ex00
+(0) to
+.Ql \e377
+or
+.Ql \exff
+(255).
+If they are equal, prints
+.Ql \&=
+followed by the description from
+.Ar descr .
+This conversion may be repeated.
+.
.It Cm F Ar lsb Ar width Op Ar descr
Describes a multi-bit field like
.Sq Cm f ,
@@ -225,24 +260,20 @@ The description from
is ignored,
it is only present for uniformity with the other conversions.
.
-.It Cm \&= Ar cmp Ar descr
-Compares the field value from the previous
-.Sq Cm f
-conversion to the single-byte value
-.Ar cmp ,
-which ranges from 0 to 255.
-If they are equal, prints
-.Ql \&=
-followed by the description from
-.Ar descr .
-This conversion may be repeated.
-.
.It Cm \&: Ar cmp Ar descr
Compares the field value from the previous
.Sq Cm F
conversion to the single-byte value
.Ar cmp ,
-which ranges from 0 to 255.
+ranging from
+.Ql \e000
+or
+.Ql \ex00
+(0) to
+.Ql \e377
+or
+.Ql \exff
+(255).
If they are equal, prints the description from
.Ar descr .
This conversion may be repeated.
@@ -255,7 +286,7 @@ or
conversions matched, prints the format string
.Ar fmt
via
-.Xr printf 3 .
+.Xr snprintf 3 .
The format string
.Ar fmt
may contain a single
@@ -289,11 +320,18 @@ snprintb(buf, bufsize, "\e010\e002BITTWO
\(rA "03<BITTWO,BITONE>"
snprintb(buf, bufsize,
- "\e020"
- "\ex10""NOTBOOT" "\ex0f""FPP" "\ex0e""SDVMA"
- "\ex0c""VIDEO" "\ex0b""LORES" "\ex0a""FPA"
- "\ex09""DIAG" "\ex07""CACHE" "\ex06""IOCACHE"
- "\ex05""LOOPBACK" "\ex04""DBGCACHE",
+ "\ex10"
+ "\ex10" "NOTBOOT"
+ "\ex0f" "FPP"
+ "\ex0e" "SDVMA"
+ "\ex0c" "VIDEO"
+ "\ex0b" "LORES"
+ "\ex0a" "FPA"
+ "\ex09" "DIAG"
+ "\ex07" "CACHE"
+ "\ex06" "IOCACHE"
+ "\ex05" "LOOPBACK"
+ "\ex04" "DBGCACHE",
0xe860)
\(rA "0xe860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>"
.Ed
@@ -302,9 +340,13 @@ An example of the new formatting style:
.Bd -literal -offset indent
snprintb(buf, bufsize,
"\e177\e020"
- "b\e000LSB\e0" "b\e001BITONE\e0" "f\e004\e004NIBBLE2\e0"
- "f\e020\e004BURST\e0" "=\e004FOUR\e0" "=\e017FIFTEEN\e0"
- "b\e037MSB\e0",
+ "b\e000" "LSB\e0"
+ "b\e001" "BITONE\e0"
+ "f\e004\e004" "NIBBLE2\e0"
+ "f\e020\e004" "BURST\e0"
+ "=\ex04" "FOUR\e0"
+ "=\ex0f" "FIFTEEN\e0"
+ "b\e037" "MSB\e0",
0x800f0701)
\(rA "0x800f0701<LSB,NIBBLE2=0,BURST=0xf=FIFTEEN,MSB>"
.Ed
@@ -313,9 +355,13 @@ The same example using snprintb_m:
.Bd -literal -offset indent
snprintb_m(buf, bufsize,
"\e177\e020"
- "b\e000LSB\e0" "b\e001BITONE\e0" "f\e004\e004NIBBLE2\e0"
- "f\e020\e004BURST\e0" "=\e004FOUR\e0" "=\e017FIFTEEN\e0"
- "b\e037MSB\e0",
+ "b\e000" "LSB\e0"
+ "b\e001" "BITONE\e0"
+ "f\e004\e004" "NIBBLE2\e0"
+ "f\e020\e004" "BURST\e0"
+ "=\ex04" "FOUR\e0"
+ "=\ex0f" "FIFTEEN\e0"
+ "b\e037" "MSB\e0",
0x800f0701, 34)
\(rA "0x800f0701<LSB,NIBBLE2=0>\e0"
"0x800f0701<BURST=0xf=FIFTEEN,MSB>\e0"
@@ -324,12 +370,12 @@ snprintb_m(buf, bufsize,
.Pp
A more complex example from
.In sys/mman.h
-that uses both the bit position
+that uses both the single-bit
.Sq Cm b
-formatting as well as the
+formatting as well as the multi-bit field
.Sq Cm F
-multibit field formatting with a default case
-.Pq Sq Cm \&* :
+formatting with a default
+.Sq Cm \&* :
.Bd -literal -offset indent
#define MAP_FMT "\e177\e020" \e
"b\e0" "SHARED\e0" \e
@@ -407,7 +453,6 @@ or
failed.
.El
.Sh SEE ALSO
-.Xr printf 3 ,
.Xr snprintf 3
.Sh HISTORY
The
@@ -429,3 +474,10 @@ The
.Dq new
format was the invention of
.An Chris Torek .
+.Sh CAVEATS
+When using hexadecimal character escapes for bit positions or field widths,
+if a following description starts with one of the letters A to F,
+that letter is considered part of the character escape.
+In such a situation, the character escape and the description must be
+put into separate string literals, as in
+.Li \[dq]\ex0f\[dq] \[dq]FIFTEEN\[dq] .
Index: src/tests/lib/libutil/t_snprintb.c
diff -u src/tests/lib/libutil/t_snprintb.c:1.35 src/tests/lib/libutil/t_snprintb.c:1.36
--- src/tests/lib/libutil/t_snprintb.c:1.35 Sun Apr 7 15:20:17 2024
+++ src/tests/lib/libutil/t_snprintb.c Mon Apr 8 21:28:35 2024
@@ -1,4 +1,4 @@
-/* $NetBSD: t_snprintb.c,v 1.35 2024/04/07 15:20:17 rillig Exp $ */
+/* $NetBSD: t_snprintb.c,v 1.36 2024/04/08 21:28:35 rillig Exp $ */
/*
* Copyright (c) 2002, 2004, 2008, 2010, 2024 The NetBSD Foundation, Inc.
@@ -32,7 +32,7 @@
#include <sys/cdefs.h>
__COPYRIGHT("@(#) Copyright (c) 2008, 2010, 2024\
The NetBSD Foundation, inc. All rights reserved.");
-__RCSID("$NetBSD: t_snprintb.c,v 1.35 2024/04/07 15:20:17 rillig Exp $");
+__RCSID("$NetBSD: t_snprintb.c,v 1.36 2024/04/08 21:28:35 rillig Exp $");
#include <stdio.h>
#include <string.h>
@@ -994,7 +994,7 @@ ATF_TC_BODY(snprintb, tc)
// example from the manual page, old style octal
h_snprintb(
- "\10\2BITTWO\1BITONE",
+ "\010\002BITTWO\001BITONE",
0x03,
"03<BITTWO,BITONE>");
@@ -1006,21 +1006,31 @@ ATF_TC_BODY(snprintb, tc)
// the bit number and the description need to be written as separate
// string literals.
h_snprintb(
- "\20"
- "\x10NOTBOOT" "\x0f""FPP" "\x0eSDVMA"
- "\x0cVIDEO" "\x0bLORES" "\x0a""FPA" "\x09""DIAG"
- "\x07""CACHE" "\x06IOCACHE" "\x05LOOPBACK"
- "\x04""DBGCACHE",
+ "\x10"
+ "\x10" "NOTBOOT"
+ "\x0f" "FPP"
+ "\x0e" "SDVMA"
+ "\x0c" "VIDEO"
+ "\x0b" "LORES"
+ "\x0a" "FPA"
+ "\x09" "DIAG"
+ "\x07" "CACHE"
+ "\x06" "IOCACHE"
+ "\x05" "LOOPBACK"
+ "\x04" "DBGCACHE",
0xe860,
"0xe860<NOTBOOT,FPP,SDVMA,VIDEO,CACHE,IOCACHE>");
// example from the manual page, new style bits and fields
h_snprintb(
"\177\020"
- "b\0LSB\0" "b\1BITONE\0"
- "f\4\4NIBBLE2\0"
- "f\x10\4BURST\0" "=\4FOUR\0" "=\xf""FIFTEEN\0"
- "b\x1fMSB\0",
+ "b\000" "LSB\0"
+ "b\001" "BITONE\0"
+ "f\004\004" "NIBBLE2\0"
+ "f\020\004" "BURST\0"
+ "=\x04" "FOUR\0"
+ "=\x0f" "FIFTEEN\0"
+ "b\037" "MSB\0",
0x800f0701,
"0x800f0701<LSB,NIBBLE2=0,BURST=0xf=FIFTEEN,MSB>");
@@ -1492,13 +1502,13 @@ ATF_TC_BODY(snprintb_m, tc)
// example from the manual page, new style bits and fields
h_snprintb_m(
"\177\020"
- "b\0LSB\0"
- "b\1BITONE\0"
- "f\4\4NIBBLE2\0"
- "f\x10\4BURST\0"
- "=\4FOUR\0"
- "=\xf""FIFTEEN\0"
- "b\x1fMSB\0",
+ "b\000" "LSB\0"
+ "b\001" "BITONE\0"
+ "f\004\004" "NIBBLE2\0"
+ "f\020\004" "BURST\0"
+ "=\x04" "FOUR\0"
+ "=\x0f" "FIFTEEN\0"
+ "b\037" "MSB\0",
0x800f0701,
34,
"0x800f0701<LSB,NIBBLE2=0>\0"
