socket(7) and section 2

["James K. Lowden" <jklowden%schemamania.org@localhost>]

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