File 1280-Improve-documentation-for-gen_tcp-recv-3.patch of Package erlang

From 90df8acc3ec6ad769bc013722e78bb0353908ab2 Mon Sep 17 00:00:00 2001
From: Andrea leopardi <an.leopardi@gmail.com>
Date: Sun, 23 Apr 2023 15:21:54 +0200
Subject: [PATCH] Improve documentation for gen_tcp:recv/3

The first part of this patch only highlights the word "passive" in the
documentation for gen_tcp:recv/3, to emphasize that this function only
works in passive mode.

The second part adds a note saying that calling gen_tcp:recv/3 on
an active socket returns {error, einval}.

The last part of the patch adds a paragraph to the documentation for
gen_tcp:recv/3 mentioning what happens when multiple processes call
recv/3 on the same socket. This was previously not documented.
---
 lib/kernel/doc/src/gen_tcp.xml | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml
index e455cfdaf5..0aced6bfa8 100644
--- a/lib/kernel/doc/src/gen_tcp.xml
+++ b/lib/kernel/doc/src/gen_tcp.xml
@@ -539,9 +539,10 @@ do_recv(Sock, Bs) ->
       in ERTS.
       </type_desc>
       <desc>
-        <p>Receives a packet from a socket in passive
+        <p>Receives a packet from a socket in <em>passive</em>
           mode. A closed socket is indicated by return value
-          <c>{error, closed}</c>.</p>
+          <c>{error, closed}</c>. If the socket is not in passive mode,
+          the return value is <c>{error, einval}</c>.</p>
         <p>Argument <c><anno>Length</anno></c> is only meaningful when
           the socket is in <c>raw</c> mode and denotes the number of
           bytes to read. If <c><anno>Length</anno></c> is <c>0</c>, all
@@ -552,6 +553,12 @@ do_recv(Sock, Bs) ->
           data when the socket is closed from the other side.</p>
         <p>The optional <c><anno>Timeout</anno></c> parameter specifies a
           time-out in milliseconds. Defaults to <c>infinity</c>.</p>
+        <p>Any process can receive data from a passive socket, even if that
+          process is not the controlling process of the socket. However,
+          only one process can call this function on a socket at any given time.
+          Using simultaneous calls to <c>recv</c> is not recommended as its behavior
+          is dependent on the socket implementation, and could return errors
+          such as <c>{error, ealready}</c>.</p>
       </desc>
     </func>
 
-- 
2.35.3