controlling_process can return {error, badarg}

For gen_tcp, gen_udp and gen_sctp controlling_process/2 can return
badarg if erlang:port_connect/2 fails with badarg. This can easily
happen if the new owner is not alive but in some race condition also
when the socket is closed right before port_connect/2 (and after the
previous socket function)
This commit documents this behaviour.

5 files changed, 13 insertions, 5 deletions

diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml
index 08454b9832..e97db20062 100644
--- a/lib/kernel/doc/src/gen_tcp.xml
+++ b/lib/kernel/doc/src/gen_tcp.xml
@@ -231,7 +231,11 @@ do_recv(Sock, Bs) ->
           <c><anno>Socket</anno></c>. The controlling process is the process
           that receives messages from the socket. If called by any other
           process than the current controlling process,
-          <c>{error, not_owner}</c> is returned.</p>
+          <c>{error, not_owner}</c> is returned. If the process identified
+          by <c><anno>Pid</anno></c> is not an existing local pid,
+          <c>{error, badarg}</c> is returned. <c>{error, badarg}</c> may also
+          be returned in some cases when <c><anno>Socket</anno></c> is closed
+          during the execution of this function.</p>
           <p>If the socket is set in active mode, this function
           will transfer any messages in the mailbox of the caller
           to the new controlling process.
diff --git a/lib/kernel/doc/src/gen_udp.xml b/lib/kernel/doc/src/gen_udp.xml
index 3f88a0272d..f79566ef71 100644
--- a/lib/kernel/doc/src/gen_udp.xml
+++ b/lib/kernel/doc/src/gen_udp.xml
@@ -68,7 +68,11 @@
           <c><anno>Socket</anno></c>. The controlling process is the process
           that receives messages from the socket. If called by any other
           process than the current controlling process,
-          <c>{error, not_owner}</c> is returned.</p>
+          <c>{error, not_owner}</c> is returned. If the process identified
+          by <c><anno>Pid</anno></c> is not an existing local pid,
+          <c>{error, badarg}</c> is returned. <c>{error, badarg}</c> may also
+          be returned in some cases when <c><anno>Socket</anno></c> is closed
+          during the execution of this function.</p>
       </desc>
     </func>
 
diff --git a/lib/kernel/src/gen_sctp.erl b/lib/kernel/src/gen_sctp.erl
index b133e6fed4..a6aa0edd15 100644
--- a/lib/kernel/src/gen_sctp.erl
+++ b/lib/kernel/src/gen_sctp.erl
@@ -439,7 +439,7 @@ error_string(X) ->
 -spec controlling_process(Socket, Pid) -> ok | {error, Reason} when
       Socket :: sctp_socket(),
       Pid :: pid(),
-      Reason :: closed | not_owner | inet:posix().
+      Reason :: closed | not_owner | badarg | inet:posix().
 
 controlling_process(S, Pid) when is_port(S), is_pid(Pid) ->
     inet:udp_controlling_process(S, Pid);
diff --git a/lib/kernel/src/gen_tcp.erl b/lib/kernel/src/gen_tcp.erl
index 1a21541b7c..ac61dbc792 100644
--- a/lib/kernel/src/gen_tcp.erl
+++ b/lib/kernel/src/gen_tcp.erl
@@ -320,7 +320,7 @@ unrecv(S, Data) when is_port(S) ->
 -spec controlling_process(Socket, Pid) -> ok | {error, Reason} when
       Socket :: socket(),
       Pid :: pid(),
-      Reason :: closed | not_owner | inet:posix().
+      Reason :: closed | not_owner | badarg | inet:posix().
 
 controlling_process(S, NewOwner) ->
     case inet_db:lookup_socket(S) of
diff --git a/lib/kernel/src/gen_udp.erl b/lib/kernel/src/gen_udp.erl
index 98d2f0bcfb..3121544719 100644
--- a/lib/kernel/src/gen_udp.erl
+++ b/lib/kernel/src/gen_udp.erl
@@ -195,7 +195,7 @@ connect(S, Address, Port) when is_port(S) ->
 -spec controlling_process(Socket, Pid) -> ok | {error, Reason} when
       Socket :: socket(),
       Pid :: pid(),
-      Reason :: closed | not_owner | inet:posix().
+      Reason :: closed | not_owner | badarg | inet:posix().
 
 controlling_process(S, NewOwner) ->
     inet:udp_controlling_process(S, NewOwner).