Implement socket option recvtos and friends

Implement socket options recvtclass, recvtos, recvttl and pktoptions.

Document the implemented socket options, new types and message formats.

The options recvtclass, recvtos and recvttl are boolean options that
when activated (true) for a socket will cause ancillary data to be
received through recvmsg().  That is for packet oriented sockets
(UDP and SCTP).

The required options for this feature were recvtclass and recvtos,
and recvttl was only added to test that the ancillary data parsing
handled multiple data items in one message correctly.

These options does not work on Windows since ancillary data
is not handled by the Winsock2 API.

For stream sockets (TCP) there is no clear connection between
a received packet and what is returned when reading data from
the socket, so recvmsg() is not useful.  It is possible to get
the same ancillary data through a getsockopt() call with
the IPv6 socket option IPV6_PKTOPTIONS, on Linux named
IPV6_2292PKTOPTIONS after the now obsoleted RFC where it originated.
(unfortunately RFC 3542 that obsoletes it explicitly undefines
 this way to get packet ancillary data from a stream socket)

Linux also has got a way to get packet ancillary data for IPv4
TCP sockets through a getsockopt() call with IP_PKTOPTIONS,
which appears to be Linux specific.

This implementation uses a flag field in the inet_drv.c socket
internal data that records if any setsockopt() call with recvtclass,
recvtos or recvttl (IPV6_RECVTCLASS, IP_RECVTOS or IP_RECVTTL)
has been activated.  If so recvmsg() is used instead of recvfrom().

Ancillary data is delivered to the application by a new return
tuple format from gen_udp:recv/2,3 containing a list of
ancillary data tuples [{tclass,TCLASS} | {tos,TOS} | {ttl,TTL}],
as returned by recvmsg().  For a socket in active mode a new
message format, containing the ancillary data list, delivers
the data in the same way.

For gen_sctp the ancillary data is delivered in the same way,
except that the gen_sctp return tuple format already contained
an ancillary data list so there are just more possible elements
when using these socket options.  Note that the active mode
message format has got an extra tuple level for the ancillary
data compared to what is now implemented gen_udp.
The gen_sctp active mode format was considered to be the odd one
- now all tuples containing ancillary data are flat,
except for gen_sctp active mode.

Note that testing has not shown that Linux SCTP sockets deliver
any ancillary data for these socket options, so it is probably
not implemented yet.  Remains to be seen what FreeBSD does...

For gen_tcp inet:getopts([pktoptions]) will deliver the latest
received ancillary data for any activated socket option recvtclass,
recvtos or recvttl, on platforms where IP_PKTOPTIONS is defined
for an IPv4 socket, or where IPV6_PKTOPTIONS or IPV6_2292PKTOPTIONS
is defined for an IPv6 socket.  It will be delivered as a
list of ancillary data items in the same way as for gen_udp
(and gen_sctp).

On some platforms, e.g the BSD:s, when you activate IP_RECVTOS
you get ancillary data tagged IP_RECVTOS with the TOS value,
but on Linux you get ancillary data tagged IP_TOS with the
TOS value.  Linux follows the style of RFC 2292, and the BSD:s
use an older notion.  For RFC 2292 that defines the IP_PKTOPTIONS
socket option it is more logical to tag the items with the
tag that is the item's, than with the tag that defines that you
want the item.  Therefore this implementation translates all
BSD style ancillary data tags to the corresponding Linux style
data tags, so the application will only see the tags 'tclass',
'tos' and 'ttl' on all platforms.

4 files changed, 230 insertions, 13 deletions

