On 20/07/2026 17:10, Pádraig Brady wrote:
The "see also" has a reference to printf(3),
which you can drill down to directly depending on you man page viewer,
or view directly with `man 3 printf`.
But I agree we should show that reference directly in the text.
We need to be careful not to repeat too much info from the (large) printf(3)
page,
but I also agree that we could provide a little more info here.
I'll look at:
Using our recently improved man table formatting to present a conversion
summary.
Including at least mentioning that flags are supported.
Also an EXAMPLES section would be useful here I think to show supported
combinations.
I'll apply the attached later, which adds:
CONVERSION Shell format example Output
%s '[%10s]' 'left pad' [ left pad]
%s '[%-10s]' 'right pad' [right pad ]
%c %s '%c %.3s' un unibyte u uni
%d %i "%'d ;%i04i" 1234 '-1' 1,234 ;-001
%o '%#o' $((2#110100100)) 0644
%u '%u' 0xFFFFFFFF 4294967295
%x '0x%08x' 11259375 0x00abcdef
%a %f '%1$a %1$f' 0.0009765625 0x8p-13 0.000977
%e %f '%1$e %1$f' 123.45678 1.234568e+02 123.456789
%g '%1$g %1$.2g' 1.2345678e3 1234.57 1.2e+03
%b '%b' 'food\bbar' foobar
%q '%q ' 'a' ';b' $'c\n' a ';b' 'c'$'\n'
Marking this as done.
cheers,
Padraig
From 88f95b3bb4bdbedfa4b3bd6bec56ad81bb4e0820 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?P=C3=A1draig=20Brady?= <[email protected]>
Date: Wed, 22 Jul 2026 12:49:52 +0100
Subject: [PATCH] doc: printf: provide usage examples
* src/printf.c (usage): List examples for each supported
conversion specifier.
* doc/coreutils.texi (printf invocation): Likewise.
Addresses https://bugs.gnu.org/81442
---
doc/coreutils.texi | 26 +++++++++++++++++++++++++-
src/printf.c | 25 +++++++++++++++++++++++--
2 files changed, 48 insertions(+), 3 deletions(-)
diff --git a/doc/coreutils.texi b/doc/coreutils.texi
index 50afa99fc..2deec234a 100644
--- a/doc/coreutils.texi
+++ b/doc/coreutils.texi
@@ -12951,12 +12951,36 @@ and C language escape sequence processing.
@xref{Output Conversion Syntax,, @command{printf} format directives,
libc, The GNU C Library Reference Manual}, for details.
See also @uref{https://en.cppreference.com/w/c/language/escape,
-C99 string escapes:}. The differences are listed below.
+C99 string escapes:}.
+
+Examples of supported conversion specifiers and flags are:
+
+@example
+CONVERSION Shell format example Output
+
+%s '[%10s]' 'left pad' [ left pad]
+%s '[%-10s]' 'right pad' [right pad ]
+%c %s '%c %.3s' un unibyte u uni
+%d %i "%'d ;%i04i" 1234 '-1' 1,234 ;-001
+%o '%#o' $((2#110100100)) 0644
+%u '%u' 0xFFFFFFFF 4294967295
+%x '0x%08x' 11259375 0x00abcdef
+%a %f '%1$a %1$f' 0.0009765625 0x8p-13 0.000977
+%e %f '%1$e %1$f' 123.45678 1.234568e+02 123.456789
+%g '%1$g %1$.2g' 1.2345678e3 1234.57 1.2e+03
+%b '%b' 'food\bbar' foobar
+%q '%q ' 'a' ';b' $'c\n' a ';b' 'c'$'\n'
+@end example
@mayConflictWithShellBuiltIn{printf}
+The differences from the C @samp{printf} function are:
+
@itemize @bullet
+@item
+Only the @samp{diouxXfaAeEgGcs} conversion specifiers are supported.
+
@item
The @var{format} argument is reused as necessary to convert all the
given @var{argument}s. For example, the command @samp{printf %s a b}
diff --git a/src/printf.c b/src/printf.c
index 5fb4c7c86..57e65cb4a 100644
--- a/src/printf.c
+++ b/src/printf.c
@@ -92,8 +92,29 @@ FORMAT controls the output as in C printf. Interpreted sequences are:\n\
%q ARGUMENT is printed in a format that can be reused as shell input,\n\
escaping non-printable characters with the POSIX $'' syntax\
\n\n\
-and all C format specifications ending with one of diouxXfeEgGcs, with\n\
-ARGUMENTs converted to proper type first. Variable widths are handled.\n\
+and all C printf(3) format specifications ending with one of diouxXfaAeEgGcs,\n\
+with ARGUMENTs converted to proper type first.\n\
+"), stdout);
+ fputs (_("\
+FORMAT is reused to convert all specified arguments.\n\
+"), stdout);
+ fputs (_("\
+The following table shows examples of supported conversion specifiers,\n\
+including usage of width, precision, and flags.\n\
+\n\
+ CONVERSION Shell format example Output\n\
+ %s '[%10s]' 'left pad' [ left pad]\n\
+ %s '[%-10s]' 'right pad' [right pad ]\n\
+ %c %s '%c %.3s' un unibyte u uni\n\
+ %d %i \"%'d ;%i04i\" 1234 '-1' 1,234 ;-001\n\
+ %o '%#o' $((2#110100100)) 0644\n\
+ %u '%u' 0xFFFFFFFF 4294967295\n\
+ %x '0x%08x' 11259375 0x00abcdef\n\
+ %a %f '%1$a %1$f' 0.0009765625 0x8p-13 0.000977\n\
+ %e %f '%1$e %1$f' 123.45678 1.234568e+02 123.456789\n\
+ %g '%1$g %1$.2g' 1.2345678e3 1234.57 1.2e+03\n\
+ %b '%b' 'food\\bbar' foobar\n\
+ %q '%q ' 'a' ';b' $'c\\n' a ';b' 'c'$'\\n'\n\
"), stdout);
printf (USAGE_BUILTIN_WARNING, PROGRAM_NAME);
emit_ancillary_info (PROGRAM_NAME);
--
2.55.0
