Re: claim: forward declarations are confusing

Alejandro Colomar <[email protected]> Thu, 2 Jul 2026 23:36:48 +0200
Newsgroups	org.kernel.vger.linux-man
Message-ID	<akbWn0TppbdxNAHQ@devuan>
Hi Reid,

On 2026-07-02T17:37:04+0000, Priedhorsky, Reid wrote:
> Hi folks,
> 
> It seems that since early 2025, the man pages have starting using
> GCC-style forward declaration of parameters, which based on skimming
> the mailing list has generated many spurious bug reports.

Correct.

d2c2db8830f8 (2025-03-14; "man/: SYNOPSIS: Use GNU forward-declarations of parameters for sizes of array parameters")

> I agree with many others that this notation is confusing.  I’ve been
> programming C for over 30 years and had never heard of this syntax.
> I actually spent a while this morning preparing a bug report on a few
> web pages, since I thought it was a typo.  Only when I went to figure
> out when the “bug” had been introduced did I realize it was a
> deliberate change to introduce a syntax I was not familiar with.
> After reading up on forward declarations a bit, I’m convinced they are
> a useful syntax for actual programming, but I also agree with several
> others that the syntax is confusing in reference documentation.

I understand and somewhat agree.  If you've never seen the syntax
before, it's confusing.  And most people have never seen the syntax
before.

> My use case, as a human rather than a compiler, is to figure out how
> to call the function and what it does, and the information to do so is
> already present, for example in the case of getpwnam_r(3), the type of
> `size` is already given in the normal parameter list.

Yes, it looks a bit repetitive (like most of C, declarations and
definitions are repetitive).

> If one assumes the syntax *is* correct, it’s still difficult to figure
> out what it means.  It is (AFAICT) still a GNU extension, so looking
> at “what’s new” for e.g. C17 or C23, or even the current working draft
> of C29, doesn’t turn up anything.

Indeed.

There's a proposal for the C Committee, but Clang is vetoing it, so it
hasn't been approved so far.
<https://www.open-std.org/jtc1/sc22/wg14/www/docs/n3681.pdf>

> The point being, I argue that the forward declarations are a usability
> bug and should be reverted, because
> (1) the syntax is unfamiliar/confusing

I agree with the syntax being unfamiliar and confusing, but:

The alternatives are worse.  We have to choose between not declaring
array sizes at all (which would make the synopses less informative),
or keep using array sizes but remove the forward declarations (which
would be dangerous, because it is invalid C, until you have a variable
declaration in scope with the same name, in which case you have a pretty
bad bug).

So, I think the best way forward is to keep this, and let the world
spread the word that this syntax exists, so that future readers
understand it.  It might take a transition period of a year or a few of
extra bug reports, but I can deal with that.

> and
> (2) generates many spurious bug reports that waste the time of
> maintainers.

As the maintainer of the project, I'm willing to spend my time on this.
It's a price I can pay.

> Or, at a minimum, there should be a link at each point of use to an
> explanation, similar to the ubiquitous “see feature_test_macros(7)”.

We could add it to intro(3), but I believe people don't read that page
often.

At the moment, I believe this will cure with time, but if it remains
problematic after a few years, I'll try to figure out the best way to
point to the documentation of this syntax.

> Appreciate your time. Please CC me on any replies as I’m not on the mailing list.


Have a lovely night!
Alex

> HTH,
> Reid

-- 
<https://www.alejandro-colomar.es>
signature.asc (application/pgp-signature, 833 B)