[ On Tuesday, October 9, 2001 at 17:30:08 (-0400), der Mouse wrote: ]
> Subject: Re: wrap up of pipe(2)
>
> But if - and this is my position - the manpage is not only
> documentation on what NetBSD does, but more general documentation on
> the call, warnings about what might surprise someone coming from
> elsewhere to NetBSD, someone going from NetBSD to elsewhere, what it
> might do in the future, or used to do but doesn't any longer...

While the resource resulting from such an effort would be a valuable
thing to have, I think that it is a pointless and unachievable goal (at
least for NetBSD).

There are ample porting guides available in many forms (including
online), and most any relevant OS has its manual pages available online
somewhere too.

The only thing relevant in this respect would be to mention EFAULT in
the BUGS section since the NetBSD implementation does not "conform" to
many other implementations (including previous NetBSD implementations?)
which will return EFAULT if the pointer it's handed is not "valid".

> Most important, to my mind, are the "what might surprise someone trying
> to port code one direction or another" reasons.

Yes, and those are the things that belong in the "BUGS" section.
Otherwise manual pages must document the implementation.


FYI the AT&T System V Release 4.2 manual page does not mention EFAULT,
presumably because the assignment to filedes[2] is also done in
user-land in that implementation (and in which case a SIGSEGV will
result if the pointer is invalid, though no mention is made of that).

Their equivalent to the "BUGS" section also says:

    NOTES
       Since  a  pipe  is  bi-directional, there are two separate
       flows of data.  Therefore, the size (st_size) returned  by
       a  call  to  fstat with argument fildes[0] or fildes[1] is
       the number of bytes available for reading  from  fildes[0]
       or fildes[1] respectively.  Previously, the size (st_size)
       returned by a call to fstat with argument  fildes[1]  (the
       write-end)  was  the number of bytes available for reading
       from fildes[0] (the read-end).  See stat(2).

-- 
							Greg A. Woods

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