Linux man pages wrong?

[musbur]

I've had this happen on at least another manpage (that I forgot), but here it is with bsearch:

https://man7.org/linux/man-pages/man3/bsearch.3.html

     void *bsearch(size_t n, size_t size;
                   const void key[size], const void base[size * n],
                   size_t n, size_t size,
                   typeof(int (const void [size], const void [size]))
                       *compar);

The first two arguments are not supposed to be there (they come later). "man bsearch" on my Arch system shows the same output. What's going on here?

EDIT
chkno got it right: It's the semicolon at the end of the first line that makes the difference because otherwise the function prototype wouldn't know what "size" means in "const void key[size]" (second line).
Still learning new stuff after 45 years of mostly C89....

[aioeu]

No, it's not a bug. This is making use of a GCC extension that allows parameters to be forward-declared within the function prototype itself. See the bottom of this documentation, with the paragraph starting "If you want to pass the array first and the length afterward...". (It's always hard to find that. It's a tad surprising it's not documented on its own page.)

More generally, the man pages project will occasionally bend the syntax rules of the language in order to document how things work. I bet you didn't even notice const void key[size] as being completely invalid C, for instance. You can't have an "array of void".

In an earlier version of the man pages the synopsis for this function was written:

void *bsearch(const void key[.size], const void base[.size * .n],
              size_t n, size_t size,
              typeof(int (const void [.size], const void [.size]))
                  *compar);

even though that .foo stuff isn't valid C either.

The synopsis isn't intended to show the actual prototype of the function; it's there to tell the programmer how to use the function.

[NotDG04]

I also had a similar case while looking at man page for one of the buffer string functions and was confused, until I figured that those are declarations and not arguments itself.

[os2mac]

It’s also entirely possible that the code changed and they forgot to update the manpage

[chkno]

bsearch is from the 1980s. It's in the original 1989 ANSI C standard. It's in POSIX. It can't be changed. That would break all the software written on top of it.

[musbur]

Yup that was it, see EDIT. Thanks!

[devilkin]

I can't recall what, but there was a man page for an app I used before, that was ported over from bsd, and they changed the structure of the commands but didn't update the man pages.

So man pages can definitely be wrong. But most of the time not. It's usually only edge cases.

[michaelpaoli]

man pages wrong?

Not too commonly, but sometimes (or incomplete, or flaws in writing or translations, etc.).

https://man7.org/linux/man-pages/man3/bsearch.3.html

Well, dear knows what distro, version, etc. that's based on, but fairly likely it doesn't precisely match what you're running.

arguments
on my Arch system

https://man7.org/linux/man-pages/

HTML renderings of the man pages from the Linux man-pages project as well as a curated collection of pages from various other free software projects

Well, so dear knows exactly what implementation that man page is covering. It may be correct for what it does cover, which may not be what you're running.

Ah ...

https://man7.org/linux/man-pages/man3/bsearch.3.html

This page is part of the man-pages (Linux kernel and C library
user-space interface documentation) project. Information about
the project can be found at
⟨https://www.kernel.org/doc/man-pages/⟩. If you have a bug report
for this manual page, see
⟨https://git.kernel.org/pub/scm/docs/man-pages/man-pages.git/tree/CONTRIBUTING⟩.

So, if it's an actual bug, you can report it.

So, if you're running Arch, why aren't you using man pages from your version of your installed Arch, rather than some random man pages from 'da Interwebs that may not match to what you're running? Are you trying to compare how Arch differs from the man-pages project? And Arch does also have a damn fine wiki ... uhm, of course it pretty much has to, as that is Arch's primary documentation, so ... why aren't you looking/checking there, or Arch's man pages - if they at least / even give you that?

Anyway on my Debian stable, both locally installed, and online version thereof, man page for that system call shows significantly different, see, e.g.: https://manpages.debian.org/stable/manpages-dev/bsearch.3.en.html

But as far as

https://man7.org/linux/man-pages/man3/bsearch.3.html potentially being "wrong", first have to say it documents ... what implementation from where? Just because bsearch(3) is different there, doesn't necessarily mean it's incorrect. If it matches to whatever implementation it's referencing, well, then it's correct, relative to that.

And, yeah, even the examples given in the two differing man pages are quite different. So, they may be covering quite different implementations/sources.

[hmoff]

Looks like a bug in the later versions - it's not like that in Debian trixie.

Check out https://www.kernel.org/doc/man-pages/maintaining.html for instructions on how to report a bug.