Subject: Re: wrap up of pipe(2)
To: None <firstname.lastname@example.org>
From: Greg A. Woods <email@example.com>
Date: 10/09/2001 17:59:46
[ 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
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 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:
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 or fildes is
the number of bytes available for reading from fildes
or fildes respectively. Previously, the size (st_size)
returned by a call to fstat with argument fildes (the
write-end) was the number of bytes available for reading
from fildes (the read-end). See stat(2).
Greg A. Woods
+1 416 218-0098 VE3TCP <firstname.lastname@example.org> <email@example.com>
Planix, Inc. <firstname.lastname@example.org>; Secrets of the Weird <email@example.com>