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. > 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 --