git: 76edfabbecde - main - libc: Document support for binary integers.
- Go to: [ bottom of page ] [ top of archives ] [ this month ]
Date: Mon, 28 Aug 2023 15:38:23 UTC
The branch main has been updated by des:
URL: https://cgit.FreeBSD.org/src/commit/?id=76edfabbecdec686a570b8e009d5ea4112f943e0
commit 76edfabbecdec686a570b8e009d5ea4112f943e0
Author: Dag-Erling Smørgrav <des@FreeBSD.org>
AuthorDate: 2023-08-28 15:34:17 +0000
Commit: Dag-Erling Smørgrav <des@FreeBSD.org>
CommitDate: 2023-08-28 15:34:17 +0000
libc: Document support for binary integers.
Reviewed by: debdrup, emaste
Differential Revision: https://reviews.freebsd.org/D41522
---
lib/libc/stdio/printf.3 | 34 +++++++++++++++++++++++++---------
lib/libc/stdio/scanf.3 | 29 +++++++++++++++++++----------
lib/libc/stdlib/strtol.3 | 4 +++-
lib/libc/stdlib/strtoul.3 | 4 +++-
4 files changed, 50 insertions(+), 21 deletions(-)
diff --git a/lib/libc/stdio/printf.3 b/lib/libc/stdio/printf.3
index 3e5c6ca23511..110851e2a421 100644
--- a/lib/libc/stdio/printf.3
+++ b/lib/libc/stdio/printf.3
@@ -31,7 +31,7 @@
.\"
.\" @(#)printf.3 8.1 (Berkeley) 6/4/93
.\"
-.Dd May 22, 2018
+.Dd August 21, 2023
.Dt PRINTF 3
.Os
.Sh NAME
@@ -212,6 +212,17 @@ and
.Cm u
conversions, this option has no effect.
For
+.Cm b
+and
+.Cm B
+conversions, a non-zero result has the string
+.Ql 0b
+(or
+.Ql 0B
+for
+.Cm B
+conversions) prepended to it.
+For
.Cm o
conversions, the precision of the number is increased to force the first
character of the output string to a zero.
@@ -245,7 +256,7 @@ For all conversions except
.Cm n ,
the converted value is padded on the left with zeros rather than blanks.
If a precision is given with a numeric conversion
-.Cm ( d , i , o , u , i , x ,
+.Cm ( b , B , d , i , o , u , i , x ,
and
.Cm X ) ,
the
@@ -301,7 +312,7 @@ followed by an
optional digit string.
If the digit string is omitted, the precision is taken as zero.
This gives the minimum number of digits to appear for
-.Cm d , i , o , u , x ,
+.Cm b , B , d , i , o , u , x ,
and
.Cm X
conversions, the number of digits to appear after the decimal-point for
@@ -319,12 +330,12 @@ conversions.
.It
An optional length modifier, that specifies the size of the argument.
The following length modifiers are valid for the
-.Cm d , i , n , o , u , x ,
+.Cm b , B , d , i , n , o , u , x ,
or
.Cm X
conversion:
.Bl -column ".Cm q Em (deprecated)" ".Vt signed char" ".Vt unsigned long long" ".Vt long long *"
-.It Sy Modifier Ta Cm d , i Ta Cm o , u , x , X Ta Cm n
+.It Sy Modifier Ta Cm d , i Ta Cm b , B , o , u , x , X Ta Cm n
.It Cm hh Ta Vt "signed char" Ta Vt "unsigned char" Ta Vt "signed char *"
.It Cm h Ta Vt short Ta Vt "unsigned short" Ta Vt "short *"
.It Cm l No (ell) Ta Vt long Ta Vt "unsigned long" Ta Vt "long *"
@@ -339,7 +350,7 @@ Note:
the
.Cm t
modifier, when applied to a
-.Cm o , u , x ,
+.Cm b , B , o , u , x ,
or
.Cm X
conversion, indicates that the argument is of an unsigned type
@@ -403,11 +414,16 @@ If a single format directive mixes positional
and non-positional arguments, the results are undefined.
.Pp
The conversion specifiers and their meanings are:
-.Bl -tag -width ".Cm diouxX"
-.It Cm diouxX
+.Bl -tag -width ".Cm bBdiouxX"
+.It Cm bBdiouxX
The
.Vt int
-(or appropriate variant) argument is converted to signed decimal
+(or appropriate variant) argument is converted to
+unsigned binary
+.Cm ( b
+and
+.Cm B ) ,
+signed decimal
.Cm ( d
and
.Cm i ) ,
diff --git a/lib/libc/stdio/scanf.3 b/lib/libc/stdio/scanf.3
index b1c50e10a795..6cefdb133983 100644
--- a/lib/libc/stdio/scanf.3
+++ b/lib/libc/stdio/scanf.3
@@ -31,7 +31,7 @@
.\"
.\" @(#)scanf.3 8.2 (Berkeley) 12/11/93
.\"
-.Dd April 2, 2022
+.Dd August 21, 2023
.Dt SCANF 3
.Os
.Sh NAME
@@ -141,7 +141,7 @@ The conversion that follows occurs as usual, but no pointer is used;
the result of the conversion is simply discarded.
.It Cm hh
Indicates that the conversion will be one of
-.Cm dioux
+.Cm bdioux
or
.Cm n
and the next pointer is a pointer to a
@@ -150,7 +150,7 @@ and the next pointer is a pointer to a
.Vt int ) .
.It Cm h
Indicates that the conversion will be one of
-.Cm dioux
+.Cm bdioux
or
.Cm n
and the next pointer is a pointer to a
@@ -159,7 +159,7 @@ and the next pointer is a pointer to a
.Vt int ) .
.It Cm l No (ell)
Indicates that the conversion will be one of
-.Cm dioux
+.Cm bdioux
or
.Cm n
and the next pointer is a pointer to a
@@ -185,7 +185,7 @@ and the next pointer is a pointer to an array of
.Vt char ) .
.It Cm ll No (ell ell)
Indicates that the conversion will be one of
-.Cm dioux
+.Cm bdioux
or
.Cm n
and the next pointer is a pointer to a
@@ -201,7 +201,7 @@ and the next pointer is a pointer to
.Vt "long double" .
.It Cm j
Indicates that the conversion will be one of
-.Cm dioux
+.Cm bdioux
or
.Cm n
and the next pointer is a pointer to a
@@ -210,7 +210,7 @@ and the next pointer is a pointer to a
.Vt int ) .
.It Cm t
Indicates that the conversion will be one of
-.Cm dioux
+.Cm bdioux
or
.Cm n
and the next pointer is a pointer to a
@@ -219,7 +219,7 @@ and the next pointer is a pointer to a
.Vt int ) .
.It Cm z
Indicates that the conversion will be one of
-.Cm dioux
+.Cm bdioux
or
.Cm n
and the next pointer is a pointer to a
@@ -229,7 +229,7 @@ and the next pointer is a pointer to a
.It Cm q
(deprecated.)
Indicates that the conversion will be one of
-.Cm dioux
+.Cm bdioux
or
.Cm n
and the next pointer is a pointer to a
@@ -273,6 +273,10 @@ matches a single input
.Ql %
character.
No conversion is done, and assignment does not occur.
+.It Cm b , B
+Matches an optionally signed binary integer;
+the next pointer must be a pointer to
+.Vt "unsigned int" .
.It Cm d
Matches an optionally signed decimal integer;
the next pointer must be a pointer to
@@ -281,7 +285,12 @@ the next pointer must be a pointer to
Matches an optionally signed integer;
the next pointer must be a pointer to
.Vt int .
-The integer is read in base 16 if it begins
+The integer is read
+in base 2 if it begins with
+.Ql 0b
+or
+.Ql 0B ,
+in base 16 if it begins
with
.Ql 0x
or
diff --git a/lib/libc/stdlib/strtol.3 b/lib/libc/stdlib/strtol.3
index 9656ba546915..e2c5ff7ae3cb 100644
--- a/lib/libc/stdlib/strtol.3
+++ b/lib/libc/stdlib/strtol.3
@@ -31,7 +31,7 @@
.\"
.\" @(#)strtol.3 8.1 (Berkeley) 6/4/93
.\"
-.Dd November 28, 2001
+.Dd August 21, 2023
.Dt STRTOL 3
.Os
.Sh NAME
@@ -108,6 +108,8 @@ If
.Fa base
is zero or 16,
the string may then include a
+.Dq Li 0b
+prefix, and the number will be read in base 2; or it may include a
.Dq Li 0x
prefix,
and the number will be read in base 16; otherwise, a zero
diff --git a/lib/libc/stdlib/strtoul.3 b/lib/libc/stdlib/strtoul.3
index e05d7a7728cd..41b3b2c578bc 100644
--- a/lib/libc/stdlib/strtoul.3
+++ b/lib/libc/stdlib/strtoul.3
@@ -31,7 +31,7 @@
.\"
.\" @(#)strtoul.3 8.1 (Berkeley) 6/4/93
.\"
-.Dd November 28, 2001
+.Dd August 21, 2023
.Dt STRTOUL 3
.Os
.Sh NAME
@@ -108,6 +108,8 @@ If
.Fa base
is zero or 16,
the string may then include a
+.Dq Li 0b
+prefix, and the number will be read in base 2; or it may include a
.Dq Li 0x
prefix,
and the number will be read in base 16; otherwise, a zero