[PATCH] manual: Improve documentation of the shutdown function

[Collin Funk]

Florian Weimer <fweimer@redhat.com> writes:

> Document the SHUT_* constants and attempt to explain the
> implications for Linux TCP and UNIX domain sockets.
>
> The Linux TCP behavior was discovered when writing the
> socket/tst-shutdown test.
>
> Suggested by Sergey Organov in
> <http://inbox.sourceware.org/libc-alpha/qblfrh$4m4i$1@blaine.gmane.org>.
>
> ---
>  manual/socket.texi | 45 +++++++++++++++++++++++++++++++++------------
>  1 file changed, 33 insertions(+), 12 deletions(-)
>
> diff --git a/manual/socket.texi b/manual/socket.texi
> index d804c7a48b..c9dfd81f5c 100644
> --- a/manual/socket.texi
> +++ b/manual/socket.texi
> @@ -2317,22 +2317,23 @@ The @code{shutdown} function shuts down the connection of socket
>  @var{socket}.  The argument @var{how} specifies what action to
>  perform:
>  
> -@table @code
> -@item 0
> -Stop receiving data for this socket.  If further data arrives,
> -reject it.
> +@vtable @code
> +@item SHUT_RD
> +Stop receiving data on the socket.

Surprisingly, these values aren't required to be 0, 1, and 2 by POSIX. I
can't think of any system where they are something different, though.

Regardless, it is better to not promote the use of magic numbers.

> +Additional errors can be reported for specific socket types.
> +
> +The exact impact of the @code{shutdown} function depends on the socket
> +protocol and its implementation.  In portable code, the @code{shutdown}
> +function cannot be used on its own to gracefully terminate a connection
> +which is operated in full-duplex mode (with both peers sending data).
> +
> +On Linux, when @code{SHUT_RD} is used to shut down a TCP socket, any
> +pending data in the incoming socket buffer and any data that arrives
> +subsequently is discarded, without reporting an error or generating a
> +TCP RST segment.  Future @code{read} function calls on the socket return
> +zero.  (Other systems may treat @code{SHUT_RD} with pending data as a
> +data loss event and generate RST segments.  Linux
> +@code{AF_LOCAL}/@code{AF_UNIX} sockets also report errors to peers.)
> +
> +Similarly, when @code{SHUT_WR} is used on a Linux TCP socket, a FIN
> +segment is sent to the peer, ordered after any data written previously
> +to the socket.  After encountering the FIN segment, the peer will
> +recognize this as an end-of-stream condition.
> +

That looks correct based on my reading of socket/tst-shutdown.

Is it worth writing "@code{read} or @code{recv}" instead of just
"@code{read}"? If someone is new to socket programming and is trying to
learn from reading code they may see either, since both work equally
well in most cases. That topic is introduced later in the manual, so
referencing both might clear up potential confusion.

Anyways, that is a minor thing, so:

Reviewed-by: Collin Funk <collin.funk1@gmail.com>

Collin