Subject: Re: wrap up of pipe(2)
To: None <>
From: der Mouse <mouse@Rodents.Montreal.QC.CA>
List: tech-userlevel
Date: 10/14/2001 16:41:39
> [W]hat I really intended to imply there was a desire for the level of
> detail afforded by a well worded standards document, for example --

Except that that's what you say below you *don't* want.

>> The only stuff that should be documented are the parts you can rely
>> on, stuff that won't just change on someone's whim.
> No thanks!  That just won't do.

But that's exactly what a well worded standards document will give you:
what aspects of the interface are guaranteed and what aspects aren't;
those points on which it's up to the implementation are specified as
such, with (if the implementation is constrained at all) the possible
alternatives itemized.

Documentation on which of the possible alternative is chosen is, I
believe, not appropriate for a manpage.  UTSL for that.

> It's not the way things are now either!

True; the manpages are defective in many ways.  But the above is, I
believe, the ideal towards which NetBSD should be striving, and the
touchstone with respect to which potential changes such as the one that
started this thread off should be tested.  And by that test, EFAULT
belongs in there (as someone said recently, the bug is the "will fail
if" wording, not the presence of EFAULT).

> If I cannot ever receive an EFAULT from pipe(2) on even just one
> architecture then I want the manual page to clearly document that
> fact.

Why?  It's not a part of the interface you can depend on.

>> 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.
> Well, since ssize_t is a (signed) int, the possibility is there on at
> least some platforms....

Which platform allows a user process to have more than half a moby of
address space?  I can't think of any offhand (but admittedly am not
familiar with more than about 5-10 of them).

/~\ The ASCII				der Mouse
\ / Ribbon Campaign
 X  Against HTML
/ \ Email!	     7D C8 61 52 5D E7 2D 39  4E F1 31 3E E8 B3 27 4B