On Tue, 26 Aug 2014, Robert Elz wrote:
| > memcmp is only supposed to provide the correct sign, not
| > the difference.
| true, but that's not what memcmp(9) says.
This is a "normal" problem with man pages - they're written to
document what the code actually does, then interpreted as a
specification of what the code is required to do. Man pages
should be the former, the latter is the job of standards docs.
Often, there are no standards docs, and the man page has to serve
as both a specification of the parts of the interface that users
can depend on, and documentation of what the code actually does.
For example, it's possible to document "returns -ve, 0, or +ve"
in one part of the man page, as an interface specification, and
"returns the difference" in another part of th man page, as an
implementation note.
If anything needs changing, it would be to make it more clear
that the man pages should not be interpreted as an interface
specification, but as a statement of what the implementations
actually do - not to be interpreted as a promise that they will
always do that - for what can be relied upon a reference should
be made to the relevant standard (which can be POSIX (or IEEE
for C, or anyone else), or POSIX (etc) as amended by NetBSD, or
a NetBSD private standard for stuff that either isn't documented
by anyone else's standards doc, or where NetBSD's version has
simply decided to be different.
In cases where there really is a standard that can be referred to,
that might work, but I like to have all the information in one
place. If it's easy for the NetBSD man page to say both what's
promised, and what is actually done, then I would like it to do
so. I think that this helps both people using the interface and
people changing the implementation.
--apb (Alan Barrett)
