socket(7) and section 2

[James K. Lowden-2]

It's impossible to program sockets correctly based on the manual.  Believe
me; I tried.  Among other things, read(2) doesn't mention that it returns
zero to indicate the peer has closed the connection.  

Throughout the socket documentation, ERRORS is not exhaustive.  write(2)
for instance doesn't mention that EPIPE is set (or at least *should* be,
after SIGPIPE) after writing to a closed connection.  Nor is ENETDOWN
mentioned.  I could go on.  

The thing is, I have a hard time believing this is an oversight, because
NetBSD's ancestors practically invented tcp/ip.  Am I missing something,
or does it fall to a nonexpert like me to take at least a swag at getting
write(2) right?  

In a similar vein, I'm not aware of anything that serves as a Guide to
Sockets.  I don't mean Sockets for Novices; I mean something that relates
the API to the TCP/IP protocol.  What packets does
connect/bind/listen/accept/close cause to be sent?  What does select(2)
mean by a "ready" descriptor?  (Hint: available data or free buffers is
only one of four cases.)  How will i/o functions behave when the network
can't transmit data, when the peer crashes, when the peer's host crashes,
if I down the interface?  I propose sockets(7) for the purpose.  

Perhaps some of the ambiguity and vagueness stems from uncertainty in
flintlock times of what socket domain would be used.  All well and good,
but surely we agree that TCP/IPv4 is commonly enough used nowadays that it
deserves careful, detailed explication?  ;-)

--jkl

[Christos Zoulas-2]

In article <20090315185649.4a012a39.jklowden@...>,
James K. Lowden <netbsd-docs@...> wrote:

>It's impossible to program sockets correctly based on the manual.  Believe
>me; I tried.  Among other things, read(2) doesn't mention that it returns
>zero to indicate the peer has closed the connection.  
>
>Throughout the socket documentation, ERRORS is not exhaustive.  write(2)
>for instance doesn't mention that EPIPE is set (or at least *should* be,
>after SIGPIPE) after writing to a closed connection.  Nor is ENETDOWN
>mentioned.  I could go on.  
>
>The thing is, I have a hard time believing this is an oversight, because
>NetBSD's ancestors practically invented tcp/ip.  Am I missing something,
>or does it fall to a nonexpert like me to take at least a swag at getting
>write(2) right?  
>
>In a similar vein, I'm not aware of anything that serves as a Guide to
>Sockets.  I don't mean Sockets for Novices; I mean something that relates
>the API to the TCP/IP protocol.  What packets does
>connect/bind/listen/accept/close cause to be sent?  What does select(2)
>mean by a "ready" descriptor?  (Hint: available data or free buffers is
>only one of four cases.)  How will i/o functions behave when the network
>can't transmit data, when the peer crashes, when the peer's host crashes,
>if I down the interface?  I propose sockets(7) for the purpose.  
>
>Perhaps some of the ambiguity and vagueness stems from uncertainty in
>flintlock times of what socket domain would be used.  All well and good,
>but surely we agree that TCP/IPv4 is commonly enough used nowadays that it
>deserves careful, detailed explication?  ;-)

You can start with the opengroup case, but they don't mention the network
related errors either. Perhaps mention that if the file descriptor refers
to a socket, then all the errors from send can be returned.

christos

[James K. Lowden-2]

Christos Zoulas wrote:
> >Throughout the socket documentation, ERRORS is not exhaustive.
> >write(2) for instance doesn't mention that EPIPE is set (or at least
> >*should* be, after SIGPIPE) after writing to a closed connection.  Nor
> >is ENETDOWN mentioned.  I could go on.  
>
> You can start with the opengroup case, but they don't mention the
> network related errors either. Perhaps mention that if the file
> descriptor refers to a socket, then all the errors from send can be
> returned.

Opengroup got that far:

http://www.opengroup.org/onlinepubs/000095399/functions/write.html

        "If fildes refers to a socket, write() shall be equivalent to send() with
no flags set."

I take it, though, that you mean our implementation asserts conformance
with SuSv3?  It's easy to document what these things are supposed to do;
it's hard to know exactly what's true about them.  

http://www.opengroup.org/comm/press/15feb06.htm 

I missed that announcement at the time.  IIUC, we can use opengroup's docs
verbatim?  That would be nice, particularly if they're in a format that is
or can be converted to mdoc.  Where are they?  

I'm confused about SuSv3, though.  Austin says it was approved in December
and is published by TOG.  I registered, yet everything I see at
http://www.unix.org/single_unix_specification/ says "The Open Group Base
Specifications Issue 6 IEEE Std 1003.1, 2004 Edition".  Not 2008.  

Perhaps we should adopt the opengroup socket API docs wholesale and edit
them for any specifics we already mention.  Then we can add to the BUGS
section whenever practice deviates from theory until a kernel hacker
narrows the difference.  

--jkl

[James K. Lowden-2]

James K. Lowden wrote:
> write(2)
> for instance doesn't mention that EPIPE is set (or at least *should* be,
> after SIGPIPE) after writing to a closed connection.  

Reply to self: this is in fact documented quite plainly.  Apologies.  

--jkl