Re: Mangled function prototypes (phantom arguments)

[Alejandro Colomar <alx@kernel.org>]

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

Hi Carlos,

On 2026-05-28T14:39:15-0400, Carlos O'Donell wrote:
> On 5/28/26 9:06 AM, Michael Kerrisk (man7.org) wrote:
> > I don't think the Linux system call and C library manual pages are a
> > good place to promote this obscure GNU feature. It is confusing
> > people, including me. (I came to making this report because several
> > people have reported this "bug" on various pages rendered at
> > man7.org.)
> > 
> > Please consider reverting these changes. These markings use
> > little-understood, nonportable syntax. The manual page synopses should
> > be in standard, portable C that is *easy* to understand.
> 
> I agree with Michael.
> 
> I think these changes should be reverted, but it's a question of
> goals and values for the project, and the purpose of the SYNOPSIS.
> 
> My view was always that they were the simplest expression of the
> interface that the widest possible audience could understand, and
> that seems to align with Michael's view.

That doesn't provide much value, IMHO.  My opinion of the SYNOPSIS is
that it's a quick reminder of how a function should be used.

Let's take a real example:

     long mbind(void *addr, unsigned long len, int mode,
                const unsigned long *nodemask, unsigned long maxnode,
                unsigned int flags);

I honestly don't know anything from the prototype above.  Apart from the
types, there's no useful information.  There are the names which will
later be described in the description, but so far they're not useful.

     long mbind(unsigned long size, unsigned long maxnode;
                void addr[size], unsigned long size, int mode,
                const unsigned long nodemask[(maxnode + ULONG_WIDTH - 1)
                                             / ULONG_WIDTH],
                unsigned long maxnode, unsigned int flags);

This already introduces me the function quite well.  The description
will of course clarify details, but I can already see some things.

> It certainly isn't for me as a C library author...

The SYNOPSIS is for everyone.  I read the synopses regularly while
programming.  In fact, I read it quite more than the descriptions, which
I only read seldom, when interested in some rare details.

> it's for
> someone just learning or refreshing knowledge, and what makes
> it easiest for a new person or someone less familiar to consume?

Speaking of myself as a new programmer not so long ago, I would have
appreciated these synopses.

> It seems like we've drifted toward describing the interface *and*
> the constraints in a compact form (like N3433). Is that in line
> with the goals of the project?

I think it is.  At least with how I see it.

I also don't see much difference between the interface and its
constraints.  They are deeply related (array parameters are part of the
type system, after all).  If we wanted to know the names of the
arguments and their order, we could have something much simpler:

	mbind(addr, size, mode, nodemask, maxnode, flags);

But of course we don't want that.

> It's not like these are the *real* prototypes in your C library,

Implementation details are unimportant.

> since those are much much more complicated and difficult to
> understand. It's also not like they match the GNU C Library
> manual's description via `info libc mmap` that are presented
> to users of the library.

I don't see why both documentations should agree in the details.  Of
course, I'd like the libc manual to be more detailed, but there's no
inherent reason why both should be exact matches, as long as they're
compatible.

> What is the intent of the SYNOPSIS field and the prototypes
> therein? What are the goals or values of the project around
> that information?

That information should introduce the API, giving enough details to
understand a decent amount of it.  It should also remind quickly of
some details such as whether an argument may be null, or which sizes
correspond to which arrays, so that programmers can quickly check those.

> There is certainly some syntax that is valuable for compilers
> enforcing constraints and providing warnings, but is that
> valuable for man pages readers?

For me, as a frequent reader, it is very valuable.  YMMV.

> For manual pages overall I think the forward declarations
> are a net negative change in readability. I would continue
> to express the constraints in plain prose.

I tend to disagree.  For example, let's consider the addition of
'restrict' (I added it a few years ago, when Michael was still around,
IIRC).

	$ find man -type f | xargs grep -rl '[[*]restrict' | wc -l;
	137

Here's the prose in memcpy(3), which I haven't removed yet (because it's
historically more relevant in memcpy(3)):

CAVEATS
     Failure  to  observe  the requirement that the memory areas do not overlap
     has been the source of significant bugs.  (POSIX and the C  standards  are
     explicit that employing memcpy() with overlapping areas produces undefined
     behavior.)  Most notably, in glibc 2.13 a performance optimization of mem‐
     cpy()  on some platforms (including x86‐64) included changing the order in
     which bytes were copied from src to dest.

If we had to replicate this paragraph in 137 pages, we'd be adding walls
of text unnecessarily.  And it would be a problem for maintaining that
text.  Now that we use 'restrict', it's just a few keywords in the
SYNOPSIS, and it's all well documented (but you need to know what that
keyword means, of course; there's a trade-off).  (Another matter is that
'restrict' is utterly broken as a keyword for source code; but for
documentation purposes it's relatively fine.  The same thing happens
with Clang's _Nullable, which has never really worked in source code.)


Have a lovely night!
Alex

> 
> $0.02.
> 
> -- 
> Cheers,
> Carlos.
> 

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

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