aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc
diff options
context:
space:
mode:
authorLukas Larsson <[email protected]>2017-03-16 10:38:23 +0100
committerLukas Larsson <[email protected]>2017-03-28 08:22:16 +0200
commit1b4dedb155a4fe6faf35448c2d119e391204701a (patch)
tree3d4f0074e5df6983bb55769b4dd03f5709e392f3 /lib/kernel/doc
parent1cbc44aa05d4abf958e4bf7d5014668df3d98e90 (diff)
downloadotp-1b4dedb155a4fe6faf35448c2d119e391204701a.tar.gz
otp-1b4dedb155a4fe6faf35448c2d119e391204701a.tar.bz2
otp-1b4dedb155a4fe6faf35448c2d119e391204701a.zip
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.
Diffstat (limited to 'lib/kernel/doc')
-rw-r--r--lib/kernel/doc/src/gen_tcp.xml17
-rw-r--r--lib/kernel/doc/src/inet.xml2
2 files changed, 18 insertions, 1 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>
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>