Inadequate documentation: sockets

Inadequate documentation: sockets

[Alessandro Baretta]

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

Re: Inadequate documentation: sockets

[Alan Cox]

> =46inally 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.

By an EOF on read or getting SIGPIPE/EPIPE on a write. You might want to pick
up a book on the subject of network programming. There are some very nice ones
around

Re: Inadequate documentation: sockets

[Khalid Aziz]

Alan Cox wrote:
> 
> > =46inally 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.
> 
> By an EOF on read or getting SIGPIPE/EPIPE on a write. You might want to pick
> up a book on the subject of network programming. There are some very nice ones
> around

As Alan already pointed out, a book on network programming can answer
these questions. I would recommend "UNIX Network Programming, Volume 1:
Networking APIs - Sockets and XTI" by W. Richard Stevens.

-- 
Khalid

====================================================================
Khalid Aziz                             Linux Development Laboratory
(970)898-9214                                        Hewlett-Packard
khalid@fc.hp.com                                    Fort Collins, CO

Re: Inadequate documentation: sockets

[kuznet]

Hello!

> 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.

The information is is not quite correct.

POLLHUP is really ambigous in the case of full-duplex connections
with bi-directional close sort of TCP. However, invariants are:

* POLLHUP is set when connection is closed in both directions.
* POLLHUP implies that descriptor is not-writable and any write
  will cause error and, probably, SIGPIPE.
* POLLHUP is _not_ set when descriptor is writable (i.e. connection
  is shutdowned in write direction by remote)

Standards require that POLLHUP and POLLOUT never happened
together, however linux does this, which is formally bug.
However, it is not fixed, assuming that POLLHUP overrides POLLOUT.


> Finally I'm left with my original problem: how am I supposed to
> detect a close or a shutdown from the peer?

By EOF. No other way exists. POLLHUP is local condition, only
local side can close connection in write direction. Exception
is abort (reset) initiated by peer.


> by addressing me to more adequate documentation.

UNIX98 and Austin draft pages. The are very ambiguous though.

Alexey

Re: Inadequate documentation: sockets

[Alessandro Baretta]

kuznet@ms2.inr.ac.ru wrote:
> 
> Hello!
> 
> > The manual specifies the following flag to be returned by the
> > kernel
> > [smip]
> 
> The information is is not quite correct.
> [snip]

The information you gave me sounds interesting, but it is conflict
with the documentation. This was my original assertion: the
documentation on the subject is inadequate.

> > Finally I'm left with my original problem: how am I supposed to
> > detect a close or a shutdown from the peer?
> 
> By EOF. No other way exists. POLLHUP is local condition, only
> local side can close connection in write direction. Exception
> is abort (reset) initiated by peer.

What do you mean by "local condition"? You surely do not mean that
the event which provokes the POLLHUP occours on my host? What
about a shutdown(sock, SHUT_RD) called by the peer?

> > by addressing me to more adequate documentation.
> 
> UNIX98 and Austin draft pages. The are very ambiguous though.
> 
Hmmmm....

Thank you very much!

Alex

P.S. Alexey, I meant this post to be for the list. The copy I sent
to you privately is my mistake.