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