Re: [PATCH] man/: SYNOPSIS: Remove GNU forward-declarations of parameters for lengths of array parameters

[Alejandro Colomar <alx+linux-man@kernel.org>]

[-- Attachment #1: Type: text/plain, Size: 5042 bytes --]

Hi Michael,

> Date: 2026-10-23 08:53:22-0300
> From: "Michael Kerrisk (man7.org)" <mtk@man7.org>
>
[...]
> > > > Also, this syntax is not very dangerous: a programmer thinking
> > > > that a forward declaration is actually a normal parameter will pass a
> > > > wrong number of arguments to the function, and thus will have compiler
> > > > errors.  This syntax is quite robust, as it requires several bugs to
> > > > happen in the same code to pass compilation silently.  If one replaces
> > > > ';' with ',', the parameter will be declared twice, which is an error.
> > > > If one renames a forward declaration, it will not match a parameter, and
> > > > will result in a compiler error.  Only if both mistakes happen at once,
> > > > the compilation would pass, but then the call sites would also have to
> > > > match the bogus declaration.  And also, the function definition would
> > > > have unused parameters, which would trigger diagnostics.  So, concerning
> > > > safety, this feature is not very dangerous, even if used by someone who
> > > > is very confused.
> 
> It is not enough to say that the compiler will warn people about the
> incorrect arguments. I have seen people do the strangest (incorrect)
> things to "fix" warnings and errors they get from the compiler.

Hmmmm.

> > > > Do we think programmers are unable to ever learn this new syntax?
> > >
> > > No, because programmers are clever and it is relatively simple. I wrote a
> > > paper that explored the drawbacks of the syntax and recommended
> > > standardising a subset (which I assume is what you are using).
> 
> I have talked with programmers with *decades* of C programming
> experience who are unfamiliar with this syntax. Indeed, when I first
> got bug reports about, I also was unfamiliar with it, and thought it
> was just a bug in the manual page.

I agree with this.  Very very few people knew about this feature until
it started being discussed recently, and still very few people know
about it.  I only knew about it around 3 years ago or so.

What I wonder is whether people can get familiar with it in one or two
years of exposure to it.

One way to test that would be to wait until Fedora contains this syntax
at least in one release, to get it exposed to more programmers.  So far,
Fedora remains in man-pages-6.13, and the first version with this
syntax was 6.14 (1.5 years ago).  Carlos is working on getting the
packaging updated.

There are risks in both alternatives: if we have the GNU C syntax,
there's a risk with programmers workarounding compiler errors in weird
ways.  If we have the invalid syntax without forward declarations, the
risk is in people using that syntax in their own code and triggering UB
or least logic errors.  The latter risk is a persistent one; there's no
expectation that the risk will ever decrease.  The former risk (that of
using GNU C syntax), I expect the risk to be temporary, until
programmers get accustomed to this syntax.

I'd accept adding this patch if there's an overwhelming majority that
I'm being a bit paranoid about the risk of using invalid syntax, and
that I'm understating the risk of using GNU C syntax.

I'd like to hear explicit comments from Carlos, Sam, and Joseph before
taking a decision.  But if they seem to agree with that point of view,
I'd take the patch, even with my own NAK (I'm willing to document both
ACKs and NAKs).

I've now also CCed a few more people, since I'm also curious about their
opinions.

So far, the patch would have:

	Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
	Nacked-by: Alejandro Colomar <alx@kernel.org>
	Nacked-by: Martin Uecker <uecker@tugraz.at>
	Nacked-by: Christopher Bazley <chris.bazley.wg14@gmail.com>
	Acked-by: Mark Harris <mark.hsj@gmail.com>
	Acked-by: Michael Kerrisk <mtk.manpages@gmail.com>
	Signed-off-by: Alejandro Colomar <alx@kernel.org>

(those ACKs and NAKs transformed from messages saying they want or don't
 want the patch.)

(Before anyone comments the possibility of going back to simple pointer
 syntax, that's certainly not coming back.  The information about array
 lengths is fundamental in the SYNOPSIS.)

[...]
> My preference would be the earlier status quo: standard C syntax, with

As a reminder, it was never standard C syntax.  We have always had
non-standard exceptions in prototypes, such as open(2) having two
declarations (as if C++ overload syntax).  It was ISO C syntax regarding
array parameters, though: we used pointer syntax.  But as said above,
I really disliked having that information only in the DESCRIPTION.

> an explanation in the manual page text that explains the relationship
> between the arguments. The current proposed patch is a compromise: it
> has the disadvantage of being nonstandard C, but does at least clearly
> hint at the relationship between the arguments.

Agree.


Have a lovely day!
Alex

> Thanks,
> 
> Michael

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]