Date:        Sat, 15 Jul 2000 10:57:42 -0700
    From:        "Erik E. Fair" <fair@clock.org>
    Message-ID:  <v04220812b59656359aff@[216.240.40.200]>

  | The PR wants every error that a given system call can return in the 
  | man page for that system call (in section 2). I'm asking for 
  | discussion here as to whether that's reasonable

Since you asked ... no, it isn't.

For two reasons .. first, if it pretends to be exhaustive, then people
will start to rely on no other errors ever being possible, which makes
it real hard to extend the system, or even just change the implementation.

And, as you say, it is horrid to maintain, and also fills all the man pages
with needless garbage.

The man pages should cover the most common errors, and any that have
anything other than the standard common error meanings.  Beyond that
they should all just 'see also" intro(2) for a general explanation of
all the errors that can occur.

Eg: for open(2) it is reasonable to explain EACCES, ENOENT, EOPNOTSUPP,
EEXIST, and maybe one or two more, but others (ENOTDIR, EFAULT, ...)
are just a waste of energy - ENOTDIR only occurs because namei() chasing
the path found something not a directory before the final segment, which
is exactly the same as can happen with stat() link() unlink() rename()
and about 20 or 30 other system calls.   Repeating the same stuff over
and over is tedious...   The same is true for EFAULT EIO ELOOP EINTR
ENXIO, ...

To some extent that's done already - that is, the man page for open(2)
doesn't mention any of the NFS related errno's that can be returned
(ESTALE, etc) - which is good, but it does insist on mentioning EFAULT
and EIO and a bunch more errors that are just as irrelevant as the NFS ones.

kre