[SOLVED] man-pages broken?

markz79 · 2023-03-27 15:24:42

The man page for mmap (2) shows
void *mmap(void addr[.length], size_t length, int prot, int flags,
int fd, off_t offset);
int munmap(void addr[.length], size_t length);

I don't think the "[.length]" strings should be present. Many other system calls have a similar issue (e.g., read and write). It has also propagated to the man pages on the web.

I have man-pages 6.03-1 installed. The issue doesn't appear with 6.01-1.

Last edited by markz79 (2023-03-28 05:40:50)

rowdog · 2023-03-28 00:13:43

This seems to be the way the man pages are written now, so no, the Arch package isn't broken.

In C, if you want to pass an array to a function, you can write the function parameter in (at least) 3 ways:

int foo(void *param);
int foo(void param[]);
int foo(void param[10]);

Basically, array notation is an opinionated way to write void *addr.

You can read more about array notation at
https://stackoverflow.com/questions/617 … ments-in-c

If there's a bug here, it's with the upstream project
https://www.kernel.org/doc/man-pages/

Trilby · 2023-03-28 00:43:23

But none of those three ways are what is in the referenced man pages. You cannot declare a function as:

int foo(void param[.len], int len);

Though this does seem to be a deliberate abomination. And it is not (yet?) on the man pages at kernel.org, e.g. https://man7.org/linux/man-pages/man2/mmap.2.html

Last edited by Trilby (2023-03-28 00:49:23)

loqs · 2023-03-28 02:22:09

https://git.kernel.org/pub/scm/docs/man … 0f034fea70
https://www.open-std.org/jtc1/sc22/wg14 … /n2611.htm
Edit:
https://lore.kernel.org/all/4b2d7cd7-da … gmail.com/

- Use VLA syntax for documenting function parameters that are treated
as arrays. This uses syntax not accepted by compilers.

https://lore.kernel.org/all/20220826210 … gmail.com/

ISO C doesn't allow using VLA syntax when the parameter used for
the size of the array is declared _after_ the parameter that is a
VLa. That's a minor issue that could be easily changed in the
language without backwards-compatibility issues, and in fact it
seems to have been proposed, and not yet discarded, even if it's
not going to change in C23.
Since the manual pages SYNOPSIS are not bounded by strict C legal
syntax, but we already use some "tricks" to try to convey the most
information to the reader even if it might not be the most legal
syntax, we can also make a small compromise in this case, using
illegal syntax (at least not yet legalized) to add important
information to the function prototypes.
If we're lucky, compiler authors, and maybe even WG14 members, may
be satisfied by the syntax used in these manual pages, and may
decide to implement this feature to the language.
It seems to me a sound syntax that isn't ambiguous, even if it
deviates from the common pattern in C that declarations _always_
come before use. It's a reasonable tradeoff.

Last edited by loqs (2023-03-28 02:39:36)

markz79 · 2023-03-28 05:39:11

So it is deliberate -- interesting. Marking as solved. Thanks.

Trilby · 2023-03-28 12:54:30

The syntax used in the man page wouldn't even be valid if the size parameter were first ... at least not with the dot before the length.

# this is legal VLA format
int foo(int len, char buffer[len]);
# this is not
int foo(int len, char buffer[.len]);

Arch Linux

#1 2023-03-27 15:24:42

[SOLVED] man-pages broken?

#2 2023-03-28 00:13:43

Re: [SOLVED] man-pages broken?

#3 2023-03-28 00:43:23

Re: [SOLVED] man-pages broken?

#4 2023-03-28 02:22:09

Re: [SOLVED] man-pages broken?

#5 2023-03-28 05:39:11

Re: [SOLVED] man-pages broken?

#6 2023-03-28 12:54:30

Re: [SOLVED] man-pages broken?

Board footer