The format string of printf is quite complicated, and while its documentation is extensive, it has a bit too many errors and needs some cleanup for comprehensibility. In particular, man 3 printf contains: By default, the arguments are used in the order given, where each '*' and each conversion specifier asks for the next argument (and it is an error if insufficiently many arguments are given). This is inexact, as "%" is defined as a conversion specifier and doesn't consume any argument. It's also unclear in that sentence what "next argument" refers to. And "*" hasn't been introduced at that point, so that part is hard to follow ("*" is defined in section The precision).
That would be from glibc not the kernel I think ?
printf() is provided by the C library. This report is about printf's manual page, shipped in man-pages. man-pages is hosted on kernel.org ( https://www.kernel.org/doc/man-pages/reporting_bugs.html ). This persists in man-pages 3.54.
(In reply to Filipus Klutiero from comment #0) > The format string of printf is quite complicated, and while its > documentation is extensive, it has a bit too many errors and needs some > cleanup for comprehensibility. > > In particular, man 3 printf contains: > > By default, the arguments are used in the order given, where each '*' and > each conversion specifier asks for the next argument (and it is an error if > insufficiently many arguments are given). > > This is inexact, as "%" is defined as a conversion specifier and doesn't > consume any argument. Yes, but that's explained no less than twice further down the page. > It's also unclear in that sentence what "next argument" refers to. It seems clear enough to me. But, if you have a better proposal let me know. > And "*" > hasn't been introduced at that point, so that part is hard to follow ("*" is > defined in section The precision). For this piece, I changed the text to: By default, the arguments are used in the order given, where each '*' (see Field width and Pre‐ cision below) and each conversion specifier asks for the next argument
Thanks for the change. Regarding "%", I agree it is explained later, but the sentence remains incorrect (and the topic is complicated enough that each error is one too many).
Sorry. Please do not reopen this bug, unless you have a concrete proposal for a fix--i.e., a patch. As far as I'm concerned the text is adequate, and I'm not doing further work on the page, but if you want you can propose a patch on the mailing list.
Please do not close this ticket until the issue has been solved. A simple patch for this issue is trivial - just rectify that only some conversion specifiers ask for the next arguments, for example: By default, the arguments are used in the order given, where each '*' and each conversion specifier (except for some) asks for the next argument (and it is an error if insufficiently many arguments are given). A patch which would keep the current sentence's precision would have to list the exceptions.
So, I've stepped back from this a little, to think about it more. I don't agree with the characterization of this problem as an error. The sentence you refer to is a generalization. The exceptions are clarified later. I don't think it help comprehensibility, nor readability, to clutter the initial discussion with a note that there are some exceptions. By the time folk get to the point in the page where %% is discussed, it's also noted as an exception to the general rule; problem solved. printf() is a complex API. It's reasonable to expect that people should read the documentation with some care. Summary: there's nothing to fix here, so I'm not fixing it.
Few students will be given man printf to read in school. The vast majority of consultations will happen when people try to interpret or write a call to printf(). It is unlikely that these readers will read the entire page at once. If the documentation says each conversion specifier asks for the next argument, it is reasonable to expect that readers - whether careful or not - will conclude that each conversion specifier asks for the next argument, unless they read up to the point where this is contradicted. If you think a note about exceptions would clutter, terminology can be used, for example "regular conversion specifier" versus "special conversion specifier".