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.

1 files changed, 17 insertions, 0 deletions

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>