Date:        Thu, 11 Oct 2001 14:21:01 -0400 (EDT)
    From:        woods@weird.com (Greg A. Woods)
    Message-ID:  <20011011182101.22938EA@proven.weird.com>

  | I most certainly ALWAYS want the platform documentation delivered with a
  | given release to EXACTLY describe the implementation in that very release!

That's almost impossible, and essentially useless.   Just why would anyone
need that level of detail?

  | and there's NOTHING about system
  | documentation that frustrates me more than finding that it does not
  | describe the actual release-specific implementation!

If it fails to describe some behaviour that you can observe, then yes,
that's bad.  On the other hand, if it says "X might happen if Y", there's
no problem if X doesn't actually happen.  You're not being guaranteed it
will happen, just being told it might.

  | System manuals do not
  | need to be both implementation specific and generic guides.

The system manuals should be documenting the guarantees that the
system is making to you.

  | If my application suddently somehow fails or behaves
  | unexpectedly then I want to be able to read in the new manual page how I
  | must change my application to work properly on the new system
  | implementation.

Absolutely, no problem there.   But what we're discussing here is the man
page saying that you might get an EFAULT from a bad address passed to the
pipe() sys call.   There's nothing wrong with that - including when you
know that what will actually happen is that you'll get a SEGV instead
(any use of a bad address in a program can generate a SEGV).

Pass a bad address to read(2) and you'll usually get EFAULT, but I can
trivially change the implementation of the read syscall so a SEGV happens
instead (I can trivially change the calling program so a SEGV happens instead).

You need to be able to deal with both - the man pages should make that
clear.

  | If that were to come to be then I would fully expect there either to be
  | platform specific manual pages for the call in question,

No thanks.

  | I can't quite believe you said that.  Of course there's always the
  | source, but the source is not the documentation!

It is the best documentation, and always will be, for those who really
want to know the intimate details of exactly what happens today, rather
than what the system is guaranteeing will continue to happen.

The only stuff that should be documented are the parts you can rely on,
stuff that won't just change on someone's whim.   As it is now, if on some
port, the portmaster decided that passing the pipe array address into the
sys call was a better design (for that port) than returning 2 integers,
they can simply go ahead and make the change, and return EFAULT instead
of generating a SEGV, with essentially no prior discussion, and certainly
without anyone being able to object on the basis that the change would be
breaking a defined interface - which they would be able to do if EFAULT
weren't listed as a possible return code from pipe().

Or, let's take a different example, read(2) is defined as returning EINVAL
if "The total length of the I/O is more than can be expressed by the ssize_t
return value."   Which of NetBSD's current ports can ever actually return
that error (for that reason) ??   Maybe some can, but there are certainly
some of them where it will never happen.   The man page is just fine however.

kre