I can't believe this argument is still going on.   I started a catch up of
a week and a half's worth of NetBSD mail a day or two ago, and when I saw
this nonsense, I assumed it would all be resolver long before I reached the
end of my folder, but ...

The base argument seems to be on what the man pages should really
document.

There some say that they should document exactly what the system does,
today - that's ludicrous.

If you were writing an application, and looking at the man page, and writing
the code to conform, only to be told tomorrow that it has all changed, the
man page has now been updated, and all your carefully planned code is now
not correct, you wouldn't be very happy.

This also assumes that there is one common behaviour throughout all of
NetBSD - and while that may very well be true now of the way pipe(2) works
on all ports, there's no guarantee that it will stay that way.   The actual
sys call conventions are MD - if NetBSD were to be ported to an architecture
where returning two results from a syscall was very difficult, most likely
the pipe(2) for that would actually pass in the address, and so EFAULT would
be what was returned.  But I'd still expect i386/alpha/sparc ... to keep on
generating a SEGV instead.

For anyone who really wants to know what the implementation actually does,
right now, for some particular architecture, there's always the source.

For most purposes, that isn't useful information though, what is needed by
most people who read the man pages is one of

	a) I did this sys call, and this error happened, what does it mean?
or	b) I am using this sys call, what error conditions can I expect to
	   have to handle?

For (a) as long as all reasonable errors (everything that might be generated)
is documented, with its meaning, that's fine - even if a few never happen in
practice.   For (b) what's needed is anything that a NetBSD program might
reasonably expect to have to handle (whether it will actually happen today or
not).

Note: (b) is not solved by "go look at a standards doc" - both because NetBSD
(nor any other system) rarely actually implements the precise standards, and
because they often leave quite a bit unspecified.  Someone writing code that
will (even might) run on lots of systems will have to deal with all of that,
someone writing NetBSD code doesn't - just whatever NetBSD might throw at them.

The real problem with pipe(2) is the line ...

	The pipe() call will fail if:

which conveys the wrong sense of what it should be describing.  Change
that to "Errors returned from pipe() can include:" and everything would
be fine, just as it now is.   Regardless of no pipe() I have ever seen
ever actully returning EFAULT (way back to very early unix, pipe(2) always
returned 2 ints to user code, which then stuffed the array from the C caller).
Of course, some implementation might have done it differently, somewhere.

Basically, every sys call that takes an address can return either EFAULT
or generate a SEGV, at the implementors whim.

kre