From patchwork Fri May 17 09:49:25 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Florian Weimer X-Patchwork-Id: 32737 Received: (qmail 53365 invoked by alias); 17 May 2019 09:49:30 -0000 Mailing-List: contact libc-alpha-help@sourceware.org; run by ezmlm Precedence: bulk List-Id: List-Unsubscribe: List-Subscribe: List-Archive: List-Post: List-Help: , Sender: libc-alpha-owner@sourceware.org Delivered-To: mailing list libc-alpha@sourceware.org Received: (qmail 53353 invoked by uid 89); 17 May 2019 09:49:30 -0000 Authentication-Results: sourceware.org; auth=none X-Spam-SWARE-Status: No, score=-19.1 required=5.0 tests=AWL, BAYES_00, GIT_PATCH_0, GIT_PATCH_1, GIT_PATCH_2, GIT_PATCH_3, SPF_HELO_PASS autolearn=ham version=3.3.1 spammy=transmission, highlevel, high-level, treats X-HELO: mx1.redhat.com From: Florian Weimer To: libc-alpha@sourceware.org Cc: Sergey Organov Subject: [PATCH] manual: Improve documentation of the shutdown function Date: Fri, 17 May 2019 11:49:25 +0200 Message-ID: <871s0xqul6.fsf@oldenburg2.str.redhat.com> User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/26.1 (gnu/linux) MIME-Version: 1.0 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 . 2019-05-17 Florian Weimer * 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. 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