Merge branch 'raimo/receive-TOS-TCLASS/ERIERL-187/OTP-15145' into maint

* raimo/receive-TOS-TCLASS/ERIERL-187/OTP-15145:
  Write testcases for recvtos and friends
  Fix term buffer overflow bug
  Fix documentation due to feedback
  Implement socket option recvtos and friends

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>