diff --git a/lib/kernel/doc/src/gen_sctp.xml b/lib/kernel/doc/src/gen_sctp.xml
index 737800c6b1..1e08b25f66 100644
--- a/lib/kernel/doc/src/gen_sctp.xml
+++ b/lib/kernel/doc/src/gen_sctp.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>2007</year><year>2016</year>
+      <year>2007</year><year>2018</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -331,6 +331,37 @@ connect(Socket, Ip, Port>,
 	  with <anno>SockType</anno> <c>seqpacket</c>, and with reasonably large
           <seealso marker="inet#option-sndbuf">kernel</seealso> and driver
           <seealso marker="inet#option-buffer">buffers</seealso>.</p>
+	<p>
+	  If the socket is in
+          <seealso marker="#option-active">passive</seealso>
+	  mode data can be received through the
+          <seealso marker="#recv/1"><c>recv/1,2</c></seealso>
+	  calls.
+	</p>
+	<p>
+	  If the socket is in
+          <seealso marker="#option-active">active</seealso>
+	  mode data received data is delivered to the controlling process
+	  as messages:
+	</p>
+        <code type="none">
+{sctp, <anno>Socket</anno>, FromIP, FromPort, {AncData, Data}}
+	</code>
+	<p>
+	  See
+	  <seealso marker="#recv/1"><c>recv/1,2</c></seealso>
+	  for a description of the message fields.
+	</p>
+	<note>
+	  <p>
+	    This message format unfortunately differs slightly from the
+	    <seealso marker="gen_udp#open/1"><c>gen_udp</c></seealso>
+	    message format with ancillary data,
+	    and from the
+	    <seealso marker="#recv/1"><c>recv/1,2</c></seealso>
+	    return tuple format.
+	  </p>
+	</note>
       </desc>
     </func>
 
@@ -380,6 +411,19 @@ connect(Socket, Ip, Port>,
           socket option
           <seealso marker="#option-sctp_get_peer_addr_info"><c>sctp_get_peer_addr_info</c></seealso>,
           but this does still not produce the stream number).</p>
+	<p>
+	  <c><anno>AncData</anno></c> may also contain
+	  <seealso marker="inet#type-ancillary_data">
+	    ancillary data
+	  </seealso>
+	  from the socket
+	  <seealso marker="#type-option">options</seealso>
+	  <seealso marker="inet#option-recvtos"><c>recvtos</c></seealso>,
+	  <seealso marker="inet#option-recvtclass"><c>recvtclass</c></seealso>
+	  or
+	  <seealso marker="inet#option-recvttl"><c>recvttl</c></seealso>,
+	  if that is supported by the platform for the socket.
+	</p>
         <p>The <c><anno>Data</anno></c> received can be a <c>binary()</c>
           or a <c>list()</c> of bytes (integers in the range 0 through 255)
           depending on the socket mode, or an SCTP event.</p>
@@ -544,12 +588,25 @@ connect(Socket, Ip, Port>,
               <seealso marker="#recv/1"><c>recv</c></seealso> call
               to retrieve the available data from the socket.</p>
           </item>
+	  <item>
+	    <p>
+	      If <c>true|once|N</c> (active modes)
+	      received data or events are sent to the owning process.
+	      See <seealso marker="#open/0"><c>open/0..2</c></seealso>
+	      for the message format.
+	    </p>
+	  </item>
           <item>
-            <p>If <c>true</c> (full active mode), the pending data or events are
-              sent to the owning process.</p>
-            <p>Notice that this can cause the message queue to overflow,
-              as there is no way to throttle the sender in this case
-              (no flow control).</p>
+            <p>
+	      If <c>true</c> (full active mode) there is no flow control.
+	    </p>
+	    <note>
+              <p>
+		Note that this can cause the message queue to overflow
+		causing for example the virtual machine
+		to run out of memory and crash.
+	      </p>
+	    </note>
           </item>
           <item>
             <p>If <c>once</c>, only one message is automatically placed
diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml
index e6104b0c76..cf649991d0 100644
--- a/lib/kernel/doc/src/gen_tcp.xml
+++ b/lib/kernel/doc/src/gen_tcp.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1997</year><year>2017</year>
+      <year>1997</year><year>2018</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -70,6 +70,20 @@ do_recv(Sock, Bs) ->
       <name name="option"/>
     </datatype>
     <datatype>
+      <name name="pktoptions_value"/>
+      <desc>
+	<p>
+	  If the platform implements the IPv4 option
+	  <c>IP_PKTOPTIONS</c> (probably Linux specific), or the IPv6 option
+	  <c>IPV6_PKTOPTIONS</c> or <c>IPV6_2292PKTOPTIONS</c> for the socket
+	  this value is returned from
+	  <seealso marker="inet#getopts/2"><c>inet:getopts/2</c></seealso>
+	  when called with the option name
+	  <seealso marker="#type-option_name"><c>pktoptions</c></seealso>.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
       <name name="option_name"/>
     </datatype>
     <datatype>
diff --git a/lib/kernel/doc/src/gen_udp.xml b/lib/kernel/doc/src/gen_udp.xml
index f79566ef71..840ca3c188 100644
--- a/lib/kernel/doc/src/gen_udp.xml
+++ b/lib/kernel/doc/src/gen_udp.xml
@@ -4,7 +4,7 @@
 <erlref>
   <header>
     <copyright>
-      <year>1997</year><year>2016</year>
+      <year>1997</year><year>2018</year>
       <holder>Ericsson AB. All Rights Reserved.</holder>
     </copyright>
     <legalnotice>
@@ -147,7 +147,21 @@
           at the opened port, if the socket is in an active mode, the packets
           are delivered as messages to the controlling process:</p>
         <code type="none">
-{udp, Socket, IP, InPortNo, Packet}</code>
+{udp, Socket, IP, InPortNo, Packet} % Without ancillary data
+{udp, Socket, IP, InPortNo, AncData, Packet} % With ancillary data
+	</code>
+	<p>
+	  The message contains an <c>AncData</c> field
+	  if any of the socket
+	  <seealso marker="#type-option">options</seealso>
+	  <seealso marker="inet#option-recvtos"><c>recvtos</c></seealso>,
+	  <seealso marker="inet#option-recvtclass"><c>recvtclass</c></seealso>
+	  or
+	  <seealso marker="inet#option-recvttl"><c>recvttl</c></seealso>
+	  are active, otherwise it does not.
+	</p>
+	<p>
+	</p>
         <p>If the socket is not in an active mode, data can be
           retrieved through the
           <seealso marker="#recv/2"><c>recv/2,3</c></seealso> calls.
@@ -179,9 +193,22 @@
       <name name="recv" arity="3"/>
       <fsummary>Receive a packet from a passive socket.</fsummary>
       <desc>
-        <p>Receives a packet from a socket in passive mode. Optional parameter
+        <p>
+	  Receives a packet from a socket in passive mode. Optional parameter
           <c><anno>Timeout</anno></c> specifies a time-out in milliseconds.
-          Defaults to <c>infinity</c>.</p>
+          Defaults to <c>infinity</c>.
+	</p>
+	<p>
+	  If any of the socket
+	  <seealso marker="#type-option">options</seealso>
+	  <seealso marker="inet#option-recvtos"><c>recvtos</c></seealso>,
+	  <seealso marker="inet#option-recvtclass"><c>recvtclass</c></seealso>
+	  or
+	  <seealso marker="inet#option-recvttl"><c>recvttl</c></seealso>
+	  are active, the <c><anno>RecvData</anno></c> tuple contains an
+	  <c><anno>AncData</anno></c> field,
+	  otherwise it does not.
+	</p>
       </desc>
     </func>
 
diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml
index f281d61459..ed775d67eb 100644
--- a/lib/kernel/doc/src/inet.xml
+++ b/lib/kernel/doc/src/inet.xml
@@ -177,6 +177,27 @@ fe80::204:acff:fe17:bf38
       </desc>
     </datatype>
     <datatype>
+      <name name="ancillary_data"/>
+      <desc>
+	<p>
+	  Ancillary data received with the data packet
+	  or read with the socket option
+	  <seealso marker="gen_tcp#type-pktoptions_value">
+	    <c>pktoptions</c>
+	  </seealso>
+	  from a TCP socket.
+	</p>
+	<p>
+	  The value(s) correspond to the currently active socket
+	  <seealso marker="#type-socket_setopt">options</seealso>
+	  <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>.
+	</p>
+      </desc>
+    </datatype>
+    <datatype>
       <name name="posix"/>
       <desc>
         <p>An atom that is named from the POSIX error codes used in Unix,
@@ -344,7 +365,11 @@ fe80::204:acff:fe17:bf38
       <desc>
         <p>Gets one or more options for a socket. For a list of available
           options, see
-          <seealso marker="#setopts/2"><c>setopts/2</c></seealso>.</p>
+          <seealso marker="#setopts/2"><c>setopts/2</c></seealso>.
+	  See also the description for the type
+          <seealso marker="gen_tcp#type-pktoptions_value">
+	    <c>gen_tcp:pktoptions_value()</c>
+	  </seealso>.</p>
         <p>The number of elements in the returned
           <c><anno>OptionValues</anno></c>
           list does not necessarily correspond to the number of options
@@ -360,7 +385,7 @@ fe80::204:acff:fe17:bf38
           socket options not (explicitly) supported by the emulator. The
           use of raw socket options makes the code non-portable, but
           allows the Erlang programmer to take advantage of unusual features
-          present on the current platform.</p>
+          present on a particular platform.</p>
         <p><c>RawOptReq</c> consists of tag <c>raw</c> followed
           by the protocol level, the option number, and either a binary
           or the size, in bytes, of the
@@ -1115,6 +1140,100 @@ setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp</code>
               the socket. You are encouraged to use
               <seealso marker="#getopts/2"><c>getopts/2</c></seealso>
               to retrieve the size set by your operating system.</p>
+	    <marker id="option-recvtclass"></marker>
+          </item>
+          <tag><c>{recvtclass, Boolean}</c></tag>
+          <item>
+            <p>
+	      If set to <c>true</c> activates returning the received
+	      <c>TCLASS</c> value on platforms that implements
+	      the protocol <c>IPPROTO_IPV6</c>
+	      option <c>IPV6_RECVTCLASS</c> or <c>IPV6_2292RECVTCLASS</c>
+	      for the socket.
+	      The value is returned as a <c>{tclass,TCLASS}</c> tuple
+	      regardless of if the platform returns an <c>IPV6_TCLASS</c>
+	      or an <c>IPV6_RECVTCLASS</c> CMSG value.
+	    </p>
+	    <p>
+	      For packet oriented sockets that supports receiving
+	      ancillary data with the payload data
+	      (<c>gen_udp</c> and <c>gen_sctp</c>),
+	      the <c>TCLASS</c> value is returned
+	      in an extended return tuple contained in an
+	      <seealso marker="inet#type-ancillary_data">
+		ancillary data
+	      </seealso>
+	      list.
+	      For stream oriented sockets (<c>gen_tcp</c>)
+	      the only way to get the <c>TCLASS</c>
+	      value is if the platform supports the
+	      <seealso marker="gen_tcp#type-pktoptions_value">
+		<c>pktoptions</c>
+	      </seealso>
+	      option.
+	    </p>
+	    <marker id="option-recvtos"></marker>
+          </item>
+          <tag><c>{recvtos, Boolean}</c></tag>
+          <item>
+            <p>
+	      If set to <c>true</c> activates returning the received
+	      <c>TOS</c> value on platforms that implements
+	      the protocol <c>IPPROTO_IP</c> option <c>IP_RECVTOS</c>
+	      for the socket.
+	      The value is returned as a <c>{tos,TOS}</c> tuple
+	      regardless of if the platform returns an <c>IP_TOS</c>
+	      or an <c>IP_RECVTOS</c> CMSG value.
+	    </p>
+	    <p>
+	      For packet oriented sockets that supports receiving
+	      ancillary data with the payload data
+	      (<c>gen_udp</c> and <c>gen_sctp</c>),
+	      the <c>TOS</c> value is returned
+	      in an extended return tuple contained in an
+	      <seealso marker="inet#type-ancillary_data">
+		ancillary data
+	      </seealso>
+	      list.
+	      For stream oriented sockets (<c>gen_tcp</c>)
+	      the only way to get the <c>TOS</c>
+	      value is if the platform supports the
+	      <seealso marker="gen_tcp#type-pktoptions_value">
+		<c>pktoptions</c>
+	      </seealso>
+	      option.
+	    </p>
+	    <marker id="option-recvttl"></marker>
+          </item>
+          <tag><c>{recvttl, Boolean}</c></tag>
+          <item>
+            <p>
+	      If set to <c>true</c> activates returning the received
+	      <c>TTL</c> value on platforms that implements
+	      the protocol <c>IPPROTO_IP</c> option <c>IP_RECVTTL</c>
+	      for the socket.
+	      The value is returned as a <c>{ttl,TTL}</c> tuple
+	      regardless of if the platform returns an <c>IP_TTL</c>
+	      or an <c>IP_RECVTTL</c> CMSG value.
+	    </p>
+	    <p>
+	      For packet oriented sockets that supports receiving
+	      ancillary data with the payload data
+	      (<c>gen_udp</c> and <c>gen_sctp</c>),
+	      the <c>TTL</c> value is returned
+	      in an extended return tuple contained in an
+	      <seealso marker="inet#type-ancillary_data">
+		ancillary data
+	      </seealso>
+	      list.
+	      For stream oriented sockets (<c>gen_tcp</c>)
+	      the only way to get the <c>TTL</c>
+	      value is if the platform supports the
+	      <seealso marker="gen_tcp#type-pktoptions_value">
+		<c>pktoptions</c>
+	      </seealso>
+	      option.
+	    </p>
           </item>
           <tag><c>{reuseaddr, Boolean}</c></tag>
           <item>