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: 1100932 Return-Path: X-Original-To: incoming@patchwork.ozlabs.org Delivered-To: patchwork-incoming@bilbo.ozlabs.org Authentication-Results: ozlabs.org; spf=pass (mailfrom) smtp.mailfrom=sourceware.org (client-ip=209.132.180.131; helo=sourceware.org; envelope-from=libc-alpha-return-102081-incoming=patchwork.ozlabs.org@sourceware.org; receiver=) Authentication-Results: ozlabs.org; dmarc=fail (p=none dis=none) header.from=redhat.com Authentication-Results: ozlabs.org; dkim=pass (1024-bit key; secure) header.d=sourceware.org header.i=@sourceware.org header.b="GjkeW5UI"; dkim-atps=neutral Received: from sourceware.org (server1.sourceware.org [209.132.180.131]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ozlabs.org (Postfix) with ESMTPS id 4553RP3cpqz9sB3 for ; Fri, 17 May 2019 19:49:37 +1000 (AEST) DomainKey-Signature: a=rsa-sha1; c=nofws; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:from:to:cc:subject:date:message-id :mime-version:content-type; q=dns; s=default; b=VFZQudl/ogi/DJdh T+KSdffy2ArxZpVD+MQA0X2a6i5QFoY5kJsFFfi5h97RbQC1eQvZbliV664IfZGr YtCiKtostBkhsMEWcnl/u7YK4N1uD7CaAs3Dr5d5Pa+JrzW1e0MYhSGOS2/zZtHd 4Qk+UaimioMZSTkM82QjLZ7eE3I= DKIM-Signature: v=1; a=rsa-sha1; c=relaxed; d=sourceware.org; h=list-id :list-unsubscribe:list-subscribe:list-archive:list-post :list-help:sender:from:to:cc:subject:date:message-id :mime-version:content-type; s=default; bh=ZQoGNg4GEljosLCOjyqnCr T4gUg=; b=GjkeW5UIoqJP+ZnRbDdFyktsnm2S+fOT0esg9ajCwCjiQqgRIf7E1V dit5AH7nUfpBmTHy6BsmG2LkE4WNgKhJm7limJSGxhbNZp+pGXyjJ48I5IiIrK11 uFAAjhicBTsLXqyZbWDhf7hfWxArcOkLPcWskJTPtZ5BXxYxZTRhc= 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