Re: Mangled function prototypes (phantom arguments)

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.

It certainly isn't for me as a C library author... it's for
someone just learning or refreshing knowledge, and what makes
it easiest for a new person or someone less familiar to consume?

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?

It's not like these are the *real* prototypes in your C library,
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.

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

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

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.

$0.02.

-- 
Cheers,
Carlos.