diff options
Diffstat (limited to 'lib/kernel/doc/src/inet.xml')
| -rw-r--r-- | lib/kernel/doc/src/inet.xml | 155 |
1 files changed, 102 insertions, 53 deletions
diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml index 4a48a5c3d8..088d78c1d6 100644 --- a/lib/kernel/doc/src/inet.xml +++ b/lib/kernel/doc/src/inet.xml @@ -4,20 +4,21 @@ <erlref> <header> <copyright> - <year>1997</year><year>2013</year> + <year>1997</year><year>2015</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> - The contents of this file are subject to the Erlang Public License, - Version 1.1, (the "License"); you may not use this file except in - compliance with the License. You should have received a copy of the - Erlang Public License along with this software. If not, it can be - retrieved online at http://www.erlang.org/. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 - Software distributed under the License is distributed on an "AS IS" - basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See - the License for the specific language governing rights and limitations - under the License. + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -116,8 +117,9 @@ fe80::204:acff:fe17:bf38 </desc> </datatype> <datatype> - <name><marker id="type-socket">socket()</marker></name> - <desc><p>See <seealso marker="gen_tcp#type-socket">gen_tcp(3)</seealso> + <name>socket()</name> + <desc><p><marker id="type-socket"></marker> + See <seealso marker="gen_tcp#type-socket">gen_tcp(3)</seealso> and <seealso marker="gen_udp#type-socket">gen_udp(3)</seealso>.</p> </desc> </datatype> @@ -138,7 +140,7 @@ fe80::204:acff:fe17:bf38 <name name="get_rc" arity="0"/> <fsummary>Return a list of IP configuration parameters</fsummary> <desc> - <p>Returns the state of the Inet configuration database in + <p>Returns the state of the Inet configuration database in form of a list of recorded configuration parameters. (See the ERTS User's Guide, Inet configuration, for more information). Only parameters with other than default values are returned.</p> @@ -221,7 +223,7 @@ fe80::204:acff:fe17:bf38 </p> <p> Do not rely too much on the order of <c><anno>Flag</anno></c> atoms or - <c><anno>Ifopt</anno></c> tuples. There are some rules, though: + <c><anno>Ifopt</anno></c> tuples. There are some rules, though:</p> <list> <item> Immediately after <c>{addr,_}</c> follows <c>{netmask,_}</c> @@ -237,7 +239,6 @@ fe80::204:acff:fe17:bf38 tuple concerns that address. </item> </list> - </p> <p> The <c>{hwaddr,_}</c> tuple is not returned on Solaris since the hardware address historically belongs to the link layer and only @@ -258,8 +259,8 @@ fe80::204:acff:fe17:bf38 <type name="socket_getopt"/> <type name="socket_setopt"/> <desc> - <p>Gets one or more options for a socket. - See <seealso marker="#setopts/2">setopts/2</seealso> + <p>Gets one or more options for a socket. + See <seealso marker="#setopts/2">setopts/2</seealso> for a list of available options.</p> <p>The number of elements in the returned <c><anno>OptionValues</anno></c> list does not necessarily correspond to the number of options @@ -278,14 +279,14 @@ fe80::204:acff:fe17:bf38 by the protocol level, the option number and either a binary or the size, in bytes, of the buffer in which the option value is to be stored. A binary - should be used when the underlying <c>getsockopt</c> requires + should be used when the underlying <c>getsockopt</c> requires <em>input</em> in the argument field, in which case the size of the binary should correspond to the required buffer size of the return value. The supplied values in a <c>RawOptReq</c> correspond to the second, third and fourth/fifth parameters to the <c>getsockopt</c> call in the C socket API. The value stored - in the buffer is returned as a binary <c>ValueBin</c> + in the buffer is returned as a binary <c>ValueBin</c> where all values are coded in the native endianess.</p> <p>Asking for and inspecting raw socket options require low level information about the current operating system and TCP @@ -306,7 +307,7 @@ fe80::204:acff:fe17:bf38 value to be a 32 bit integer. We could use the following code to retrieve the value:</p> <code type="none"><![CDATA[ - get_tcpi_sacked(Sock) -> + get_tcpi_sacked(Sock) -> {ok,[{raw,_,_,Info}]} = inet:getopts(Sock,[{raw,6,11,92}]), <<_:28/binary,TcpiSacked:32/native,_/binary>> = Info, TcpiSacked.]]></code> @@ -332,23 +333,23 @@ fe80::204:acff:fe17:bf38 <taglist> <tag><c>recv_avg</c></tag> <item> - <p>Average size of packets in bytes received to the socket.</p> + <p>Average size of packets in bytes received by the socket.</p> </item> <tag><c>recv_cnt</c></tag> <item> - <p>Number of packets received to the socket.</p> + <p>Number of packets received by the socket.</p> </item> <tag><c>recv_dvi</c></tag> <item> - <p>Average packet size deviation in bytes received to the socket.</p> + <p>Average packet size deviation in bytes received by the socket.</p> </item> <tag><c>recv_max</c></tag> <item> - <p>The size of the largest packet in bytes received to the socket.</p> + <p>The size of the largest packet in bytes received by the socket.</p> </item> <tag><c>recv_oct</c></tag> <item> - <p>Number of bytes received to the socket.</p> + <p>Number of bytes received by the socket.</p> </item> <tag><c>send_avg</c></tag> @@ -361,7 +362,7 @@ fe80::204:acff:fe17:bf38 </item> <tag><c>send_dvi</c></tag> <item> - <p>Average packet size deviation in bytes received sent from the socket.</p> + <p>Average packet size deviation in bytes sent from the socket.</p> </item> <tag><c>send_max</c></tag> <item> @@ -378,14 +379,14 @@ fe80::204:acff:fe17:bf38 <name name="ntoa" arity="1" /> <fsummary>Convert IPv6 / IPV4 adress to ascii</fsummary> <desc> - <p>Parses an <a href="#type-ip_address">ip_address()</a> and returns an IPv4 or IPv6 address string.</p> + <p>Parses an <seealso marker="#type-ip_address">ip_address()</seealso> and returns an IPv4 or IPv6 address string.</p> </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>. + <p>Parses an IPv4 address string and returns an <seealso marker="#type-ip4_address">ip4_address()</seealso>. Accepts a shortened IPv4 shortened address string.</p> </desc> </func> @@ -393,14 +394,14 @@ fe80::204:acff:fe17:bf38 <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> + <p>Parses an IPv4 address string containing four fields, i.e <em>not</em> shortened, and returns an <seealso marker="#type-ip4_address">ip4_address()</seealso>.</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>. + <p>Parses an IPv6 address string and returns an <seealso marker="#type-ip6_address">ip6_address()</seealso>. If an IPv4 address string is passed, an IPv4-mapped IPv6 address is returned.</p> </desc> </func> @@ -408,22 +409,22 @@ fe80::204:acff:fe17:bf38 <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> + <p>Parses an IPv6 address string and returns an <seealso marker="#type-ip6_address">ip6_address()</seealso>. + Does <em>not</em> 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> + <p>Parses an IPv4 or IPv6 address string and returns an <seealso marker="#type-ip4_address">ip4_address()</seealso> or <seealso marker="#type-ip6_address">ip6_address()</seealso>. 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> + <p>Parses an IPv4 or IPv6 address string and returns an <seealso marker="#type-ip4_address">ip4_address()</seealso> or <seealso marker="#type-ip6_address">ip6_address()</seealso>. Does <em>not</em> accept a shortened IPv4 address string.</p> </desc> </func> <func> @@ -613,15 +614,20 @@ fe80::204:acff:fe17:bf38 <marker id="option-buffer"></marker> </item> - <tag><c>{buffer, Size}</c></tag> + <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> + <p>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> to + avoid performance issues due to unnecessary copying. + 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. + However, since the actual sizes set for <c>sndbuf</c> and <c>recbuf</c> + usually becomes larger, you are encouraged to use + <seealso marker="inet#getopts/2"><c>inet:getopts/2</c></seealso> + to analyze the behavior of your operating system.</p> </item> <tag><c>{delay_send, Boolean}</c></tag> @@ -856,10 +862,10 @@ fe80::204:acff:fe17:bf38 <c>CAP_SYS_ADMIN</c> according to the documentation for setns(2). However, during testing also <c>CAP_SYS_PTRACE</c> and <c>CAP_DAC_READ_SEARCH</c> has proven to be necessary. - Example:<code> + Example:</p><code> setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp </code> - Note also that the filesystem containing the virtual machine + <p>Note also that the filesystem containing the virtual machine executable (<c>beam.smp</c> in the example above) has to be local, mounted without the <c>nosetuid</c> flag, support extended attributes and that @@ -975,6 +981,11 @@ setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp indicated length are accepted and not considered invalid due to internal buffer limitations.</p> </item> + <tag><c>{line_delimiter, Char}</c>(TCP/IP sockets)</tag> + <item> + <p>Sets the line delimiting character for line oriented protocols + (<c>line</c>). Default value is <c>$\n</c>.</p> + </item> <tag><c>{priority, Priority}</c></tag> <item> <p>Set the protocol-defined priority for all packets to be sent @@ -998,8 +1009,12 @@ setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp </item> <tag><c>{recbuf, Size}</c></tag> <item> - <p>Gives the size of the receive buffer to use for - the socket.</p> + <p>The minimum size of the receive buffer to use for + the socket. You are encouraged to use + <seealso marker="inet#getopts/2"><c>inet:getopts/2</c></seealso>, + to retrieve the actual size set by your operating system. + + </p> </item> <tag><c>{reuseaddr, Boolean}</c></tag> <item> @@ -1028,22 +1043,56 @@ setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp <marker id="option-sndbuf"></marker> </item> + <tag><c>{show_econnreset, Boolean}</c>(TCP/IP sockets)</tag> + <item> + <p>When this option is set to <c>false</c>, as it is by + default, an RST that is received from the TCP peer is treated + as a normal close (as though a FIN was sent). A caller + to <seealso marker="gen_tcp#recv/2">gen_tcp:recv/2</seealso> + will get <c>{error, closed}</c>. In active + mode the controlling process will receive a + <c>{tcp_close, Socket}</c> message, indicating that the + peer has closed the connection.</p> + <p>Setting this option to <c>true</c> will allow you to + distinguish between a connection that was closed normally, + and one which was aborted (intentionally or unintentionally) + by the TCP peer. A call to + <seealso marker="gen_tcp#recv/2">gen_tcp:recv/2</seealso> + will return <c>{error, econnreset}</c>. In + active mode, the controlling process will receive a + <c>{tcp_error, Socket, econnreset}</c> message + before the usual <c>{tcp_closed, Socket}</c>, as is + the case for any other socket error. Calls to + <seealso marker="gen_tcp#send/2">gen_tcp:send/2</seealso> + will also return <c>{error, econnreset}</c> when it + is detected that a TCP peer has sent an RST.</p> + <p>A connected socket returned from + <seealso marker="gen_tcp#accept/1">gen_tcp:accept/1</seealso> + will inherit the <c>show_econnreset</c> setting from the + listening socket.</p> + <marker id="option-show_econnreset"></marker> + </item> + <tag><c>{sndbuf, Size}</c></tag> <item> - <p>Gives the size of the send buffer to use for the socket.</p> + <p>The minimum size of the send buffer to use for the socket. + You are encouraged to use + <seealso marker="inet#getopts/2"><c>inet:getopts/2</c></seealso>, + to retrieve the actual size set by your operating system. + </p> </item> <tag><c>{priority, Integer}</c></tag> <item> - <p>Sets the SO_PRIORITY socket level option on platforms where - this is implemented. The behaviour and allowed range varies on - different systems. The option is ignored on platforms where the + <p>Sets the SO_PRIORITY socket level option on platforms where + this is implemented. The behaviour and allowed range varies on + different systems. The option is ignored on platforms where the option is not implemented. Use with caution.</p> </item> <tag><c>{tos, Integer}</c></tag> <item> - <p>Sets IP_TOS IP level options on platforms where this is - implemented. The behaviour and allowed range varies on different - systems. The option is ignored on platforms where the option is + <p>Sets IP_TOS IP level options on platforms where this is + implemented. The behaviour and allowed range varies on different + systems. The option is ignored on platforms where the option is not implemented. Use with caution.</p> </item> </taglist> |