Linux Manual Pages development
 help / color / mirror / Atom feed
From: Alejandro Colomar <alx+linux-man@kernel.org>
To: "Michael Kerrisk (man7.org)" <mtk@man7.org>
Cc: "Christopher Bazley" <chris.bazley.wg14@gmail.com>,
	linux-man@vger.kernel.org,
	"Michael Kerrisk" <mtk.manpages@gmail.com>,
	"Sam James" <sam@gentoo.org>,
	"Carlos O'Donell" <carlos@redhat.com>,
	"Joseph S. Myers" <josmyers@redhat.com>,
	"Martin Uecker" <uecker@tugraz.at>,
	"Guillem Jover" <guillem@hadrons.org>,
	g.branden.robinson@gmail.com,
	"Günther Noack" <gnoack3000@gmail.com>,
	"Ahelenia Ziemiańska" <nabijaczleweli@nabijaczleweli.xyz>
Subject: Re: [PATCH] man/: SYNOPSIS: Remove GNU forward-declarations of parameters for lengths of array parameters
Date: Tue, 17 Nov 2026 20:17:44 +0100	[thread overview]
Message-ID: <avyn9TUpxZ6N6sQS@devuan> (raw)
In-Reply-To: <attQRCILbrngR_70@debian>

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

Hi Michael,

> Date: 2026-10-23 14:42:24+0200
> From: Alejandro Colomar <alx+linux-man@kernel.org>
>
> 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.

The C Committee has discussed this feature, and now my concerns about it
have relaxed somewhat.  I'll probably apply the patch after the next
release.


Have a lovely night!
Alex

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



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

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

  reply	other threads:[~2026-11-17 19:17 UTC|newest]

Thread overview: 30+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2026-10-22 16:44 [PATCH] man/: SYNOPSIS: Remove GNU forward-declarations of parameters for lengths of array parameters Alejandro Colomar
2026-10-22 17:11 ` Martin Uecker
2026-10-22 20:01   ` Alejandro Colomar
2026-10-22 20:27     ` Alejandro Colomar
2026-10-22 17:37 ` Christopher Bazley
     [not found] ` <CAEHU8x9jET+vcrR0NpDz6t57egQG8TZqx5XtV52srH9ZRvdxSQ@mail.gmail.com>
2026-10-22 19:54   ` Alejandro Colomar
2026-10-23 11:53     ` Michael Kerrisk (man7.org)
2026-10-23 12:42       ` Alejandro Colomar
2026-11-17 19:17         ` Alejandro Colomar [this message]
2026-10-23 15:51       ` Christopher Bazley
2026-10-24 12:45         ` Michael Kerrisk (man7.org)
2026-10-24 13:38           ` Alejandro Colomar
2026-10-24 16:16             ` Christopher Bazley
2026-10-24 16:37               ` Alejandro Colomar
2026-10-24 18:11                 ` Martin Uecker
2026-10-25  6:59                   ` Alejandro Colomar
2026-10-25  7:22                     ` Martin Uecker
2026-10-25  7:38                       ` Alejandro Colomar
2026-10-25  8:29                         ` G. Branden Robinson
2026-10-25  8:40                         ` Martin Uecker
2026-10-25  8:57                           ` Alejandro Colomar
2026-10-25  9:05                             ` Martin Uecker
2026-10-29 21:24                           ` Christopher Bazley
2026-10-29 22:57                             ` Alejandro Colomar
2026-10-23 12:11     ` Alejandro Colomar
2026-10-22 22:03 ` Mark Harris
2026-10-23  9:43   ` Alejandro Colomar
2026-10-23 19:32     ` Mark Harris
2026-10-23 20:06       ` Alejandro Colomar
2026-10-24  7:53   ` Martin Uecker

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=avyn9TUpxZ6N6sQS@devuan \
    --to=alx+linux-man@kernel.org \
    --cc=carlos@redhat.com \
    --cc=chris.bazley.wg14@gmail.com \
    --cc=g.branden.robinson@gmail.com \
    --cc=gnoack3000@gmail.com \
    --cc=guillem@hadrons.org \
    --cc=josmyers@redhat.com \
    --cc=linux-man@vger.kernel.org \
    --cc=mtk.manpages@gmail.com \
    --cc=mtk@man7.org \
    --cc=nabijaczleweli@nabijaczleweli.xyz \
    --cc=sam@gentoo.org \
    --cc=uecker@tugraz.at \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox