From abf6018726321a920948d9ba6dcea7f4047a4e4a Mon Sep 17 00:00:00 2001
From: Raimo Niskanen <raimo@erlang.org>
Date: Thu, 23 May 2019 12:27:34 +0200
Subject: Introduce udp send ancillary data argument down to inet_drv

---
 lib/kernel/doc/src/gen_udp.xml | 87 ++++++++++++++++++++++++++++++++++++++++--
 lib/kernel/doc/src/inet.xml    | 50 ++++++++++++++++++++++--
 2 files changed, 130 insertions(+), 7 deletions(-)

(limited to 'lib/kernel/doc/src')

diff --git a/lib/kernel/doc/src/gen_udp.xml b/lib/kernel/doc/src/gen_udp.xml
index d20fc1fdfd..6c0d072fed 100644
--- a/lib/kernel/doc/src/gen_udp.xml
+++ b/lib/kernel/doc/src/gen_udp.xml
@@ -213,12 +213,93 @@
     </func>
 
     <func>
-      <name name="send" arity="4" since=""/>
+      <name name="send" arity="3" since="OTP @OTP-15747@"/>
       <fsummary>Send a packet.</fsummary>
       <desc>
         <p>
-	  Sends a packet to the specified address and port. Argument
-          <c><anno>Address</anno></c> can be a hostname or a socket address.
+	  Sends a packet to the specified <c><anno>Destination</anno></c>.
+	</p>
+	<p>
+	  This function is equivalent to
+	  <seealso marker="#send-4-AncData"><c>send(<anno>Socket</anno>, <anno>Destination</anno>, [], <anno>Packet</anno>)</c></seealso>.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="send" arity="4" clause_i="1" since=""/>
+      <fsummary>Send a packet.</fsummary>
+      <desc>
+        <p>
+	  Sends a packet to the specified <c><anno>Host</anno></c>
+	  and <c><anno>Port</anno></c>.
+	</p>
+	<p>
+	  This clause is equivalent to
+	  <seealso marker="#send/5"><c>send(<anno>Socket</anno>, <anno>Host</anno>, <anno>Port</anno>, [], <anno>Packet</anno>)</c></seealso>.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="send" arity="4" clause_i="2" anchor="send-4-AncData" since="OTP @OTP-15747@"/>
+      <fsummary>Send a packet.</fsummary>
+      <desc>
+        <p>
+	  Sends a packet to the specified <c><anno>Destination</anno></c>
+	  with ancillary data <c><anno>AncData</anno></c>.
+	</p>
+	<note>
+	  <p>
+	    The ancillary data <c><anno>AncData</anno></c>
+	    contains options that for this single message
+	    override the default options for the socket,
+	    an operation that may not be supported on all platforms,
+	    and if so return <c>{error, einval}</c>.
+	    Using more than one of an ancillary data item type
+	    may also not be supported.
+	    <c><anno>AncData</anno> =:= []</c> is always supported.
+	  </p>
+	</note>
+      </desc>
+    </func>
+
+    <func>
+      <name name="send" arity="4" clause_i="3" since="OTP @OTP-15747@"/>
+      <fsummary>Send a packet.</fsummary>
+      <desc>
+        <p>
+	  Sends a packet to the specified <c><anno>Destination</anno></c>.
+	  Since <c><anno>Destination</anno></c> is complete,
+	  <c><anno>PortZero</anno></c> is redundant and has to be <c>0</c>.
+	</p>
+	<p>
+	  This is a legacy clause mostly for
+	  <c><anno>Destination</anno> = {local, Binary}</c>
+	  where <c><anno>PortZero</anno></c> is superfluous.
+	  It is equivalent to
+	  <seealso marker="#send-4-AncData"><c>send(<anno>Socket</anno>, <anno>Destination</anno>, [], <anno>Packet</anno>)</c></seealso>, the clause right above here.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name name="send" arity="5" since="OTP @OTP-15747@"/>
+      <fsummary>Send a packet.</fsummary>
+      <desc>
+        <p>
+	  Sends a packet to the specified <c><anno>Host</anno></c>
+	  and <c><anno>Port</anno></c>,
+	  with ancillary data <c><anno>AncData</anno></c>.
+	</p>
+	<p>
+	  Argument <c><anno>Host</anno></c> can be
+	  a hostname or a socket address,
+	  and <c><anno>Port</anno></c> can be a port number
+	  or a service name atom.
+	  These are resolved into a <c>Destination</c> and after that
+	  this function is equivalent to
+	  <seealso marker="#send-4-AncData"><c>send(<anno>Socket</anno>, Destination, <anno>AncData</anno>, <anno>Packet</anno>)</c></seealso>, read there about ancillary data.
 	</p>
       </desc>
     </func>
diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml
index 5e33bbc3ff..adaa2684d8 100644
--- a/lib/kernel/doc/src/inet.xml
+++ b/lib/kernel/doc/src/inet.xml
@@ -117,6 +117,42 @@ fe80::204:acff:fe17:bf38
     <datatype>
       <name name="port_number"/>
     </datatype>
+    <datatype>
+      <name name="family_address" since="OTP @OTP-15747@"/>
+      <desc>
+	<p>
+	  A general address format on the form <c>{Family, Destination}</c>
+	  where <c>Family</c> is an atom such as <c>local</c>
+	  and the format of <c>Destination</c> depends on <c>Family</c>,
+	  and is a complete address
+	  (for example an IP address including port number).
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="inet_address" since="OTP @OTP-15747@"/>
+      <desc>
+	<warning>
+	  <p>
+	    This address format is for now experimental
+	    and for completeness to make all address families have a
+	    <c>{Family, Destination}</c> representation.
+	  </p>
+	</warning>
+      </desc>
+    </datatype>
+    <datatype>
+      <name name="inet6_address" since="OTP @OTP-15747@"/>
+      <desc>
+	<warning>
+	  <p>
+	    This address format is for now experimental
+	    and for completeness to make all address families have a
+	    <c>{Family, Destination}</c> representation.
+	  </p>
+	</warning>
+      </desc>
+    </datatype>
     <datatype>
       <name name="local_address"/>
       <desc>
@@ -180,12 +216,16 @@ fe80::204:acff:fe17:bf38
       <name name="ancillary_data"/>
       <desc>
 	<p>
-	  Ancillary data received with the data packet
-	  or read with the socket option
+	  Ancillary data received with the data packet,
+	  read with the socket option
 	  <seealso marker="gen_tcp#type-pktoptions_value">
 	    <c>pktoptions</c>
 	  </seealso>
-	  from a TCP socket.
+	  from a TCP socket,
+	  or to set in a call to
+	  <seealso marker="gen_udp#send-4-AncData"><c>gen_udp:send/4</c></seealso>
+	  or
+	  <seealso marker="gen_udp#send/5"><c>gen_udp:send/5</c></seealso>.
 	</p>
 	<p>
 	  The value(s) correspond to the currently active socket
@@ -193,7 +233,9 @@ fe80::204:acff:fe17:bf38
 	  <seealso marker="inet#option-recvtos"><c>recvtos</c></seealso>,
 	  <seealso marker="inet#option-recvtclass"><c>recvtclass</c></seealso>
 	  and
-	  <seealso marker="inet#option-recvttl"><c>recvttl</c></seealso>.
+	  <seealso marker="inet#option-recvttl"><c>recvttl</c></seealso>,
+	  or for a single send operation the option(s) to override
+	  the currently active socket option(s).
 	</p>
       </desc>
     </datatype>
-- 
cgit v1.2.3