Merge branch 'egil/inet-document-options/OTP-10053' into maint

* egil/inet-document-options/OTP-10053:
  kernel: Document ifaddr option
  kernel: Document tcp-, udp- and sctp_module option
  kernel: Remove bit8 option in spec
  kernel: Document bit8 option in inet:setopts/2
  kernel: Initial doc of forgotten inet options

5 files changed, 194 insertions, 43 deletions

diff --git a/lib/kernel/doc/src/gen_sctp.xml b/lib/kernel/doc/src/gen_sctp.xml
index 579b7f1f74..cf1cfb6ec9 100644
--- a/lib/kernel/doc/src/gen_sctp.xml
+++ b/lib/kernel/doc/src/gen_sctp.xml
@@ -530,19 +530,8 @@
               SCTP data interleaved with other inter-process messages.</p>
           </item>
         </list>
-        <marker id="option-buffer"></marker>
       </item>
-      <tag><c>{buffer, integer()}</c></tag>
-      <item>
-        <p>Determines the size of the user-level software buffer used by
-          the SCTP driver. Not to be confused with <c>sndbuf</c>
-          and <c>recbuf</c> options which correspond to
-          the kernel socket buffers. It is recommended
-          to have <c>val(buffer) &gt;= max(val(sndbuf),val(recbuf))</c>.
-          In fact, the <c>val(buffer)</c> is automatically set to
-          the above maximum when <c>sndbuf</c> or <c>recbuf</c> values are set.</p>
-      </item>
-      <tag><c>{tos, integer()}</c></tag>
+     <tag><c>{tos, integer()}</c></tag>
       <item>
         <p>Sets the Type-Of-Service field on the IP datagrams being sent,
           to the given value, which effectively determines a prioritization
@@ -567,19 +556,8 @@
           <c>{IP,Port}</c> of the socket can be re-used immediately:
           no waiting in the CLOSE_WAIT state is performed (may be
           required for high-throughput servers).</p>
