From 1b4dedb155a4fe6faf35448c2d119e391204701a Mon Sep 17 00:00:00 2001
From: Lukas Larsson <lukas@erlang.org>
Date: Thu, 16 Mar 2017 10:38:23 +0100
Subject: kernel: Expand gen_tcp:close docs with send text

This commit attempts to clarify some of the guarantees given by
the TCP standard when issuing close. This is quite a complex
topic so there are probably corner cases still left, but this
at least tells the user that things can go wrong when doing
a close.
---
 lib/kernel/doc/src/gen_tcp.xml | 17 +++++++++++++++++
 lib/kernel/doc/src/inet.xml    |  2 +-
 2 files changed, 18 insertions(+), 1 deletion(-)

(limited to 'lib/kernel')

diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml
index e97db20062..bef8096aed 100644
--- a/lib/kernel/doc/src/gen_tcp.xml
+++ b/lib/kernel/doc/src/gen_tcp.xml
@@ -140,6 +140,23 @@ do_recv(Sock, Bs) ->
       <fsummary>Close a TCP socket.</fsummary>
       <desc>
         <p>Closes a TCP socket.</p>
+        <p>Note that in most implementations of TCP, doing a <c>close</c> does
+         not guarantee that any data sent is delivered to the recipient before
+         the close is detected at the remote side. If you want to guarantee
+         delivery of the data to the recipient there are two common ways to
+         achieve this.</p>
+         <list type="ordered">
+           <item><p>Use <seealso marker="#shutdown/2">
+             <c>gen_tcp:shutdown(Sock, write)</c></seealso> to signal that
+             no more data is to be sent and wait for the read side of the
+             socket to be closed.</p>
+           </item>
+           <item><p>Use the socket option <seealso marker="inet#packet">
+             <c>{packet, N}</c></seealso> (or something similar) to make
+             it possible for the receiver to close the connection when it
+             knowns it has received all the data.</p>
+           </item>
+         </list>
       </desc>
     </func>
 
diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml
index 4c4a5c39cb..36a99f7a7a 100644
--- a/lib/kernel/doc/src/inet.xml
+++ b/lib/kernel/doc/src/inet.xml
@@ -909,7 +909,7 @@ setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp</code>
           </item>
           <tag><c>{packet, PacketType}</c>(TCP/IP sockets)</tag>
           <item>
-            <p>Defines the type of packets to use for a socket.
+            <p><marker id="packet"/>Defines the type of packets to use for a socket.
 	      Possible values:</p>
             <taglist>
               <tag><c>raw | 0</c></tag>
-- 
cgit v1.2.3