about summary refs log tree commit diff
path: root/manual/stdio.texi
diff options
context:
space:
mode:
authorJoseph Myers <joseph@codesourcery.com>2021-11-10 15:52:21 +0000
committerJoseph Myers <joseph@codesourcery.com>2021-11-10 15:52:21 +0000
commit309548bec3b89022bbc81a372ec3e9240211d799 (patch)
tree00606a6f381f0f9ed70358421305e4e229a79788 /manual/stdio.texi
parent3387c40a8bbad5faf85b1feb56429cb20feaa640 (diff)
downloadglibc-309548bec3b89022bbc81a372ec3e9240211d799.tar.gz
glibc-309548bec3b89022bbc81a372ec3e9240211d799.tar.xz
glibc-309548bec3b89022bbc81a372ec3e9240211d799.zip
Support C2X printf %b, %B
C2X adds a printf %b format (see
<http://www.open-std.org/jtc1/sc22/wg14/www/docs/n2630.pdf>, accepted
for C2X), for outputting integers in binary.  It also has recommended
practice for a corresponding %B format (like %b, but %#B starts the
output with 0B instead of 0b).  Add support for these formats to
glibc.

One existing test uses %b as an example of an unknown format, to test
how glibc printf handles unknown formats; change that to %v.  Use of
%b and %B as user-registered format specifiers continues to work (and
we already have a test that covers that, tst-printfsz.c).

Note that C2X also has scanf %b support, plus support for binary
constants starting 0b in strtol (base 0 and 2) and scanf %i (strtol
base 0 and scanf %i coming from a previous paper that added binary
integer literals).  I intend to implement those features in a separate
patch or patches; as discussed in the thread starting at
<https://sourceware.org/pipermail/libc-alpha/2020-December/120414.html>,
they will be more complicated because they involve adding extra public
symbols to ensure compatibility with existing code that might not
expect 0b constants to be handled by strtol base 0 and 2 and scanf %i,
whereas simply adding a new format specifier poses no such
compatibility concerns.

Note that the actual conversion from integer to string uses existing
code in _itoa.c.  That code has special cases for bases 8, 10 and 16,
probably so that the compiler can optimize division by an integer
constant in the code for those bases.  If desired such special cases
could easily be added for base 2 as well, but that would be an
optimization, not actually needed for these printf formats to work.

Tested for x86_64 and x86.  Also tested with build-many-glibcs.py for
aarch64-linux-gnu with GCC mainline to make sure that the test does
indeed build with GCC 12 (where format checking warnings are enabled
for most of the test).
Diffstat (limited to 'manual/stdio.texi')
-rw-r--r--manual/stdio.texi30
1 files changed, 21 insertions, 9 deletions
diff --git a/manual/stdio.texi b/manual/stdio.texi
index 1d235be68d..29d01b9ec9 100644
--- a/manual/stdio.texi
+++ b/manual/stdio.texi
@@ -1664,9 +1664,9 @@ an @code{int} argument should be printed in decimal notation, the
 the @samp{%%} conversion to print a literal @samp{%} character.
 
 There are also conversions for printing an integer argument as an
-unsigned value in octal, decimal, or hexadecimal radix (@samp{%o},
-@samp{%u}, or @samp{%x}, respectively); or as a character value
-(@samp{%c}).
+unsigned value in binary, octal, decimal, or hexadecimal radix
+(@samp{%b}, @samp{%o}, @samp{%u}, or @samp{%x}, respectively); or as a
+character value (@samp{%c}).
 
 Floating-point numbers can be printed in normal, fixed-point notation
 using the @samp{%f} conversion or in exponential notation using the
@@ -1825,6 +1825,13 @@ Conversions}, for details.  @samp{%d} and @samp{%i} are synonymous for
 output, but are different when used with @code{scanf} for input
 (@pxref{Table of Input Conversions}).
 
+@item @samp{%b}, @samp{%B}
+Print an integer as an unsigned binary number.  @samp{%b} uses
+lower-case @samp{b} with the @samp{#} flag and @samp{%B} uses
+upper-case.  @samp{%b} is an ISO C2X feature; @samp{%B} is an
+extension recommended by ISO C2X.  @xref{Integer Conversions}, for
+details.
+
 @item @samp{%o}
 Print an integer as an unsigned octal number.  @xref{Integer
 Conversions}, for details.
@@ -1901,15 +1908,17 @@ simply ignored; this is sometimes useful.
 @subsection Integer Conversions
 
 This section describes the options for the @samp{%d}, @samp{%i},
-@samp{%o}, @samp{%u}, @samp{%x}, and @samp{%X} conversion
+@samp{%b}, @samp{%B}, @samp{%o}, @samp{%u}, @samp{%x}, and @samp{%X} conversion
 specifications.  These conversions print integers in various formats.
 
 The @samp{%d} and @samp{%i} conversion specifications both print an
-@code{int} argument as a signed decimal number; while @samp{%o},
-@samp{%u}, and @samp{%x} print the argument as an unsigned octal,
+@code{int} argument as a signed decimal number; while @samp{b}, @samp{%o},
+@samp{%u}, and @samp{%x} print the argument as an unsigned binary, octal,
 decimal, or hexadecimal number (respectively).  The @samp{%X} conversion
 specification is just like @samp{%x} except that it uses the characters
-@samp{ABCDEF} as digits instead of @samp{abcdef}.
+@samp{ABCDEF} as digits instead of @samp{abcdef}.  The @samp{%B}
+conversion specification is just like @samp{%b} except that, with the
+@samp{#} flag, the output starts with @samp{0B} instead of @samp{0b}.
 
 The following flags are meaningful:
 
@@ -1931,7 +1940,9 @@ includes a sign, this flag is ignored if you supply both of them.
 @item @samp{#}
 For the @samp{%o} conversion, this forces the leading digit to be
 @samp{0}, as if by increasing the precision.  For @samp{%x} or
-@samp{%X}, this prefixes a leading @samp{0x} or @samp{0X} (respectively)
+@samp{%X}, this prefixes a leading @samp{0x} or @samp{0X}
+(respectively) to the result.  For @samp{%b} or @samp{%B}, this
+prefixes a leading @samp{0b} or @samp{0B} (respectively)
 to the result.  This doesn't do anything useful for the @samp{%d},
 @samp{%i}, or @samp{%u} conversions.  Using this flag produces output
 which can be parsed by the @code{strtoul} function (@pxref{Parsing of
@@ -1957,7 +1968,8 @@ characters at all are produced.
 
 Without a type modifier, the corresponding argument is treated as an
 @code{int} (for the signed conversions @samp{%i} and @samp{%d}) or
-@code{unsigned int} (for the unsigned conversions @samp{%o}, @samp{%u},
+@code{unsigned int} (for the unsigned conversions @samp{%b},
+@samp{%B}, @samp{%o}, @samp{%u},
 @samp{%x}, and @samp{%X}).  Recall that since @code{printf} and friends
 are variadic, any @code{char} and @code{short} arguments are
 automatically converted to @code{int} by the default argument