aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/inet.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/kernel/doc/src/inet.xml')
-rw-r--r--lib/kernel/doc/src/inet.xml827
1 files changed, 827 insertions, 0 deletions
diff --git a/lib/kernel/doc/src/inet.xml b/lib/kernel/doc/src/inet.xml
new file mode 100644
index 0000000000..cae5fef2f8
--- /dev/null
+++ b/lib/kernel/doc/src/inet.xml
@@ -0,0 +1,827 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1997</year><year>2009</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/.
+
+ 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.
+
+ </legalnotice>
+
+ <title>inet</title>
+ <prepared>[email protected]</prepared>
+ <docno></docno>
+ <date>1998-02-04</date>
+ <rev>A</rev>
+ </header>
+ <module>inet</module>
+ <modulesummary>Access to TCP/IP Protocols</modulesummary>
+ <description>
+ <p>Provides access to TCP/IP protocols.</p>
+ <p>See also <em>ERTS User's Guide, Inet configuration</em> for more
+ information on how to configure an Erlang runtime system for IP
+ communication.</p>
+ <p>Two Kernel configuration parameters affect the behaviour of all
+ sockets opened on an Erlang node:
+ <c>inet_default_connect_options</c> can contain a list of default
+ options used for all sockets returned when doing <c>connect</c>,
+ and <c>inet_default_listen_options</c> can contain a list of
+ default options used when issuing a <c>listen</c> call. When
+ <c>accept</c> is issued, the values of the listensocket options
+ are inherited, why no such application variable is needed for
+ <c>accept</c>.</p>
+ <p>Using the Kernel configuration parameters mentioned above, one
+ can set default options for all TCP sockets on a node. This should
+ be used with care, but options like <c>{delay_send,true}</c>
+ might be specified in this way. An example of starting an Erlang
+ node with all sockets using delayed send could look like this:</p>
+ <pre>
+$ <input>erl -sname test -kernel \\</input>
+<input>inet_default_connect_options '[{delay_send,true}]' \\</input>
+<input>inet_default_listen_options '[{delay_send,true}]'</input></pre>
+ <p>Note that the default option <c>{active, true}</c> currently
+ cannot be changed, for internal reasons.</p>
+ </description>
+
+ <section>
+ <title>DATA TYPES</title>
+ <code type="none">
+#hostent{h_addr_list = [ip_address()] % list of addresses for this host
+ h_addrtype = inet | inet6
+ h_aliases = [hostname()] % list of aliases
+ h_length = int() % length of address in bytes
+ h_name = hostname() % official name for host
+ The record is defined in the Kernel include file "inet.hrl"
+ Add the following directive to the module:
+ -include_lib("kernel/include/inet.hrl").
+
+hostname() = atom() | string()
+
+ip_address() = {N1,N2,N3,N4} % IPv4
+ | {K1,K2,K3,K4,K5,K6,K7,K8} % IPv6
+ Ni = 0..255
+ Ki = 0..65535
+
+posix()
+ an atom which is named from the Posix error codes used in
+ Unix, and in the runtime libraries of most C compilers
+
+socket()
+ see gen_tcp(3), gen_udp(3)</code>
+ <p>Addresses as inputs to functions can be either a string or a
+ tuple. For instance, the IP address 150.236.20.73 can be passed to
+ <c>gethostbyaddr/1</c> either as the string "150.236.20.73"
+ or as the tuple <c>{150, 236, 20, 73}</c>.</p>
+ <p>IPv4 address examples:</p>
+ <code type="none">
+Address ip_address()
+------- ------------
+127.0.0.1 {127,0,0,1}
+192.168.42.2 {192,168,42,2}</code>
+ <p>IPv6 address examples:</p>
+ <code type="none">
+Address ip_address()
+------- ------------
+::1 {0,0,0,0,0,0,0,1}
+::192.168.42.2 {0,0,0,0,0,0,(192 bsl 8) bor 168,(42 bsl 8) bor 2}
+FFFF::192.168.42.2
+ {16#FFFF,0,0,0,0,0,(192 bsl 8) bor 168,(42 bsl 8) bor 2}
+3ffe:b80:1f8d:2:204:acff:fe17:bf38
+ {16#3ffe,16#b80,16#1f8d,16#2,16#204,16#acff,16#fe17,16#bf38}
+fe80::204:acff:fe17:bf38
+ {16#fe80,0,0,0,0,16#204,16#acff,16#fe17,16#bf38}</code>
+ <p>A function that may be useful is <c>inet_parse:address/1</c>:</p>
+ <pre>
+1> <input>inet_parse:address("192.168.42.2").</input>
+{ok,{192,168,42,2}}
+2> <input>inet_parse:address("FFFF::192.168.42.2").</input>
+{ok,{65535,0,0,0,0,0,49320,10754}}</pre>
+ </section>
+ <funcs>
+ <func>
+ <name>close(Socket) -> ok</name>
+ <fsummary>Close a socket of any type</fsummary>
+ <type>
+ <v>Socket = socket()</v>
+ </type>
+ <desc>
+ <p>Closes a socket of any type.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_rc() -> [{Par, Val}]</name>
+ <fsummary>Return a list of IP configuration parameters</fsummary>
+ <type>
+ <v>Par, Val -- see below</v>
+ </type>
+ <desc>
+ <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>
+ </desc>
+ </func>
+ <func>
+ <name>format_error(Posix) -> string()</name>
+ <fsummary>Return a descriptive string for an error reason</fsummary>
+ <type>
+ <v>Posix = posix()</v>
+ </type>
+ <desc>
+ <p>Returns a diagnostic error string. See the section below
+ for possible <c>Posix</c> values and the corresponding
+ strings.</p>
+ </desc>
+ </func>
+ <func>
+ <name>getaddr(Host, Family) -> {ok, Address} | {error, posix()}</name>
+ <fsummary>Return the IP-address for a host</fsummary>
+ <type>
+ <v>Host = ip_address() | string() | atom()</v>
+ <v>Family = inet | inet6</v>
+ <v>Address = ip_address()</v>
+ <v>posix() = term()</v>
+ </type>
+ <desc>
+ <p>Returns the IP-address for <c>Host</c> as a tuple of
+ integers. <c>Host</c> can be an IP-address, a single hostname
+ or a fully qualified hostname.</p>
+ </desc>
+ </func>
+ <func>
+ <name>getaddrs(Host, Family) -> {ok, Addresses} | {error, posix()}</name>
+ <fsummary>Return the IP-addresses for a host</fsummary>
+ <type>
+ <v>Host = ip_address() | string() | atom()</v>
+ <v>Addresses = [ip_address()]</v>
+ <v>Family = inet | inet6</v>
+ </type>
+ <desc>
+ <p>Returns a list of all IP-addresses for <c>Host</c>.
+ <c>Host</c> can be an IP-address, a single hostname or a fully
+ qualified hostname.</p>
+ </desc>
+ </func>
+ <func>
+ <name>gethostbyaddr(Address) -> {ok, Hostent} | {error, posix()}</name>
+ <fsummary>Return a hostent record for the host with the given address</fsummary>
+ <type>
+ <v>Address = string() | ip_address()</v>
+ <v>Hostent = #hostent{}</v>
+ </type>
+ <desc>
+ <p>Returns a <c>hostent</c> record given an address.</p>
+ </desc>
+ </func>
+ <func>
+ <name>gethostbyname(Name) -> {ok, Hostent} | {error, posix()}</name>
+ <fsummary>Return a hostent record for the host with the given name</fsummary>
+ <type>
+ <v>Hostname = hostname()</v>
+ <v>Hostent = #hostent{}</v>
+ </type>
+ <desc>
+ <p>Returns a <c>hostent</c> record given a hostname.</p>
+ </desc>
+ </func>
+ <func>
+ <name>gethostbyname(Name, Family) -> {ok, Hostent} | {error, posix()}</name>
+ <fsummary>Return a hostent record for the host with the given name</fsummary>
+ <type>
+ <v>Hostname = hostname()</v>
+ <v>Family = inet | inet6</v>
+ <v>Hostent = #hostent{}</v>
+ </type>
+ <desc>
+ <p>Returns a <c>hostent</c> record given a hostname, restricted
+ to the given address family.</p>
+ </desc>
+ </func>
+ <func>
+ <name>gethostname() -> {ok, Hostname}</name>
+ <fsummary>Return the local hostname</fsummary>
+ <type>
+ <v>Hostname = string()</v>
+ </type>
+ <desc>
+ <p>Returns the local hostname. Will never fail.</p>
+ </desc>
+ </func>
+ <func>
+ <name>getopts(Socket, Options) -> OptionValues | {error, posix()}</name>
+ <fsummary>Get one or more options for a socket</fsummary>
+ <type>
+ <v>Socket = term()</v>
+ <v>Options = [Opt | RawOptReq]</v>
+ <v>Opt = atom()</v>
+ <v>RawOptReq = {raw, Protocol, OptionNum, ValueSpec}</v>
+ <v>Protocol = int()</v>
+ <v>OptionNum = int()</v>
+ <v>ValueSpec = ValueSize | ValueBin</v>
+ <v>ValueSize = int()</v>
+ <v>ValueBin = binary()</v>
+ <v>OptionValues = [{Opt, Val} | {raw, Protocol, OptionNum, ValueBin}]</v>
+ </type>
+ <desc>
+ <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>OptionValues</c>
+ list does not necessarily correspond to the number of options
+ asked for. If the operating system fails to support an option,
+ it is simply left out in the returned list. An error tuple is only
+ returned when getting options for the socket is impossible
+ (i.e. the socket is closed or the buffer size in a raw request
+ is too large). This behavior is kept for backward
+ compatibility reasons.</p>
+ <p>A <c>RawOptReq</c> can be used to get information about
+ 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>
+ <p>The <c>RawOptReq</c> consists of the tag <c>raw</c> followed
+ 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
+ <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>
+ 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
+ stack.</p>
+ <p>As an example, consider a Linux machine where the
+ <c>TCP_INFO</c> option could be used to collect TCP statistics
+ for a socket. Lets say we're interested in the
+ <c>tcpi_sacked</c> field of the <c>struct tcp_info</c>
+ filled in when asking for <c>TCP_INFO</c>. To
+ be able to access this information, we need to know both the
+ numeric value of the protocol level <c>IPPROTO_TCP</c>, the
+ numeric value of the option <c>TCP_INFO</c>, the size of the
+ <c>struct tcp_info</c> and the size and offset of
+ the specific field. By inspecting the headers or writing a small C
+ program, we found <c>IPPROTO_TCP</c> to be 6,
+ <c>TCP_INFO</c> to be 11, the structure size to be 92 (bytes),
+ the offset of <c>tcpi_sacked</c> to be 28 bytes and the actual
+ 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) ->
+ {ok,[{raw,_,_,Info}]} = inet:getopts(Sock,[{raw,6,11,92}]),
+ <<_:28/binary,TcpiSacked:32/native,_/binary>> = Info,
+ TcpiSacked.]]></code>
+ <p>Preferably, you would check the machine type, the OS
+ and the kernel version prior to executing anything similar to the
+ code above.</p>
+ </desc>
+ </func>
+
+ <func>
+ <name>getstat(Socket)</name>
+ <name>getstat(Socket, Options) -> {ok, OptionValues} | {error, posix()}</name>
+ <fsummary>Get one or more statistic options for a socket</fsummary>
+ <type>
+ <v>Socket = term()</v>
+ <v>Options = [Opt]</v>
+ <v>OptionValues = [{Opt, Val}]</v>
+ <v>&nbsp;Opt, Val -- see below</v>
+ </type>
+ <desc>
+ <p>Gets one or more statistic options for a socket.</p>
+ <p><c>getstat(Socket)</c> is equivalent to
+ <c>getstat(Socket,&nbsp;[recv_avg,&nbsp;recv_cnt,&nbsp;recv_dvi,&nbsp;recv_max,&nbsp;recv_oct,&nbsp;send_avg,&nbsp;send_cnt,&nbsp;send_dvi,&nbsp;send_max,&nbsp;send_oct])</c></p>
+ <p>The following options are available:</p>
+ <taglist>
+ <tag><c>recv_avg</c></tag>
+ <item>
+ <p>Average size of packets in bytes received to the socket.</p>
+ </item>
+ <tag><c>recv_cnt</c></tag>
+ <item>
+ <p>Number of packets received to the socket.</p>
+ </item>
+ <tag><c>recv_dvi</c></tag>
+ <item>
+ <p>Average packet size deviation in bytes received to 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>
+ </item>
+ <tag><c>recv_oct</c></tag>
+ <item>
+ <p>Number of bytes received to the socket.</p>
+ </item>
+
+ <tag><c>send_avg</c></tag>
+ <item>
+ <p>Average size of packets in bytes sent from the socket.</p>
+ </item>
+ <tag><c>send_cnt</c></tag>
+ <item>
+ <p>Number of packets sent from the socket.</p>
+ </item>
+ <tag><c>send_dvi</c></tag>
+ <item>
+ <p>Average packet size deviation in bytes received sent from the socket.</p>
+ </item>
+ <tag><c>send_max</c></tag>
+ <item>
+ <p>The size of the largest packet in bytes sent from the socket.</p>
+ </item>
+ <tag><c>send_oct</c></tag>
+ <item>
+ <p>Number of bytes sent from the socket.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+
+ <func>
+ <name>peername(Socket) -> {ok, {Address, Port}} | {error, posix()}</name>
+ <fsummary>Return the address and port for the other end of a connection</fsummary>
+ <type>
+ <v>Socket = socket()</v>
+ <v>Address = ip_address()</v>
+ <v>Port = int()</v>
+ </type>
+ <desc>
+ <p>Returns the address and port for the other end of a
+ connection.</p>
+ </desc>
+ </func>
+ <func>
+ <name>port(Socket) -> {ok, Port}</name>
+ <fsummary>Return the local port number for a socket</fsummary>
+ <type>
+ <v>Socket = socket()</v>
+ <v>Port = int()</v>
+ </type>
+ <desc>
+ <p>Returns the local port number for a socket.</p>
+ </desc>
+ </func>
+ <func>
+ <name>sockname(Socket) -> {ok, {Address, Port}} | {error, posix()}</name>
+ <fsummary>Return the local address and port number for a socket</fsummary>
+ <type>
+ <v>Socket = socket()</v>
+ <v>Address = ip_address()</v>
+ <v>Port = int()</v>
+ </type>
+ <desc>
+ <p>Returns the local address and port number for a socket.</p>
+ </desc>
+ </func>
+ <func>
+ <name>setopts(Socket, Options) -> ok | {error, posix()}</name>
+ <fsummary>Set one or more options for a socket</fsummary>
+ <type>
+ <v>Socket = term()</v>
+ <v>Options = [{Opt, Val} | {raw, Protocol, Option, ValueBin}]</v>
+ <v>Protocol = int()</v>
+ <v>OptionNum = int()</v>
+ <v>ValueBin = binary()</v>
+ <v>&nbsp;Opt, Val -- see below</v>
+ </type>
+ <desc>
+ <p>Sets one or more options for a socket. The following options
+ are available:</p>
+ <taglist>
+ <tag><c>{active, true | false | once}</c></tag>
+ <item>
+ <p>If the value is <c>true</c>, which is the default,
+ everything received from the socket will be sent as
+ messages to the receiving process. If the value is
+ <c>false</c> (passive mode), the process must explicitly
+ receive incoming data by calling <c>gen_tcp:recv/2,3</c>
+ or <c>gen_udp:recv/2,3</c> (depending on the type of
+ socket).</p>
+ <p>If the value is <c>once</c> (<c>{active, once}</c>),
+ <em>one</em> data message from the socket will be sent
+ to the process. To receive one more message,
+ <c>setopts/2</c> must be called again with the
+ <c>{active, once}</c> option.</p>
+ <p>When using <c>{active, once}</c>, the socket changes
+ behaviour automatically when data is received. This can
+ sometimes be confusing in combination with connection
+ oriented sockets (i.e. <c>gen_tcp</c>) as a socket with
+ <c>{active, false}</c> behaviour reports closing
+ differently than a socket with <c>{active, true}</c>
+ behaviour. To make programming easier, a socket where
+ the peer closed and this was detected while in
+ <c>{active, false}</c> mode, will still generate the
+ message
+ <c>{tcp_closed,Socket}</c> when set to <c>{active, once}</c> or <c>{active, true}</c> mode. It is therefore
+ safe to assume that the message
+ <c>{tcp_closed,Socket}</c>, possibly followed by socket
+ port termination (depending on the <c>exit_on_close</c>
+ option) will eventually appear when a socket changes
+ back and forth between <c>{active, true}</c> and
+ <c>{active, false}</c> mode. However,
+ <em>when</em> peer closing is detected is all up to the
+ underlying TCP/IP stack and protocol.</p>
+ <p>Note that <c>{active,true}</c> mode provides no flow
+ control; a fast sender could easily overflow the
+ receiver with incoming messages. Use active mode only if
+ your high-level protocol provides its own flow control
+ (for instance, acknowledging received messages) or the
+ amount of data exchanged is small. <c>{active,false}</c>
+ mode or use of the <c>{active, once}</c> mode provides
+ 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>
+ </item>
+ <tag><c>{delay_send, Boolean}</c></tag>
+ <item>
+ <p>Normally, when an Erlang process sends to a socket,
+ the driver will try to immediately send the data. If that
+ fails, the driver will use any means available to queue
+ up the message to be sent whenever the operating system
+ says it can handle it. Setting <c>{delay_send, true}</c>
+ will make <em>all</em> messages queue up. This makes
+ the messages actually sent onto the network be larger but
+ fewer. The option actually affects the scheduling of send
+ requests versus Erlang processes instead of changing any
+ real property of the socket. Needless to say it is an
+ implementation specific option. Default is <c>false</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>
+ <p>The only reason to set it to <c>false</c> is if you want
+ to continue sending data to the socket after a close has
+ been detected, for instance if the peer has used
+ <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>
+ option was specified when the socket was created. If
+ the <c>header</c> option is specified, the first
+ <c>Size</c> number bytes of data received from the socket
+ will be elements of a list, and the rest of the data will
+ be a binary given as the tail of the same list. If for
+ example <c>Size == 2</c>, the data received will match
+ <c>[Byte1,Byte2|Binary]</c>.</p>
+ </item>
+ <tag><c>{keepalive, Boolean}</c>(TCP/IP sockets)</tag>
+ <item>
+ <p>Enables/disables periodic transmission on a connected
+ socket, when no other data is being exchanged. If
+ 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>
+ </item>
+ <tag><c>{nodelay, Boolean}</c>(TCP/IP sockets)</tag>
+ <item>
+ <p>If <c>Boolean == true</c>, the <c>TCP_NODELAY</c> option
+ is turned on for the socket, which means that even small
+ amounts of data will be sent immediately.</p>
+ </item>
+ <tag><c>{packet, PacketType}</c>(TCP/IP sockets)</tag>
+ <item>
+ <p>Defines the type of packets to use for a socket.
+ The following values are valid:</p>
+ <taglist>
+ <tag><c>raw | 0</c></tag>
+ <item>
+ <p>No packaging is done.</p>
+ </item>
+ <tag><c>1 | 2 | 4</c></tag>
+ <item>
+ <p>Packets consist of a header specifying the number of
+ bytes in the packet, followed by that number of bytes.
+ The length of header can be one, two, or four bytes;
+ containing an unsigned integer in big-endian byte order.
+ Each send operation will generate the header, and the header
+ will be stripped off on each receive operation.</p>
+ <p>In current implementation the 4-byte header is limited to 2Gb.</p>
+ </item>
+ <tag><c>asn1 | cdr | sunrm | fcgi | tpkt | line</c></tag>
+ <item>
+ <p>These packet types only have effect on receiving.
+ When sending a packet, it is the responsibility of
+ the application to supply a correct header. On
+ receiving, however, there will be one message sent to
+ the controlling process for each complete packet
+ received, and, similarly, each call to
+ <c>gen_tcp:recv/2,3</c> returns one complete packet.
+ The header is <em>not</em> stripped off.</p>
+ <p>The meanings of the packet types are as follows:
+ <br></br>
+<c>asn1</c> - ASN.1 BER,
+ <br></br>
+<c>sunrm</c> - Sun's RPC encoding,
+ <br></br>
+<c>cdr</c> - CORBA (GIOP 1.1),
+ <br></br>
+<c>fcgi</c> - Fast CGI,
+ <br></br>
+<c>tpkt</c> - TPKT format [RFC1006],
+ <br></br>
+<c>line</c> - Line mode, a packet is a line
+ terminated with newline, lines longer than
+ the receive buffer are truncated.</p>
+ </item>
+ <tag><c>http | http_bin</c></tag>
+ <item>
+ <p>The Hypertext Transfer Protocol. The packets
+ are returned with the format according to <c>HttpPacket</c>
+ described in <seealso marker="erts:erlang#decode_packet/3">
+ erlang:decode_packet/3</seealso>. A socket in passive
+ mode will return <c>{ok, HttpPacket}</c> from <c>gen_tcp:recv</c>
+ while an active socket will send messages like <c>{http,
+ Socket, HttpPacket}</c>.</p>
+ <p>Note that the packet type <c>httph</c> is not
+ needed when reading from a socket.</p>
+ </item>
+ </taglist>
+ </item>
+ <tag><c>{packet_size, Integer}</c>(TCP/IP sockets)</tag>
+ <item>
+ <p>Sets the max allowed length of the packet body. If
+ the packet header indicates that the length of the packet
+ is longer than the max allowed length, the packet is
+ considered invalid. The same happens if the packet header
+ is too big for the socket receive buffer.</p>
+ </item>
+ <tag><c>{read_packets, Integer}</c>(UDP sockets)</tag>
+ <item>
+ <p>Sets the max number of UDP packets to read without
+ intervention from the socket when data is available.
+ When this many packets have been read and delivered
+ to the destination process, new packets are not read
+ until a new notification of available data has arrived.
+ The default is 5, and if this parameter is set too
+ high the system can become unresponsive due to
+ UDP packet flooding.</p>
+ </item>
+ <tag><c>{recbuf, Integer}</c></tag>
+ <item>
+ <p>Gives the size of the receive buffer to use for
+ the socket.</p>
+ </item>
+ <tag><c>{reuseaddr, Boolean}</c></tag>
+ <item>
+ <p>Allows or disallows local reuse of port numbers. By
+ default, reuse is disallowed.</p>
+ </item>
+ <tag><c>{send_timeout, Integer}</c></tag>
+ <item>
+ <p>Only allowed for connection oriented sockets.</p>
+ <p>Specifies a longest time to wait for a send operation to
+ be accepted by the underlying TCP stack. When the limit is
+ exceeded, the send operation will return
+ <c>{error,timeout}</c>. How much of a packet that actually
+ got sent is unknown, why the socket should be closed
+ whenever a timeout has occurred (see <c>send_timeout_close</c>).
+ Default is <c>infinity</c>.</p>
+ </item>
+ <tag><c>{send_timeout_close, Boolean}</c></tag>
+ <item>
+ <p>Only allowed for connection oriented sockets.</p>
+ <p>Used together with <c>send_timeout</c> to specify whether
+ the socket will be automatically closed when the send operation
+ 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>
+ </item>
+
+ <tag><c>{sndbuf, Integer}</c></tag>
+ <item>
+ <p>Gives the size of the send buffer to use for the socket.</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
+ 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
+ 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
+ <c>raw</c>, followed by the protocol level, the option number
+ and the actual option value specified as a binary. This
+ corresponds to the second, third and fourth argument to the
+ <c>setsockopt</c> call in the C socket API. The option value
+ needs to be coded in the native endianess of the platform and,
+ if a structure is required, needs to follow the struct
+ alignment conventions on the specific platform.</p>
+ <p>Using raw socket options require detailed knowledge about
+ the current operating system and TCP stack.</p>
+ <p>As an example of the usage of raw options, consider a Linux
+ system where you want to set the <c>TCP_LINGER2</c> option on
+ the <c>IPPROTO_TCP</c> protocol level in the stack. You know
+ that on this particular system it defaults to 60 (seconds),
+ but you would like to lower it to 30 for a particular
+ socket. The <c>TCP_LINGER2</c> option is not explicitly
+ supported by inet, but you know that the protocol level
+ translates to the number 6, the option number to the number 8
+ and the value is to be given as a 32 bit integer. You can use
+ this line of code to set the option for the socket named
+ <c>Sock</c>:</p>
+ <code type="none"><![CDATA[
+ inet:setopts(Sock,[{raw,6,8,<<30:32/native>>}]),]]></code>
+ <p>As many options are silently discarded by the stack if they
+ are given out of range, it could be a good idea to check that
+ a raw option really got accepted. This code places the value
+ in the variable TcpLinger2:</p>
+ <code type="none"><![CDATA[
+ {ok,[{raw,6,8,<<TcpLinger2:32/native>>}]}=inet:getopts(Sock,[{raw,6,8,4}]),]]></code>
+ <p>Code such as the examples above is inherently non portable,
+ even different versions of the same OS on the same platform
+ may respond differently to this kind of option
+ manipulation. Use with care.</p>
+ <p>Note that the default options for TCP/IP sockets can be
+ changed with the Kernel configuration parameters mentioned in
+ the beginning of this document.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <marker id="error_codes"></marker>
+ <title>POSIX Error Codes</title>
+ <list type="bulleted">
+ <item><c>e2big</c> - argument list too long</item>
+ <item><c>eacces</c> - permission denied</item>
+ <item><c>eaddrinuse</c> - address already in use</item>
+ <item><c>eaddrnotavail</c> - cannot assign requested address</item>
+ <item><c>eadv</c> - advertise error</item>
+ <item><c>eafnosupport</c> - address family not supported by
+ protocol family</item>
+ <item><c>eagain</c> - resource temporarily unavailable</item>
+ <item><c>ealign</c> - EALIGN</item>
+ <item><c>ealready</c> - operation already in progress</item>
+ <item><c>ebade</c> - bad exchange descriptor</item>
+ <item><c>ebadf</c> - bad file number</item>
+ <item><c>ebadfd</c> - file descriptor in bad state</item>
+ <item><c>ebadmsg</c> - not a data message</item>
+ <item><c>ebadr</c> - bad request descriptor</item>
+ <item><c>ebadrpc</c> - RPC structure is bad</item>
+ <item><c>ebadrqc</c> - bad request code</item>
+ <item><c>ebadslt</c> - invalid slot</item>
+ <item><c>ebfont</c> - bad font file format</item>
+ <item><c>ebusy</c> - file busy</item>
+ <item><c>echild</c> - no children</item>
+ <item><c>echrng</c> - channel number out of range</item>
+ <item><c>ecomm</c> - communication error on send</item>
+ <item><c>econnaborted</c> - software caused connection abort</item>
+ <item><c>econnrefused</c> - connection refused</item>
+ <item><c>econnreset</c> - connection reset by peer</item>
+ <item><c>edeadlk</c> - resource deadlock avoided</item>
+ <item><c>edeadlock</c> - resource deadlock avoided</item>
+ <item><c>edestaddrreq</c> - destination address required</item>
+ <item><c>edirty</c> - mounting a dirty fs w/o force</item>
+ <item><c>edom</c> - math argument out of range</item>
+ <item><c>edotdot</c> - cross mount point</item>
+ <item><c>edquot</c> - disk quota exceeded</item>
+ <item><c>eduppkg</c> - duplicate package name</item>
+ <item><c>eexist</c> - file already exists</item>
+ <item><c>efault</c> - bad address in system call argument</item>
+ <item><c>efbig</c> - file too large</item>
+ <item><c>ehostdown</c> - host is down</item>
+ <item><c>ehostunreach</c> - host is unreachable</item>
+ <item><c>eidrm</c> - identifier removed</item>
+ <item><c>einit</c> - initialization error</item>
+ <item><c>einprogress</c> - operation now in progress</item>
+ <item><c>eintr</c> - interrupted system call</item>
+ <item><c>einval</c> - invalid argument</item>
+ <item><c>eio</c> - I/O error</item>
+ <item><c>eisconn</c> - socket is already connected</item>
+ <item><c>eisdir</c> - illegal operation on a directory</item>
+ <item><c>eisnam</c> - is a named file</item>
+ <item><c>el2hlt</c> - level 2 halted</item>
+ <item><c>el2nsync</c> - level 2 not synchronized</item>
+ <item><c>el3hlt</c> - level 3 halted</item>
+ <item><c>el3rst</c> - level 3 reset</item>
+ <item><c>elbin</c> - ELBIN</item>
+ <item><c>elibacc</c> - cannot access a needed shared library</item>
+ <item><c>elibbad</c> - accessing a corrupted shared library</item>
+ <item><c>elibexec</c> - cannot exec a shared library directly</item>
+ <item><c>elibmax</c> - attempting to link in more shared
+ libraries than system limit</item>
+ <item><c>elibscn</c> - .lib section in a.out corrupted</item>
+ <item><c>elnrng</c> - link number out of range</item>
+ <item><c>eloop</c> - too many levels of symbolic links</item>
+ <item><c>emfile</c> - too many open files</item>
+ <item><c>emlink</c> - too many links</item>
+ <item><c>emsgsize</c> - message too long</item>
+ <item><c>emultihop</c> - multihop attempted</item>
+ <item><c>enametoolong</c> - file name too long</item>
+ <item><c>enavail</c> - not available</item>
+ <item><c>enet</c> - ENET</item>
+ <item><c>enetdown</c> - network is down</item>
+ <item><c>enetreset</c> - network dropped connection on reset</item>
+ <item><c>enetunreach</c> - network is unreachable</item>
+ <item><c>enfile</c> - file table overflow</item>
+ <item><c>enoano</c> - anode table overflow</item>
+ <item><c>enobufs</c> - no buffer space available</item>
+ <item><c>enocsi</c> - no CSI structure available</item>
+ <item><c>enodata</c> - no data available</item>
+ <item><c>enodev</c> - no such device</item>
+ <item><c>enoent</c> - no such file or directory</item>
+ <item><c>enoexec</c> - exec format error</item>
+ <item><c>enolck</c> - no locks available</item>
+ <item><c>enolink</c> - link has be severed</item>
+ <item><c>enomem</c> - not enough memory</item>
+ <item><c>enomsg</c> - no message of desired type</item>
+ <item><c>enonet</c> - machine is not on the network</item>
+ <item><c>enopkg</c> - package not installed</item>
+ <item><c>enoprotoopt</c> - bad protocol option</item>
+ <item><c>enospc</c> - no space left on device</item>
+ <item><c>enosr</c> - out of stream resources or not a stream
+ device</item>
+ <item><c>enosym</c> - unresolved symbol name</item>
+ <item><c>enosys</c> - function not implemented</item>
+ <item><c>enotblk</c> - block device required</item>
+ <item><c>enotconn</c> - socket is not connected</item>
+ <item><c>enotdir</c> - not a directory</item>
+ <item><c>enotempty</c> - directory not empty</item>
+ <item><c>enotnam</c> - not a named file</item>
+ <item><c>enotsock</c> - socket operation on non-socket</item>
+ <item><c>enotsup</c> - operation not supported</item>
+ <item><c>enotty</c> - inappropriate device for ioctl</item>
+ <item><c>enotuniq</c> - name not unique on network</item>
+ <item><c>enxio</c> - no such device or address</item>
+ <item><c>eopnotsupp</c> - operation not supported on socket</item>
+ <item><c>eperm</c> - not owner</item>
+ <item><c>epfnosupport</c> - protocol family not supported</item>
+ <item><c>epipe</c> - broken pipe</item>
+ <item><c>eproclim</c> - too many processes</item>
+ <item><c>eprocunavail</c> - bad procedure for program</item>
+ <item><c>eprogmismatch</c> - program version wrong</item>
+ <item><c>eprogunavail</c> - RPC program not available</item>
+ <item><c>eproto</c> - protocol error</item>
+ <item><c>eprotonosupport</c> - protocol not supported</item>
+ <item><c>eprototype</c> - protocol wrong type for socket</item>
+ <item><c>erange</c> - math result unrepresentable</item>
+ <item><c>erefused</c> - EREFUSED</item>
+ <item><c>eremchg</c> - remote address changed</item>
+ <item><c>eremdev</c> - remote device</item>
+ <item><c>eremote</c> - pathname hit remote file system</item>
+ <item><c>eremoteio</c> - remote i/o error</item>
+ <item><c>eremoterelease</c> - EREMOTERELEASE</item>
+ <item><c>erofs</c> - read-only file system</item>
+ <item><c>erpcmismatch</c> - RPC version is wrong</item>
+ <item><c>erremote</c> - object is remote</item>
+ <item><c>eshutdown</c> - cannot send after socket shutdown</item>
+ <item><c>esocktnosupport</c> - socket type not supported</item>
+ <item><c>espipe</c> - invalid seek</item>
+ <item><c>esrch</c> - no such process</item>
+ <item><c>esrmnt</c> - srmount error</item>
+ <item><c>estale</c> - stale remote file handle</item>
+ <item><c>esuccess</c> - Error 0</item>
+ <item><c>etime</c> - timer expired</item>
+ <item><c>etimedout</c> - connection timed out</item>
+ <item><c>etoomanyrefs</c> - too many references</item>
+ <item><c>etxtbsy</c> - text file or pseudo-device busy</item>
+ <item><c>euclean</c> - structure needs cleaning</item>
+ <item><c>eunatch</c> - protocol driver not attached</item>
+ <item><c>eusers</c> - too many users</item>
+ <item><c>eversion</c> - version mismatch</item>
+ <item><c>ewouldblock</c> - operation would block</item>
+ <item><c>exdev</c> - cross-domain link</item>
+ <item><c>exfull</c> - message tables full</item>
+ <item><c>nxdomain</c> - the hostname or domain name could not be
+ found</item>
+ </list>
+ </section>
+</erlref>
+