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)