Re: Mangled function prototypes (phantom arguments)

 Alejandro Colomar wrote:
>
> On 2026-05-28T23:24:06+0200, Alejandro Colomar wrote:
> > 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);
>
> BTW, FWIW, this resembles quite a lot the documentation from the times
> of V7 Unix.  Here's how functions were documented back then.
>
>         SYNOPSIS
>              char *ttyname(fildes)
>
>              isatty(fildes)
>
>              ttyslot()
>
> AFAICS, 4.4BSD is the first BSD that used function prototypes (both in
> the source code and documentation).  You could similarly argue that that
> was unnecessarily confusing programmers back then (most programmers of
> the time might not be aware of the innovation of function prototypes,
> and why one would care about parameter types, especially when being
> introduced to a function).  However, we'll probably agree that that was
> a good change.  I would find a prototype without types to be quite
> uninformative.

The types are documented.  Originally the types of arguments and the
return type of a function defaulted to int, so there is no need to
write the type in that case.  Argument and return types that were not
int were shown in the man pages, using the syntax that was used at the
time (arguments declared with their type after the close parenthesis
before the open brace).

The issue is not the inclusion of additional information, the issue is
the use of obscure non-standard syntax that introduces confusion.  The
man page above uses the normal C syntax that C programmers at the time
were very familiar with.

 - Mark