-        <marker id="option-linger"></marker>
-      </item>
-      <tag><c>{linger, {true|false, integer()}</c></tag>
-      <item>
-        <p>Determines the timeout in seconds for flushing unsent data in the
-          <c>gen_sctp:close/1</c> socket call. If the 1st component of the value
-          tuple is <c>false</c>, the 2nd one is ignored, which means that
-          <c>gen_sctp:close/1</c> returns immediately not waiting
-          for data to be flushed. Otherwise, the 2nd component is
-          the flushing time-out in seconds.</p>
-        <marker id="option-sndbuf"></marker>
       </item>
-      <tag><c>{sndbuf, integer()}</c></tag>
+	  <tag><c>{sndbuf, integer()}</c></tag>
       <item>
         <p>The size, in bytes, of the *kernel* send buffer for this socket.
           Sending errors would occur for datagrams larger than
@@ -593,6 +571,15 @@
           <c>val(sndbuf)</c>. Setting this option also adjusts
           the size of the driver buffer (see <c>buffer</c> above).</p>
       </item>
+
+		  <tag><c>{sctp_module, module()}</c></tag>
+		  <item> <p>
+				  Override which callback module used. Defaults to
+				  <c>inet_sctp</c> for IPv4 and <c>inet6_sctp</c> for IPv6.
+			  </p>
+		  </item>
+
+
       <tag><c>{sctp_rtoinfo, #sctp_rtoinfo{}}</c></tag>
       <item>
 <pre>  #sctp_rtoinfo{
diff --git a/lib/kernel/doc/src/gen_tcp.xml b/lib/kernel/doc/src/gen_tcp.xml
index cf97607af1..869e305690 100644
--- a/lib/kernel/doc/src/gen_tcp.xml
+++ b/lib/kernel/doc/src/gen_tcp.xml
@@ -96,37 +96,47 @@ do_recv(Sock, Bs) ->
           can be either a hostname, or an IP address.</p>
         <p>The available options are:</p>
         <taglist>
-          <tag><c>list</c></tag>
-          <item>
-            <p>Received <c>Packet</c> is delivered as a list.</p>
-          </item>
-          <tag><c>binary</c></tag>
-          <item>
-            <p>Received <c>Packet</c> is delivered as a binary.</p>
-          </item>
-          <tag><c>{ip, ip_address()}</c></tag>
+         <tag><c>{ip, ip_address()}</c></tag>
           <item>
             <p>If the host has several network interfaces, this option
               specifies which one to use.</p>
           </item>
-          <tag><c>{port, Port}</c></tag>
+
+		  <tag><c>{ifaddr, ip_address()}</c></tag>
           <item>
-            <p>Specify which local port number to use.</p>
-          </item>
+			  <p>Same as <c>{ip, ip_address()}</c>. If the host has several network interfaces, this option
+              specifies which one to use.</p>
+		  </item>
+
           <tag><c>{fd, integer() >= 0}</c></tag>
           <item>
             <p>If a socket has somehow been connected without using
               <c>gen_tcp</c>, use this option to pass the file
               descriptor for it.</p>
           </item>
-          <tag><c>inet6</c></tag>
+
+          <tag><c>inet</c></tag>
           <item>
+            <p>Set up the socket for IPv4.</p>
+          </item>
+
+		  <tag><c>inet6</c></tag>
+		  <item>
             <p>Set up the socket for IPv6.</p>
           </item>
-          <tag><c>inet</c></tag>
+
+          <tag><c>{port, Port}</c></tag>
           <item>
-            <p>Set up the socket for IPv4.</p>
+            <p>Specify which local port number to use.</p>
           </item>
+
+		  <tag><c>{tcp_module, module()}</c></tag>
+		  <item> <p>
+				  Override which callback module used. Defaults to
+				  <c>inet_tcp</c> for IPv4 and <c>inet6_tcp</c> for IPv6.
+			  </p>
+		  </item>
+
           <tag><c>Opt</c></tag>
           <item>
             <p>See
@@ -197,6 +207,13 @@ do_recv(Sock, Bs) ->
               <c>gen_tcp</c>, use this option to pass the file
               descriptor for it.</p>
           </item>
+
+		  <tag><c>{ifaddr, ip_address()}</c></tag>
+          <item>
+			  <p>Same as <c>{ip, ip_address()}</c>. If the host has several network interfaces, this option
+              specifies which one to use.</p>
+		  </item>
+
           <tag><c>inet6</c></tag>
           <item>
             <p>Set up the socket for IPv6.</p>
@@ -205,6 +222,14 @@ do_recv(Sock, Bs) ->
           <item>
             <p>Set up the socket for IPv4.</p>
           </item>
+
+		  <tag><c>{tcp_module, module()}</c></tag>
+		  <item> <p>
+				  Override which callback module used. Defaults to
+				  <c>inet_tcp</c> for IPv4 and <c>inet6_tcp</c> for IPv6.
+			  </p>
+		  </item>
+
           <tag><c>Opt</c></tag>
           <item>
             <p>See
diff --git a/lib/kernel/doc/src/gen_udp.xml b/lib/kernel/doc/src/gen_udp.xml
index daa9b7d887..77e6182884 100644
--- a/lib/kernel/doc/src/gen_udp.xml
+++ b/lib/kernel/doc/src/gen_udp.xml
@@ -72,6 +72,14 @@
             <p>If the host has several network interfaces, this option
               specifies which one to use.</p>
           </item>
+
+		  <tag><c>{ifaddr, ip_address()}</c></tag>
+          <item>
+			  <p>Same as <c>{ip, ip_address()}</c>. If the host has several network interfaces, this option
+              specifies which one to use.</p>
+		  </item>
+
+
           <tag><c>{fd, integer() >= 0}</c></tag>
           <item>
             <p>If a socket has somehow been opened without using
@@ -86,6 +94,51 @@
           <item>
             <p>Set up the socket for IPv4.</p>
           </item>
+
+		  <tag><c>{udp_module, module()}</c></tag>
+		  <item> <p>
+				  Override which callback module used. Defaults to
+				  <c>inet_udp</c> for IPv4 and <c>inet6_udp</c> for IPv6.
+			  </p>
+		  </item>
+
+          <tag><c>{multicast_if, Address}</c></tag>
+          <item>
+			  <p>Set the local device for a multicast socket.</p>
+          </item>
+ 
+          <tag><c>{multicast_loop, true | false}</c></tag>
+          <item>
+			  <p>
+				  When <c>true</c> sent multicast packets will be looped back to the local
+				  sockets.
+			  </p>
+          </item>
+
+          <tag><c>{multicast_ttl, Integer}</c></tag>
+          <item>
+			  <p>
+				  The <c>multicast_ttl</c> option changes the time-to-live (TTL) for
+				  outgoing multicast datagrams in order to control the scope of the 
+				  multicasts.
+			  </p>
+			  <p>
+				  Datagrams with a TTL of 1 are not forwarded beyond the local
+				  network.
+				  <br />Default: 1
+			  </p>
+          </item>
+
+		  <tag><c>{add_membership, {MultiAddress, InterfaceAddress}}</c></tag>
+          <item>
+			  <p>Join a multicast group. </p>
+          </item>
+
+		  <tag><c>{drop_membership, {MultiAddress, InterfaceAddress}}</c></tag>
+          <item>
+			  <p>Leave multicast group.</p>
+          </item>
+
           <tag><c>Opt</c></tag>
           <item>
             <p>See
diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml
index bf6c4cfb1a..522a27dcfa 100644
--- a/lib/kernel/doc/src/inet.xml
+++ b/lib/kernel/doc/src/inet.xml
@@ -445,10 +445,33 @@ fe80::204:acff:fe17:bf38
               flow control; the other side will not be able send
               faster than the receiver can read.</p>
           </item>
+
+		  <tag><c>{bit8, clear | set | on | off}</c></tag>
+		  <item>
+			  <p>
+				  Scans every byte in received data-packets and checks if the 8 bit
+				  is set in any of them. Information is retrieved with
+				  <c>inet:getopts/2</c>.
+				  <note>Deprecated! Will be removed in Erlang/OTP R16.</note>
+			  </p>
+		  </item>
+
           <tag><c>{broadcast, Boolean}</c>(UDP sockets)</tag>
           <item>
             <p>Enable/disable permission to send broadcasts.</p>
           </item>
+
+		  <tag><c>{buffer, Size}</c></tag>
+		  <item>
+			  <p>Determines the size of the user-level software buffer used by
+				  the driver. Not to be confused with <c>sndbuf</c>
+				  and <c>recbuf</c> options which correspond to
+				  the kernel socket buffers. It is recommended
+				  to have <c>val(buffer) &gt;= max(val(sndbuf),val(recbuf))</c>.
+				  In fact, the <c>val(buffer)</c> is automatically set to
+				  the above maximum when <c>sndbuf</c> or <c>recbuf</c> values are set.</p>
+		  </item>
+
           <tag><c>{delay_send, Boolean}</c></tag>
           <item>
             <p>Normally, when an Erlang process sends to a socket,
@@ -463,10 +486,19 @@ fe80::204:acff:fe17:bf38
               real property of the socket. Needless to say it is an
               implementation specific option. Default is <c>false</c>.</p>
           </item>
+
+		  <tag><c>{deliver, port | term}</c></tag>
+		  <item> <p> When <c>{active, true}</c> delivers data on the forms
+				  <c>port</c> : <c>{S, {data, [H1,..Hsz | Data]}}</c> or
+				  <c>term</c> : <c>{tcp, S, [H1..Hsz | Data]}</c>.
+				  </p>
+		  </item>
+
           <tag><c>{dontroute, Boolean}</c></tag>
           <item>
             <p>Enable/disable routing bypass for outgoing messages.</p>
           </item>
+
           <tag><c>{exit_on_close, Boolean}</c></tag>
           <item>
             <p>By default this option is set to <c>true</c>.</p>
@@ -476,6 +508,7 @@ fe80::204:acff:fe17:bf38
               <seealso marker="gen_tcp#shutdown/2">gen_tcp:shutdown/2</seealso>
               to shutdown the write side.</p>
           </item>
+
           <tag><c>{header, Size}</c></tag>
           <item>
             <p>This option is only meaningful if the <c>binary</c>
@@ -487,6 +520,15 @@ fe80::204:acff:fe17:bf38
               example <c>Size == 2</c>, the data received will match
               <c>[Byte1,Byte2|Binary]</c>.</p>
           </item>
+
+		  <tag><c>{high_watermark, Size}</c></tag>
+		  <item> <p>
+				  Sender is forced busy if sent and equeued data
+				  readched the highwater mark.
+				  <br /> Default: 8192 kB. 
+			  </p>
+		  </item>
+
           <tag><c>{keepalive, Boolean}</c>(TCP/IP sockets)</tag>
           <item>
             <p>Enables/disables periodic transmission on a connected
@@ -495,6 +537,41 @@ fe80::204:acff:fe17:bf38
               considered broken and an error message will be sent to
               the controlling process. Default disabled.</p>
           </item>
+
+		  <tag><c>{linger, {true|false, Seconds}}</c></tag>
+		  <item>
+			  <p>Determines the timeout in seconds for flushing unsent data in the
+				  <c>close/1</c> socket call. If the 1st component of the value
+				  tuple is <c>false</c>, the 2nd one is ignored, which means that
+				  <c>close/1</c> returns immediately not waiting
+				  for data to be flushed. Otherwise, the 2nd component is
+				  the flushing time-out in seconds.</p>
+		  </item>
+
+		  <tag><c>{low_watermark, Size}</c></tag>
+		  <item> <p>
+				  If the port has reached its <c>high_watermark</c> it will
+				  force busy onto senders. When the port data queue reaches the
+				  <c>low_watermark</c> callers are no longer forced busy.
+				  <br /> Default: 4096 kB. 
+			  </p>
+		  </item>
+
+		  <tag><c>{mode, Mode :: binary | list}</c></tag>
+          <item>
+			  <p>Received <c>Packet</c> is delivered as defined by Mode.</p>
+		  </item>
+
+		  <tag><c>list</c></tag>
+          <item>
+			  <p>Received <c>Packet</c> is delivered as a list.</p>
+		  </item>
+
+		  <tag><c>binary</c></tag>
+          <item>
+			  <p>Received <c>Packet</c> is delivered as a binary.</p>
+		  </item>
+
           <tag><c>{nodelay, Boolean}</c>(TCP/IP sockets)</tag>
           <item>
             <p>If <c>Boolean == true</c>, the <c>TCP_NODELAY</c> option
@@ -578,6 +655,16 @@ fe80::204:acff:fe17:bf38
 	    indicated length are accepted and not considered invalid due
 	    to internal buffer limitations.</p>
           </item>
+
+		  <tag><c>{priority, Priority}</c></tag>
+          <item> <p>Set the protocol-defined priority for all packets to be sent
+			  on this socket.</p>
+		  </item>
+
+		  <tag><c>{raw, Protocol, OptionNum, ValueBin}</c></tag>
+          <item> <p>See below.</p>
+		  </item>
+
           <tag><c>{read_packets, Integer}</c>(UDP sockets)</tag>
           <item>
             <p>Sets the max number of UDP packets to read without
@@ -589,7 +676,7 @@ fe80::204:acff:fe17:bf38
               high the system can become unresponsive due to
               UDP packet flooding.</p>
           </item>
-          <tag><c>{recbuf, Integer}</c></tag>
+          <tag><c>{recbuf, Size}</c></tag>
           <item>
             <p>Gives the size of the receive buffer to use for
               the socket.</p>
@@ -620,7 +707,7 @@ fe80::204:acff:fe17:bf38
               Default is <c>false</c> due to backward compatibility.</p>
           </item>
 
-          <tag><c>{sndbuf, Integer}</c></tag>
+          <tag><c>{sndbuf, Size}</c></tag>
           <item>
             <p>Gives the size of the send buffer to use for the socket.</p>
           </item>
@@ -639,6 +726,7 @@ fe80::204:acff:fe17:bf38
               not implemented. Use with caution.</p>
           </item>
         </taglist>
+
         <p>In addition to the options mentioned above, <em>raw</em>
           option specifications can be used. The raw options are
           specified as a tuple of arity four, beginning with the tag
diff --git a/lib/kernel/src/gen_tcp.erl b/lib/kernel/src/gen_tcp.erl
index ef6bfdf7f4..e6dfdadb03 100644
--- a/lib/kernel/src/gen_tcp.erl
+++ b/lib/kernel/src/gen_tcp.erl
@@ -31,7 +31,6 @@
 
 -type option() ::
         {active,          true | false | once} |
-        {bit8,            clear | set | on | off} |
         {buffer,          non_neg_integer()} |
         {delay_send,      boolean()} |
         {deliver,         port | term} |
@@ -61,7 +60,6 @@
         {tos,             non_neg_integer()}.
 -type option_name() ::
         active |
-        bit8 |
         buffer |
         delay_send |
         deliver |