[ On Tuesday, July 18, 2000 at 20:45:39 (+1000), Robert Elz wrote: ]
> Subject: Re: bin/7249 
>
> Incidentally, I took the reference to "go look in the source" to be a joke,
> no-one is seriously suggesting that (or if they have, they have never attempted
> to work out what errors the kernel can generate from reading the source - it
> is not at all easy to do, even if you know the sources fairly well).
> 
> The real discussion that started this is whether or not each man page should
> attempt to have a complete list of all the errors, or whether most of them
> should be incorporated by reference to the intro(2) page, which contains all
> of the errno values, and their standard meanings.   Clearly when a kernel
> interface uses an error number in a non-standard way (almost the rule for
> ENXIO) then it needs to be documented on that page - but there really is
> no need to have EROFS mentioned in the pages for link(), open(), creat(),
> mkdir(), rmdir(), unlink(), socket(),  ...  on and on, all those functions
> return the error in the same circumstance, the definition of the error in
> EROFS in intro(2) is just fine.   That read() can't rationally return EROFS
> is really immaterial - anyone reading its description ("An attempt was made
> to modify...") will see that since read() doesn't modify the file, that
> error will not occur.

It is indeed damn near impossible to always work out exactly what errno
values the kernel can potentially return from any given system call (or
indeed a libc function), even by examination of the source as you say
above.  I firmly believe it is critical that all API manual pages
document at least the list of error codes that the developers believe
are possible.  It's not necessary to fully describe what each code means
when the meaning is indeed identical to the generic description given in
intro(2) (or intro(3)), and indeed such descriptions should probably not
be given in order to avoid the maintenance headache of duplicating and
changing this description.  Certainly I agree that any unique meaning
must be documented explicitly in the associated manual page.

I for one will continue to submit fixes for manual pages that do not at
least list all error codes thought possible....

-- 
							Greg A. Woods

+1 416 218-0098      VE3TCP      <gwoods@acm.org>      <robohack!woods>
Planix, Inc. <woods@planix.com>; Secrets of the Weird <woods@weird.com>