Re: The GNU C Library Manual - Authoritative or not?

[Florian Weimer <fweimer@redhat.com>]

* Carlos O'Donell via Libc-alpha:

> "What is the authoritative source for public glibc APIs?"
> https://sourceware.org/glibc/wiki/FAQ#What_is_the_authoritative_source_for_public_glibc_APIs.3F

Current text:

| The GNU C Library manual is the authoritative place for such
| information that is related to the implementation of functions in
| glibc.
|
| The Linux Man Pages are non-authoritative, but they are incredibly
| useful, easy to use, and often the first source of such information.
|
| The Linux Man Pages is generally authoritative on kernel syscalls, and
| we have worked hard in cases like futex to ensure the documentation is
| clear enough for all C libraries.
|
| We should all work together to keep both the manual (glibc manual) and
| the shorter form API references (linux man pages) up to date with the
| most accurate information we have.
|
| Where you find issues with the manual or the linux man pages please
| reach out to discuss the issue.

> "What other sources of documentation about glibc are available?"
> https://sourceware.org/glibc/wiki/FAQ#What_other_sources_of_documentation_about_glibc_are_available.3F

| The glibc manual is part of glibc, it is also available online.
|
| The Linux man-pages project documents the Linux kernel and the C
| library interfaces.
|
| The Open Group maintains the POSIX Standard which is the authoritative
| reference for the POSIX APIs.
|
| The ISO JTC1 SC22 WG14 maintains the C Standard which is the
| authoritative reference for the ISO C APIs.
|
| The official home page of glibc is at http://www.gnu.org/software/libc.
|
| The glibc wiki is at http://sourceware.org/glibc/wiki/HomePage.
|
| For bugs, the glibc project uses the sourceware bugzilla with
|component 'glibc'.

I don't think this is very helpful.  It paints a simple picture which is
turns out to be rather misleading when inspected closely.  For example,
POSIX often claims that ISO C takes precedence, but then proceeds to
specify conflicting requirements with ISO C.  What does that even mean?
After fall, it's not possible to have multiple authoritative sources for
the behavior of a single function.

Practically speaking, I see the following problems.

The GNU C Library manual is not often consulted by developers.  I don't
know why.  One reason may be that it is not readily installable from
package repositories on Debian or Ubuntu (at least not in current
versions from the main archive).  But our experience at Red Hat suggests
that our developers do not read the manual, either, although we do ship
it.  I base this on the paucity of bug reports against the manual
compared to what we receive for the man-pages package (which are often
misfiled initially against glibc).  In my opinion, a manual that is not
actually used by the people who benefit from the information in it has
at best a dubious claim to authority.

Reading our manual requires considerable skill.  You need to know the
history of the project, the lingering Linux vs Hurd conflict, the late
arrival of threading support in UNIX-like environments, the tension
between the POSIX and C standards, the lack of maintenance of both, and
so on.  Without such knowledge, it is often not possible to reach the
right conclusions.  Even senior developers can easily get confused.
(For a recent example, consider Kees Cook's misinterpretation of the
O_EXEC documentation in the manual.)  Part of the problem here is that
we do not have a team that combs through the manual from time to time
and keeps it up to date, as our understanding of the documented matter
evolves.

When it comes to Linux interfaces, any claim about authority of the
manual is very misleading.  It does not matter if the system call is
described by POSIX.  For example, if Linux developers change the signal
that waitpid reports after a failed execve, and our manual documents
something else, then the manual is now wrong.  And not the kernel.  If
the manual were authoritative, it would be the other way round.  (The
man-pages project is not authoritative in that sense, either—it did
document the SIGKILL signal and had to be updated.)

Many of these issues are beyond our control.  Some of the issues which
are in our area would need a tremendous amount of work to address.

Thanks,
Florian