diff options
Diffstat (limited to 'lib/kernel/doc/src/inet.xml')
| -rw-r--r-- | lib/kernel/doc/src/inet.xml | 181 |
1 files changed, 178 insertions, 3 deletions
diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml index bfdb163e17..a1590c2dce 100644 --- a/lib/kernel/doc/src/inet.xml +++ b/lib/kernel/doc/src/inet.xml @@ -371,7 +371,51 @@ fe80::204:acff:fe17:bf38 </taglist> </desc> </func> - + <func> + <name name="parse_ipv4_address" arity="1" /> + <fsummary>Parse an IPv4 address</fsummary> + <desc> + <p>Parses an IPv4 address string and returns an <a href="#type-ip4_address">ip4_address()</a>. + Accepts a shortened IPv4 shortened address string.</p> + </desc> + </func> + <func> + <name name="parse_ipv4strict_address" arity="1" /> + <fsummary>Parse an IPv4 address strict.</fsummary> + <desc> + <p>Parses an IPv4 address string containing four fields, i.e <b>not</b> shortened, and returns an <a href="#type-ip4_adress">ip4_address()</a>.</p> + </desc> + </func> + <func> + <name name="parse_ipv6_address" arity="1" /> + <fsummary>Parse an IPv6 address</fsummary> + <desc> + <p>Parses an IPv6 address string and returns an <a href="#type-ip6_address">ip6_address()</a>. + If an IPv4 address string is passed, an IPv4-mapped IPv6 address is returned.</p> + </desc> + </func> + <func> + <name name="parse_ipv6strict_address" arity="1" /> + <fsummary>Parse an IPv6 address strict.</fsummary> + <desc> + <p>Parses an IPv6 address string and returns an <a href="#type-ip6_address">ip6_address()</a>. + Does <b>not</b> accept IPv4 adresses.</p> + </desc> + </func> + <func> + <name name="parse_address" arity="1" /> + <fsummary>Parse an IPv4 or IPv6 address.</fsummary> + <desc> + <p>Parses an IPv4 or IPv6 address string and returns an <a href="#type-ip4_address">ip4_address()</a> or <a href="#type-ip6_address">ip6_address()</a>. Accepts a shortened IPv4 address string.</p> + </desc> + </func> + <func> + <name name="parse_strict_address" arity="1" /> + <fsummary>Parse an IPv4 or IPv6 address strict.</fsummary> + <desc> + <p>Parses an IPv4 or IPv6 address string and returns an <a href="#type-ip4_address">ip4_address()</a> or <a href="#type-ip6_adress">ip6_address()</a>. Does <b>not</b> accept a shortened IPv4 address string.</p> + </desc> + </func> <func> <name name="peername" arity="1"/> <fsummary>Return the address and port for the other end of a connection</fsummary> @@ -445,10 +489,24 @@ 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>{broadcast, Boolean}</c>(UDP sockets)</tag> <item> <p>Enable/disable permission to send broadcasts.</p> + <marker id="option-buffer"></marker> </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) >= 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 +521,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 +543,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 +555,7 @@ 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_msgq_watermark, Size}</c> (TCP/IP sockets)</tag> <item> <p>The socket message queue will be set into a busy @@ -505,6 +574,7 @@ fe80::204:acff:fe17:bf38 <seealso marker="erts:erlang#system_info_dist_buf_busy_limit">distribution buffer busy limit</seealso> which is a similar feature.</p> </item> + <tag><c>{high_watermark, Size}</c> (TCP/IP sockets)</tag> <item> <p>The socket will be set into a busy state when the amount @@ -517,6 +587,70 @@ fe80::204:acff:fe17:bf38 <c>high_msgq_watermark</c>, and <c>low_msqg_watermark</c> options.</p> </item> + + <tag><c>{ipv6_v6only, Boolean}</c></tag> + <item> + <p> + Restricts the socket to only use IPv6, prohibiting any + IPv4 connections. This is only applicable for + IPv6 sockets (option <c>inet6</c>). + </p> + <p> + On most platforms this option has to be set on the socket + before associating it to an address. Therefore it is only + reasonable to give it when creating the socket and not + to use it when calling the function + (<seealso marker="#setopts/2">setopts/2</seealso>) + containing this description. + </p> + <p> + The behaviour of a socket with this socket option set to + <c>true</c> is becoming the only portable one. The original + idea when IPv6 was new of using IPv6 for all traffic + is now not recommended by FreeBSD (you can use + <c>{ipv6_v6only,false}</c> to override the recommended + system default value), + forbidden by OpenBSD (the supported GENERIC kernel) + and impossible on Windows (that has separate + IPv4 and IPv6 protocol stacks). Most Linux distros + still have a system default value of <c>false</c>. + This policy shift among operating systems towards + separating IPv6 from IPv4 traffic has evolved since + it gradually proved hard and complicated to get + a dual stack implementation correct and secure. + </p> + <p> + On some platforms the only allowed value for this option + is <c>true</c>, e.g. OpenBSD and Windows. Trying to set + this option to <c>false</c> when creating the socket + will in this case fail. + </p> + <p> + Setting this option on platforms where it does not exist + is ignored and getting this option with + <seealso marker="#getopts/2">getopts/2</seealso> + returns no value i.e the returned list will not contain an + <c>{ipv6_v6only,_}</c> tuple. On Windows the option acually + does not exist, but it is emulated as being a + read-only option with the value <c>true</c>. + </p> + <p> + So it boils down to that setting this option to <c>true</c> + when creating a socket will never fail except possibly + (at the time of this writing) on a platform where you + have customized the kernel to only allow <c>false</c>, + which might be doable (but weird) on e.g. OpenBSD. + </p> + <p> + If you read back the option value using + <seealso marker="#getopts/2">getopts/2</seealso> + and get no value the option does not exist in the host OS + and all bets are off regarding the behaviour of both + an IPv6 and an IPv4 socket listening on the same port + as well as for an IPv6 socket getting IPv4 traffic. + </p> + </item> + <tag><c>{keepalive, Boolean}</c>(TCP/IP sockets)</tag> <item> <p>Enables/disables periodic transmission on a connected @@ -524,7 +658,19 @@ fe80::204:acff:fe17:bf38 the other end does not respond, the connection is considered broken and an error message will be sent to the controlling process. Default disabled.</p> + <marker id="option-linger"></marker> </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_msgq_watermark, Size}</c> (TCP/IP sockets)</tag> <item> <p>If the socket message queue is in a busy state, the @@ -545,6 +691,7 @@ fe80::204:acff:fe17:bf38 <seealso marker="erts:erlang#system_info_dist_buf_busy_limit">distribution buffer busy limit</seealso> which is a similar feature.</p> </item> + <tag><c>{low_watermark, Size}</c> (TCP/IP sockets)</tag> <item> <p>If the socket is in a busy state, the socket will @@ -559,6 +706,22 @@ fe80::204:acff:fe17:bf38 <c>high_msgq_watermark</c>, and <c>low_msgq_watermark</c> options.</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 @@ -642,6 +805,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 @@ -653,7 +826,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> @@ -682,9 +855,10 @@ fe80::204:acff:fe17:bf38 returns <c>{error,timeout}</c>. The recommended setting is <c>true</c> which will automatically close the socket. Default is <c>false</c> due to backward compatibility.</p> + <marker id="option-sndbuf"></marker> </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> @@ -703,6 +877,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 |