claim: forward declarations are confusing

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.

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.

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.

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.

The point being, I argue that the forward declarations are a usability bug and should be reverted, because (1) the syntax is unfamiliar/confusing and (2) generates many spurious bug reports that waste the time of maintainers. 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)”.

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

HTH,
Reid

—
he/him