Inadequate documentation: sockets

[Alessandro Baretta <alex@baretta.com>]

Hello everybody!

I am a newbie in this list, so please accept my apologies for not
being adeqately informed on many technical issues many a kernel
programmer might consider banal.

I wish to bring your attention to the documentation available on
the topic of of the _disconnection_ of stream oriented sockets.
I'm writing a user space program that uses TCP sockets. I need to
know if and when a given connection is broken, and more
specifically if and when _one_ direction of the stream is shut
down by the peer. The following documentation seems to apply to my
case:

1) man poll:
The manual specifies the following flag to be returned by the
kernel
> #define POLLHUP     0x0010    /* Hung up */

Hanging up is ambiguous. Does it mean that the client is dead,
that he closed his end of the socket, or that he shut down one or
both directions of the data flow? The following man page clears
this up, but I think the following information would best be
placed in man poll.

2) man 7 socket
> The user can then wait for
> various events via poll(2) or select(2).

      
+-----------+-----------+--------------------------------------------+
       |Read       | POLLHUP   | A disconnection request has been
initiated |
       |           |           | by the other
end.                          |
      
+-----------+-----------+--------------------------------------------+
       |Read       | POLLHUP   | A connection is broken (only 
for  connec­ |
       |           |           | tion-oriented protocols).  When
the socket |
       |           |           | is writen SIGPIPE is also
sent.            |
      
+-----------+-----------+--------------------------------------------+
      
+-----------+-----------+--------------------------------------------+
       |Read/Write | POLLHUP   | The other end has shut down one
direction. |
      
+-----------+-----------+--------------------------------------------+

This means that I get a POLLHUP in all the time, but it does not
allow me to distinguish among the three different relevant cases:
a) the client shutting down reads only, b) the client shutting
down writes only, c) the client going down entirely.

I figured the following documentation might help, but it did not.
3) man 2 send
>ERRORS
>       EPIPE  The  local  end  has been shut down on a connection
>              oriented socket.  In this  case  the  process  will
>              also  receive a SIGPIPE unless MSG_NOSIGNAL is set.
4) man recv
>       The flags argument to a recv call is formed by OR'ing  one
>       or more of the following values:
>       MSG_NOSIGNAL
>              This flag turns off raising of  SIGPIPE  on  stream
>              sockets when the other end disappears.
Yet, although the manpage mentions an MSG_NOSIGNAL flag, it never
mentions either raising a SIGPIPE when the socket is disconnected,
nor setting errno to EPIPE upon execution of recv on a socket
closed by the peer. This is very ambiguous. I would be very
greatful to anyone who clear up this point.

Finally I'm left with my original problem: how am I supposed to
detect a close or a shutdown from the peer? Once again, I thank in
advance anyone who will lend me a hand by explaining this to me or
by addressing me to more adequate documentation.

Thanks for your kind interest.

Alex Baretta