manual: Improve documentation of the shutdown function

Message ID 871s0xqul6.fsf@oldenburg2.str.redhat.com
State New
Headers show
Series
  • manual: Improve documentation of the shutdown function
Related show

Commit Message

Florian Weimer May 17, 2019, 9:49 a.m.
Document the SHUT_* constants and attempt to explain the high-level
implications of the BSD-style TCP implementation on connection
teardown.

Suggested by Sergey Organov in
<https://sourceware.org/ml/libc-help/2019-05/msg00016.html>.

2019-05-17  Florian Weimer  <fweimer@redhat.com>

	* manual/socket.texi (Closing a Socket): Mention SHUT_* constants.
	Mention the non-blocking nature of the shutdown operation.
	Describe the full-duplex connectio teardown problem.

Patch

diff --git a/manual/socket.texi b/manual/socket.texi
index cd7c0e7b12..3451afeff8 100644
--- a/manual/socket.texi
+++ b/manual/socket.texi
@@ -2257,22 +2257,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.
 
-@item 1
-Stop trying to transmit data from this socket.  Discard any data
-waiting to be sent.  Stop looking for acknowledgement of data already
-sent; don't retransmit it if it is lost.
+@item SHUT_WR
+Indicate to the peer that no further data will be transmitted on the
+socket.  This indication is ordered with regard to past send
+operations on the socket, and data pending at the time of the call is
+still delivered.
 
-@item 2
-Stop both reception and transmission.
-@end table
+@item SHUT_RDWR
+Combine the actions of @code{SHUT_RD} and @code{SHUT_WR}.
+@end vtable
 
 The return value is @code{0} on success and @code{-1} on failure.  The
-following @code{errno} error conditions are defined for this function:
+following generic @code{errno} error conditions are defined for this
+function:
 
 @table @code
 @item EBADF
@@ -2286,6 +2287,19 @@  following @code{errno} error conditions are defined for this function:
 @end table
 @end deftypefun
 
+The exact impact of the @code{shutdown} function depends on the socket
+protocol and its implementation.  For TCP, the function does not block
+and performs the operation in the background.  If shutting down (or
+closing) a TCP socket causes data to be discarded, TCP treats this as
+a data-loss event and resets the connection.  This can, in turn,
+discard data which has been transmitted in the other direction on the
+same connection.  Therefore, 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).  Instead, a
+higher-level handshake has to be performed, and the socket should be
+shut down after the other peer has acknowledged the end of the
+receiving operation (using a protocol message above the TCP layer).
+
 @node Socket Pairs
 @subsection Socket Pairs
 @cindex creating a socket pair