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: 7488 bytes --]

Hi Chris,

> Date: 2026-10-22 18:29:31+0100
> From: Christopher Bazley <chris.bazley.wg14@gmail.com>
>
> Hi Alejandro,
> 
> On Thu, 22 Oct 2026 at 17:45, Alejandro Colomar <alx@kernel.org> wrote:
> 
> > From: Alejandro Colomar <alx+linux-man@kernel.org>
> >
> > From: Alejandro Colomar <alx@kernel.org>
> >
> > I'm not fully convinced of this patch.  But I'm open to being convinced.
> > I've written the patch, as Michael asked me to do, but am willing to
> > hear everyone's opinion before applying the patch.
> 
> 
> Why did Michael ask you to do this?  I think there is some context missing.

We have dozens of users having reported a bug in the documentation,
as they believe the forward declarations are an accident/typo.
Clearly, most readers don't know this syntax, and think it's some
mistake.  I've been dealing with them nicely explaining them the
existance and validity of the syntax, and they tend to understand it
quickly.

> > As Michael reminded me recently, and as I've defended in other cases, it
> > is true that the SYNOPSIS of the manual pages does not need to be
> > strictly valid C.  It only needs to be useful enough for readers to
> > understand the interface.  Thus, if using lengths without declaring them
> > would improve the usefulness of the documentation, even if becoming
> > invalid C, it would be okay.
> >
> > However, I still have doubts, because this change comes with risks:
> >
> > Programmers might think it is valid C to refer to parameters that have
> > not been declared yet, and use that in their code, and if they are
> > unlucky, it might compile for them, which might result in UB at some
> > point.
> >
> 
> 
> I think it is reasonable to assume that anything which resembles C source
> code will at some point be copied and pasted into a C program.

Indeed.

> > One valid point is that this is rather unlikely to happen, and most of
> > the time it will just result in a compiler error, because no global
> > variables with the name of the parameter exist.
> >
> > However, with local (nested) functions, this might be easier to happen,
> > as variables declared in the outer function are more likely to share a
> > name with a length parameter.  Given that the C Committee is working
> > hard to standardize local functions, it might be a very bad idea to have
> > this combination of events going on.
> >
> 
> I agree with this concern in general, although I don’t quite see how it
> applies in the specific case of the functions that you are documenting.
> (Unless you are expecting those functions to be declared inside a function
> definition instead of by including the appropriate header — in which case
> the hazard already exists.)
> 
> I guess you are really worried about people copying the style rather than
> the content.

Indeed, my worry is not that people will copy these declarations
verbatim, but that they'll think it is valid, and write similar code for
their own declarations.

> > Concerns that have been raised against using the GNU C syntax in the
> > manual pages:
> 
> 
> Parameter forward declarations are also supported by SDCC, albeit with more
> limitations. I would be interested to see whether your usage falls into the
> category of usage that would be supported by SDCC or not.

Our users are mainly interested in POSIX compilers.  That is more or
less GCC, Clang, TCC, PCC, and maybe something like Intel or IBM
compilers.  The main two are GCC and Clang.

> > Very very few programmers know this syntax, and thus they are confused
> > when reading it for the first time.
> >
> > This is obviously true.  However, this is true of any innovative syntax.
> > We should consider whether the confusion is dangerous or not, and
> > whether programmers can learn it easily or not.
> >
> 
> Can we still call it innovative, many decades after its invention?

Maybe I should have used the term 'novel' rather than innovative.
While it's clearly not new, being decades old, it is certainly a novelty
to the programmers that have never seen it before.

> > I believe once you've been exposed to this syntax, after some research,
> > or asking the right people, one would easily learn to read it, and then
> > we'd have overcome the issue.  I don't think the syntax is inherently
> > difficult to understand once you've seen the documentation and seen it
> > a few times.
> >
> > 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.
> >
> > 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).
[...]

Agree.

> I still have not yet seen a proposal for anything easier to learn (that
> does not rely on forward-parsing).

Agree.  But indeed the counter-proposal that I've received is to use
retroactive scoping in the manual pages.

> > Are we ready to accept the risks of using the dangerous invalid syntax,
> > but which is more intuitive to programmers?
> >
> > Reported-by: Michael Kerrisk <mtk.manpages@gmail.com>
> > Not-yet-Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > ---
> >
> > I've cut the diff below to just a single page, because this is just for
> > discussion; the actual diff is huge and uninteresting.  It's just a
> > removal of all uses of fwd decls of parameters in the manual pages.
> >
> 
> I don’t agree with the change,

Thanks!

> but the fact that there are no useful ISO C
> semantics for parameters of pointer type declared using array syntax
> weakens my concern. (If the parameters actually had variably-modified types
> then the change would be far worse, from my point of view, because the
> parameter types would no longer be expressed correctly.)

We don't care about what ISO C says.  GNU C clearly assigns semantics to
array parameters, and that means we have to be careful about them here.
If this can result in sanitizers breaking code, it is something to be
careful about.  Moreover, I hope ISO C eventually catches up.

> You know your customers better than I do. If they expect GNU C semantics,
> then it seems reasonable to document those semantics using GNU C syntax.

Agree.


Have a lovely night!
Alex

P.S.:  I see two emails from you; are they the same?  One has a smaller
recipient list, but the contents seem visually the same.

> 
> Christopher

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

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