e594f0dd8e
Document the SHUT_* constants and attempt to explain the implications for Linux TCP and UNIX domain sockets. Resolves: RHEL-117418
86 lines
3.2 KiB
Diff
86 lines
3.2 KiB
Diff
commit afce5fccdf680113cdb6fc44d1b4ca7daea42c25
|
|
Author: Florian Weimer <fweimer@redhat.com>
|
|
Date: Thu Sep 25 08:37:13 2025 +0200
|
|
|
|
manual: Improve documentation of the shutdown function
|
|
|
|
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
|
|
<https://inbox.sourceware.org/libc-help/qblfrh$4m4i$1@blaine.gmane.org/>.
|
|
|
|
Reviewed-by: Collin Funk <collin.funk1@gmail.com>
|
|
|
|
diff --git a/manual/socket.texi b/manual/socket.texi
|
|
index d804c7a48b..56948073d5 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.
|
|
|
|
-@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
|
|
@@ -2346,6 +2347,27 @@ following @code{errno} error conditions are defined for this function:
|
|
@end table
|
|
@end deftypefun
|
|
|
|
+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. Attempts to read data from this socket using
|
|
+@code{recv} and similar functions (@pxref{Receiving Data}) 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.
|
|
+
|
|
@node Socket Pairs
|
|
@subsection Socket Pairs
|
|
@cindex creating a socket pair
|