.TH inet 3erl "kernel 6.2" "Ericsson AB" "Erlang Module Definition"
.SH NAME
inet \- Access to TCP/IP protocols.
.SH DESCRIPTION
.LP
This module provides access to TCP/IP protocols\&.
.LP
See also \fBERTS User\&'s Guide: Inet Configuration\fR\& for more information about how to configure an Erlang runtime system for IP communication\&.
.LP
The following two Kernel configuration parameters affect the behavior of all sockets opened on an Erlang node:
.RS 2
.TP 2
*
\fIinet_default_connect_options\fR\& can contain a list of default options used for all sockets returned when doing \fIconnect\fR\&\&.
.LP
.TP 2
*
\fIinet_default_listen_options\fR\& can contain a list of default options used when issuing a \fIlisten\fR\& call\&.
.LP
.RE

.LP
When \fIaccept\fR\& is issued, the values of the listening socket options are inherited\&. No such application variable is therefore needed for \fIaccept\fR\&\&.
.LP
Using the Kernel configuration parameters above, one can set default options for all TCP sockets on a node, but use this with care\&. Options such as \fI{delay_send,true}\fR\& can be specified in this way\&. The following is an example of starting an Erlang node with all sockets using delayed send:
.LP
.nf

$ erl -sname test -kernel \\
inet_default_connect_options \&'[{delay_send,true}]\&' \\
inet_default_listen_options \&'[{delay_send,true}]\&'
.fi
.LP
Notice that default option \fI{active, true}\fR\& cannot be changed, for internal reasons\&.
.LP
Addresses as inputs to functions can be either a string or a tuple\&. For example, the IP address 150\&.236\&.20\&.73 can be passed to \fIgethostbyaddr/1\fR\&, either as string \fI"150\&.236\&.20\&.73"\fR\& or as tuple \fI{150, 236, 20, 73}\fR\&\&.
.LP
\fIIPv4 address examples:\fR\&
.LP
.nf

Address          ip_address()
-------          ------------
127.0.0.1        {127,0,0,1}
192.168.42.2     {192,168,42,2}
.fi
.LP
\fIIPv6 address examples:\fR\&
.LP
.nf

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
                {0,0,0,0,0,16#FFFF,(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}
.fi
.LP
Function \fB\fIparse_address/1\fR\&\fR\& can be useful:
.LP
.nf

1> inet:parse_address("192\&.168\&.42\&.2")\&.
{ok,{192,168,42,2}}
2> inet:parse_address("::FFFF:192\&.168\&.42\&.2")\&.
{ok,{0,0,0,0,0,65535,49320,10754}}
.fi
.SH DATA TYPES
.nf

\fBhostent()\fR\& = 
.br
    #hostent{h_name = \fBinet:hostname()\fR\&,
.br
             h_aliases = [\fBinet:hostname()\fR\&],
.br
             h_addrtype = inet | inet6,
.br
             h_length = integer() >= 0,
.br
             h_addr_list = [\fBinet:ip_address()\fR\&]}
.br
.fi
.RS
.LP
The record is defined in the Kernel include file \fI"inet\&.hrl"\fR\&\&.
.LP
Add the following directive to the module:
.LP
.nf

-include_lib("kernel/include/inet.hrl").
.fi
.RE

.nf

\fBhostname()\fR\& = atom() | string()
.br
.fi
.nf

\fBip_address()\fR\& = \fBip4_address()\fR\& | \fBip6_address()\fR\&
.br
.fi
.nf

\fBip4_address()\fR\& = {0\&.\&.255, 0\&.\&.255, 0\&.\&.255, 0\&.\&.255}
.br
.fi
.nf

\fBip6_address()\fR\& = 
.br
    {0\&.\&.65535,
.br
     0\&.\&.65535,
.br
     0\&.\&.65535,
.br
     0\&.\&.65535,
.br
     0\&.\&.65535,
.br
     0\&.\&.65535,
.br
     0\&.\&.65535,
.br
     0\&.\&.65535}
.br
.fi
.nf

\fBport_number()\fR\& = 0\&.\&.65535
.br
.fi
.nf

\fBlocal_address()\fR\& = {local, File :: binary() | string()}
.br
.fi
.RS
.LP
This address family only works on Unix-like systems\&.
.LP
\fIFile\fR\& is normally a file pathname in a local filesystem\&. It is limited in length by the operating system, traditionally to 108 bytes\&.
.LP
A \fIbinary()\fR\& is passed as is to the operating system, but a \fIstring()\fR\& is encoded according to the \fB system filename encoding mode\&. \fR\& 
.LP
Other addresses are possible, for example Linux implements "Abstract Addresses"\&. See the documentation for Unix Domain Sockets on your system, normally \fIunix\fR\& in manual section 7\&.
.LP
In most API functions where you can use this address family the port number must be \fI0\fR\&\&.
.RE

.nf

\fBsocket_address()\fR\& = 
.br
    \fBip_address()\fR\& | any | loopback | \fBlocal_address()\fR\&
.br
.fi
.nf

\fBsocket_getopt()\fR\& = 
.br
    \fBgen_sctp:option_name()\fR\& |
.br
    \fBgen_tcp:option_name()\fR\& |
.br
    \fBgen_udp:option_name()\fR\&
.br
.fi
.nf

\fBsocket_setopt()\fR\& = 
.br
    \fBgen_sctp:option()\fR\& | \fBgen_tcp:option()\fR\& | \fBgen_udp:option()\fR\&
.br
.fi
.nf

\fBreturned_non_ip_address()\fR\& = 
.br
    {local, binary()} | {unspec, <<>>} | {undefined, any()}
.br
.fi
.RS
.LP
Addresses besides \fB\fIip_address()\fR\&\fR\& ones that are returned from socket API functions\&. See in particular \fB\fIlocal_address()\fR\&\&. \fR\& The \fIunspec\fR\& family corresponds to AF_UNSPEC and can occur if the other side has no socket address\&. The \fIundefined\fR\& family can only occur in the unlikely event of an address family that the VM does not recognize\&.
.RE

.nf

\fBancillary_data()\fR\& = 
.br
    [{tos, byte()} | {tclass, byte()} | {ttl, byte()}]
.br
.fi
.RS
.LP
Ancillary data received with the data packet or read with the socket option \fB\fIpktoptions\fR\&\fR\& from a TCP socket\&.
.LP
The value(s) correspond to the currently active socket \fBoptions\fR\& \fB\fIrecvtos\fR\&\fR\&, \fB\fIrecvtclass\fR\&\fR\& and \fB\fIrecvttl\fR\&\fR\&\&.
.RE

.nf

\fBgetifaddrs_ifopts()\fR\& = 
.br
    [Ifopt ::
.br
         {flags,
.br
          Flags ::
.br
              [up |
.br
               broadcast |
.br
               loopback |
.br
               pointtopoint |
.br
               running |
.br
               multicast]} |
.br
         {addr, Addr :: \fBip_address()\fR\&} |
.br
         {netmask, Netmask :: \fBip_address()\fR\&} |
.br
         {broadaddr, Broadaddr :: \fBip_address()\fR\&} |
.br
         {dstaddr, Dstaddr :: \fBip_address()\fR\&} |
.br
         {hwaddr, Hwaddr :: [byte()]}]
.br
.fi
.RS
.LP
Interface address description list returned from \fB\fIgetifaddrs/0,1\fR\&\fR\& for a named interface, translated from the returned data of the POSIX API function \fIgetaddrinfo()\fR\&\&.
.LP
\fIHwaddr\fR\& is hardware dependent, for example, on Ethernet interfaces it is the 6-byte Ethernet address (MAC address (EUI-48 address))\&.
.LP
The tuples \fI{addr,Addr}\fR\&, \fI{netmask,Netmask}\fR\&, and possibly \fI{broadaddr,Broadaddr}\fR\& or \fI{dstaddr,Dstaddr}\fR\& are repeated in the list if the interface has got multiple addresses\&. An interface may have multiple \fI{flag,_}\fR\& tuples for example if it has different flags for different address families\&. Multiple \fI{hwaddr,Hwaddr}\fR\& tuples is hard to say anything definite about, though\&. The tuple \fI{flag,Flags}\fR\& is mandatory, all others are optional\&.
.LP
Do not rely too much on the order of \fIFlags\fR\& atoms or the \fIIfopt\fR\& tuples\&. There are however some rules:
.RS 2
.TP 2
*
A \fI{flag,_}\fR\& tuple applies to all other tuples that follow\&.
.LP
.TP 2
*
Immediately after \fI{addr,_}\fR\& follows \fI{netmask,_}\fR\&\&.
.LP
.TP 2
*
Immediately thereafter may \fI{broadaddr,_}\fR\& follow if \fIbroadcast\fR\& is member of \fIFlags\fR\&, or \fI{dstaddr,_}\fR\& if \fIpointtopoint\fR\& is member of \fIFlags\fR\&\&. Both \fI{dstaddr,_}\fR\& and \fI{broadaddr,_}\fR\& does not occur for the same \fI{addr,_}\fR\&\&.
.LP
.TP 2
*
Any \fI{netmask,_}\fR\&, \fI{broadaddr,_}\fR\&, or \fI{dstaddr,_}\fR\& tuples that follow an \fI{addr,Addr}\fR\& tuple concerns the address \fIAddr\fR\&\&.
.LP
.RE

.LP
The tuple \fI{hwaddr,_}\fR\& is not returned on Solaris, as the hardware address historically belongs to the link layer and it is not returned by the Solaris API function \fIgetaddrinfo()\fR\&\&.
.LP

.RS -4
.B
Warning:
.RE
On Windows, the data is fetched from different OS API functions, so the \fINetmask\fR\& and \fIBroadaddr\fR\& values may be calculated, just as some \fIFlags\fR\& values\&.

.RE

.nf

\fBposix()\fR\& = 
.br
    eaddrinuse |
.br
    eaddrnotavail |
.br
    eafnosupport |
.br
    ealready |
.br
    econnaborted |
.br
    econnrefused |
.br
    econnreset |
.br
    edestaddrreq |
.br
    ehostdown |
.br
    ehostunreach |
.br
    einprogress |
.br
    eisconn |
.br
    emsgsize |
.br
    enetdown |
.br
    enetunreach |
.br
    enopkg |
.br
    enoprotoopt |
.br
    enotconn |
.br
    enotty |
.br
    enotsock |
.br
    eproto |
.br
    eprotonosupport |
.br
    eprototype |
.br
    esocktnosupport |
.br
    etimedout |
.br
    ewouldblock |
.br
    exbadport |
.br
    exbadseq |
.br
    \fBfile:posix()\fR\&
.br
.fi
.RS
.LP
An atom that is named from the POSIX error codes used in Unix, and in the runtime libraries of most C compilers\&. See section \fBPOSIX Error Codes\fR\&\&.
.RE

.nf

.B
socket()
.br
.fi
.RS
.LP
See \fB\fIgen_tcp:type-socket\fR\&\fR\& and \fB\fIgen_udp:type-socket\fR\&\fR\&\&.
.RE

.nf

\fBaddress_family()\fR\& = inet | inet6 | local
.br
.fi
.nf

\fBsocket_protocol()\fR\& = tcp | udp | sctp
.br
.fi
.SH EXPORTS
.LP
.nf

.B
close(Socket) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Socket = \fBsocket()\fR\&
.br
.RE
.RE
.RS
.LP
Closes a socket of any type\&.
.RE

.LP
.nf

.B
format_error(Reason) -> string()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Reason = \fBposix()\fR\& | system_limit
.br
.RE
.RE
.RS
.LP
Returns a diagnostic error string\&. For possible POSIX values and corresponding strings, see section \fBPOSIX Error Codes\fR\&\&.
.RE

.LP
.nf

.B
get_rc() ->
.B
          [{Par :: atom(), Val :: any()} |
.B
           {Par :: atom(), Val1 :: any(), Val2 :: any()}]
.br
.fi
.br
.RS
.LP
Returns the state of the \fIInet\fR\& configuration database in form of a list of recorded configuration parameters\&. For more information, see \fBERTS User\&'s Guide: Inet Configuration\fR\&\&.
.LP
Only actual parameters with other than default values are returned, for example not directives that specify other sources for configuration parameters nor directives that clear parameters\&.
.RE

.LP
.nf

.B
getaddr(Host, Family) -> {ok, Address} | {error, posix()}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Host = \fBip_address()\fR\& | \fBhostname()\fR\&
.br
Family = \fBaddress_family()\fR\&
.br
Address = \fBip_address()\fR\&
.br
.RE
.RE
.RS
.LP
Returns the IP address for \fIHost\fR\& as a tuple of integers\&. \fIHost\fR\& can be an IP address, a single hostname, or a fully qualified hostname\&.
.RE

.LP
.nf

.B
getaddrs(Host, Family) -> {ok, Addresses} | {error, posix()}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Host = \fBip_address()\fR\& | \fBhostname()\fR\&
.br
Family = \fBaddress_family()\fR\&
.br
Addresses = [\fBip_address()\fR\&]
.br
.RE
.RE
.RS
.LP
Returns a list of all IP addresses for \fIHost\fR\&\&. \fIHost\fR\& can be an IP address, a single hostname, or a fully qualified hostname\&.
.RE

.LP
.nf

.B
gethostbyaddr(Address) -> {ok, Hostent} | {error, posix()}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Address = string() | \fBip_address()\fR\&
.br
Hostent = \fBhostent()\fR\&
.br
.RE
.RE
.RS
.LP
Returns a \fIhostent\fR\& record for the host with the specified address\&.
.RE

.LP
.nf

.B
gethostbyname(Hostname) -> {ok, Hostent} | {error, posix()}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Hostname = \fBhostname()\fR\&
.br
Hostent = \fBhostent()\fR\&
.br
.RE
.RE
.RS
.LP
Returns a \fIhostent\fR\& record for the host with the specified hostname\&.
.LP
If resolver option \fIinet6\fR\& is \fItrue\fR\&, an IPv6 address is looked up\&.
.RE

.LP
.nf

.B
gethostbyname(Hostname, Family) ->
.B
                 {ok, Hostent} | {error, posix()}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Hostname = \fBhostname()\fR\&
.br
Family = \fBaddress_family()\fR\&
.br
Hostent = \fBhostent()\fR\&
.br
.RE
.RE
.RS
.LP
Returns a \fIhostent\fR\& record for the host with the specified name, restricted to the specified address family\&.
.RE

.LP
.nf

.B
gethostname() -> {ok, Hostname}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Hostname = string()
.br
.RE
.RE
.RS
.LP
Returns the local hostname\&. Never fails\&.
.RE

.LP
.nf

.B
getifaddrs() ->
.B
              {ok,
.B
               [{Ifname :: string(),
.B
                 Ifopts :: getifaddrs_ifopts()}]} |
.B
              {error, posix()}
.br
.fi
.br
.RS
.LP
Returns a list of 2-tuples containing interface names and the interfaces\&' addresses\&. \fIIfname\fR\& is a Unicode string and \fIIfopts\fR\& is a list of interface address description tuples\&.
.LP
The interface address description tuples are documented under the type of the \fB\fIIfopts\fR\&\fR\& value\&.
.RE

.LP
.B
getifaddrs(Opts) -> {ok, [{Ifname, Ifopts}]} | {error, Posix} 
.br
.RS
.LP
Types:

.RS 3
 Opts = [{netns, Namespace}] 
.br
 Namespace = \fB file:filename_all() \fR\&
.br
Ifname = string()
.br
 Ifopts = \fB getifaddrs_ifopts() \fR\&
.br
Posix = \fBposix()\fR\&
.br
.RE
.RE
.RS
.LP
The same as \fB\fIgetifaddrs/0\fR\&\fR\& but the \fIOption\fR\& \fI{netns, Namespace}\fR\& sets a network namespace for the OS call, on platforms that supports that feature\&.
.LP
See the socket option \fB\fI{netns, Namespace}\fR\&\fR\& under \fB\fIsetopts/2\fR\&\fR\&\&.
.RE

.LP
.nf

.B
getopts(Socket, Options) -> {ok, OptionValues} | {error, posix()}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Socket = \fBsocket()\fR\&
.br
Options = [\fBsocket_getopt()\fR\&]
.br
OptionValues = [\fBsocket_setopt()\fR\& | \fBgen_tcp:pktoptions_value()\fR\&]
.br
.RE
.RE
.RS
.LP
Gets one or more options for a socket\&. For a list of available options, see \fB\fIsetopts/2\fR\&\fR\&\&. See also the description for the type \fB\fIgen_tcp:pktoptions_value()\fR\&\fR\&\&.
.LP
The number of elements in the returned \fIOptionValues\fR\& list does not necessarily correspond to the number of options asked for\&. If the operating system fails to support an option, it is left out in the returned list\&. An error tuple is returned only when getting options for the socket is impossible (that is, the socket is closed or the buffer size in a raw request is too large)\&. This behavior is kept for backward compatibility reasons\&.
.LP
A raw option request \fIRawOptReq = {raw, Protocol, OptionNum, ValueSpec}\fR\& 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 a particular platform\&.
.LP
\fIRawOptReq\fR\& consists of tag \fIraw\fR\& 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 is to be used when the underlying \fIgetsockopt\fR\& requires \fIinput\fR\& in the argument field\&. In this case, the binary size is to correspond to the required buffer size of the return value\&. The supplied values in a \fIRawOptReq\fR\& correspond to the second, third, and fourth/fifth parameters to the \fIgetsockopt\fR\& call in the C socket API\&. The value stored in the buffer is returned as a binary \fIValueBin\fR\&, where all values are coded in the native endianess\&.
.LP
Asking for and inspecting raw socket options require low-level information about the current operating system and TCP stack\&.
.LP
\fIExample:\fR\&
.LP
Consider a Linux machine where option \fITCP_INFO\fR\& can be used to collect TCP statistics for a socket\&. Assume you are interested in field \fItcpi_sacked\fR\& of \fIstruct tcp_info\fR\& filled in when asking for \fITCP_INFO\fR\&\&. To be able to access this information, you need to know the following:
.RS 2
.TP 2
*
The numeric value of protocol level \fIIPPROTO_TCP\fR\&
.LP
.TP 2
*
The numeric value of option \fITCP_INFO\fR\&
.LP
.TP 2
*
The size of \fIstruct tcp_info\fR\&
.LP
.TP 2
*
The size and offset of the specific field
.LP
.RE

.LP
By inspecting the headers or writing a small C program, it is found that \fIIPPROTO_TCP\fR\& is 6, \fITCP_INFO\fR\& is 11, the structure size is 92 (bytes), the offset of \fItcpi_sacked\fR\& is 28 bytes, and the value is a 32-bit integer\&. The following code can be used to retrieve the value:
.LP
.nf

get_tcpi_sacked(Sock) ->
    {ok,[{raw,_,_,Info}]} = inet:getopts(Sock,[{raw,6,11,92}]),
    <<_:28/binary,TcpiSacked:32/native,_/binary>> = Info,
    TcpiSacked.
.fi
.LP
Preferably, you would check the machine type, the operating system, and the Kernel version before executing anything similar to this code\&.
.RE

.LP
.nf

.B
getstat(Socket) -> {ok, OptionValues} | {error, posix()}
.br
.fi
.br
.nf

.B
getstat(Socket, Options) -> {ok, OptionValues} | {error, posix()}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Socket = \fBsocket()\fR\&
.br
Options = [\fBstat_option()\fR\&]
.br
OptionValues = [{\fBstat_option()\fR\&, integer()}]
.br
.nf
\fBstat_option()\fR\& = 
.br
    recv_cnt |
.br
    recv_max |
.br
    recv_avg |
.br
    recv_oct |
.br
    recv_dvi |
.br
    send_cnt |
.br
    send_max |
.br
    send_avg |
.br
    send_oct |
.br
    send_pend
.fi
.br
.RE
.RE
.RS
.LP
Gets one or more statistic options for a socket\&.
.LP
\fIgetstat(Socket)\fR\& is equivalent to \fIgetstat(Socket, [recv_avg, recv_cnt, recv_dvi, recv_max, recv_oct, send_avg, send_cnt, send_dvi, send_max, send_oct])\fR\&\&.
.LP
The following options are available:
.RS 2
.TP 2
.B
\fIrecv_avg\fR\&:
Average size of packets, in bytes, received by the socket\&.
.TP 2
.B
\fIrecv_cnt\fR\&:
Number of packets received by the socket\&.
.TP 2
.B
\fIrecv_dvi\fR\&:
Average packet size deviation, in bytes, received by the socket\&.
.TP 2
.B
\fIrecv_max\fR\&:
Size of the largest packet, in bytes, received by the socket\&.
.TP 2
.B
\fIrecv_oct\fR\&:
Number of bytes received by the socket\&.
.TP 2
.B
\fIsend_avg\fR\&:
Average size of packets, in bytes, sent from the socket\&.
.TP 2
.B
\fIsend_cnt\fR\&:
Number of packets sent from the socket\&.
.TP 2
.B
\fIsend_dvi\fR\&:
Average packet size deviation, in bytes, sent from the socket\&.
.TP 2
.B
\fIsend_max\fR\&:
Size of the largest packet, in bytes, sent from the socket\&.
.TP 2
.B
\fIsend_oct\fR\&:
Number of bytes sent from the socket\&.
.RE
.RE

.LP
.nf

.B
i() -> ok
.br
.fi
.br
.nf

.B
i(Proto :: socket_protocol()) -> ok
.br
.fi
.br
.nf

.B
i(X1 :: socket_protocol(), Fs :: [atom()]) -> ok
.br
.fi
.br
.RS
.LP
Lists all TCP, UDP and SCTP sockets, including those that the Erlang runtime system uses as well as those created by the application\&.
.LP
The following options are available:
.RS 2
.TP 2
.B
\fIport\fR\&:
The internal index of the port\&.
.TP 2
.B
\fImodule\fR\&:
The callback module of the socket\&.
.TP 2
.B
\fIrecv\fR\&:
Number of bytes received by the socket\&.
.TP 2
.B
\fIsent\fR\&:
Number of bytes sent from the socket\&.
.TP 2
.B
\fIowner\fR\&:
The socket owner process\&.
.TP 2
.B
\fIlocal_address\fR\&:
The local address of the socket\&.
.TP 2
.B
\fIforeign_address\fR\&:
The address and port of the other end of the connection\&.
.TP 2
.B
\fIstate\fR\&:
The connection state\&.
.TP 2
.B
\fItype\fR\&:
STREAM or DGRAM or SEQPACKET\&.
.RE
.RE

.LP
.nf

.B
ntoa(IpAddress) -> Address | {error, einval}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Address = string()
.br
IpAddress = \fBip_address()\fR\&
.br
.RE
.RE
.RS
.LP
Parses an \fB\fIip_address()\fR\&\fR\& and returns an IPv4 or IPv6 address string\&.
.RE

.LP
.nf

.B
parse_address(Address) -> {ok, IPAddress} | {error, einval}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Address = string()
.br
IPAddress = \fBip_address()\fR\&
.br
.RE
.RE
.RS
.LP
Parses an IPv4 or IPv6 address string and returns an \fB\fIip4_address()\fR\&\fR\& or \fB\fIip6_address()\fR\&\fR\&\&. Accepts a shortened IPv4 address string\&.
.RE

.LP
.nf

.B
parse_ipv4_address(Address) -> {ok, IPv4Address} | {error, einval}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Address = string()
.br
IPv4Address = \fBip_address()\fR\&
.br
.RE
.RE
.RS
.LP
Parses an IPv4 address string and returns an \fB\fIip4_address()\fR\&\fR\&\&. Accepts a shortened IPv4 address string\&.
.RE

.LP
.nf

.B
parse_ipv4strict_address(Address) ->
.B
                            {ok, IPv4Address} | {error, einval}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Address = string()
.br
IPv4Address = \fBip_address()\fR\&
.br
.RE
.RE
.RS
.LP
Parses an IPv4 address string containing four fields, that is, \fInot\fR\& shortened, and returns an \fB\fIip4_address()\fR\&\fR\&\&.
.RE

.LP
.nf

.B
parse_ipv6_address(Address) -> {ok, IPv6Address} | {error, einval}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Address = string()
.br
IPv6Address = \fBip_address()\fR\&
.br
.RE
.RE
.RS
.LP
Parses an IPv6 address string and returns an \fB\fIip6_address()\fR\&\fR\&\&. If an IPv4 address string is specified, an IPv4-mapped IPv6 address is returned\&.
.RE

.LP
.nf

.B
parse_ipv6strict_address(Address) ->
.B
                            {ok, IPv6Address} | {error, einval}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Address = string()
.br
IPv6Address = \fBip_address()\fR\&
.br
.RE
.RE
.RS
.LP
Parses an IPv6 address string and returns an \fB\fIip6_address()\fR\&\fR\&\&. Does \fInot\fR\& accept IPv4 addresses\&.
.RE

.LP
.nf

.B
ipv4_mapped_ipv6_address(X1 :: ip_address()) -> ip_address()
.br
.fi
.br
.RS
.LP
Convert an IPv4 address to an IPv4-mapped IPv6 address or the reverse\&. When converting from an IPv6 address all but the 2 low words are ignored so this function also works on some other types of addresses than IPv4-mapped\&.
.RE

.LP
.nf

.B
parse_strict_address(Address) -> {ok, IPAddress} | {error, einval}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Address = string()
.br
IPAddress = \fBip_address()\fR\&
.br
.RE
.RE
.RS
.LP
Parses an IPv4 or IPv6 address string and returns an \fB\fIip4_address()\fR\&\fR\& or \fB\fIip6_address()\fR\&\fR\&\&. Does \fInot\fR\& accept a shortened IPv4 address string\&.
.RE

.LP
.nf

.B
peername(Socket :: socket()) ->
.B
            {ok,
.B
             {ip_address(), port_number()} |
.B
             returned_non_ip_address()} |
.B
            {error, posix()}
.br
.fi
.br
.RS
.LP
Returns the address and port for the other end of a connection\&.
.LP
Notice that for SCTP sockets, this function returns only one of the peer addresses of the socket\&. Function \fB\fIpeernames/1,2\fR\&\fR\& returns all\&.
.RE

.LP
.nf

.B
peernames(Socket :: socket()) ->
.B
             {ok,
.B
              [{ip_address(), port_number()} |
.B
               returned_non_ip_address()]} |
.B
             {error, posix()}
.br
.fi
.br
.RS
.LP
Equivalent to \fB\fIpeernames(Socket, 0)\fR\&\fR\&\&.
.LP
Notice that the behavior of this function for an SCTP one-to-many style socket is not defined by the SCTP Sockets API Extensions\&.
.RE

.LP
.nf

.B
peernames(Socket, Assoc) ->
.B
             {ok, [{Address, Port}]} | {error, posix()}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Socket = \fBsocket()\fR\&
.br
Assoc = #sctp_assoc_change{} | \fBgen_sctp:assoc_id()\fR\&
.br
Address = \fBip_address()\fR\&
.br
Port = integer() >= 0
.br
.RE
.RE
.RS
.LP
Returns a list of all address/port number pairs for the other end of an association \fIAssoc\fR\& of a socket\&.
.LP
This function can return multiple addresses for multihomed sockets, such as SCTP sockets\&. For other sockets it returns a one-element list\&.
.LP
Notice that parameter \fIAssoc\fR\& is by the SCTP Sockets API Extensions defined to be ignored for one-to-one style sockets\&. What the special value \fI0\fR\& means, hence its behavior for one-to-many style sockets, is unfortunately undefined\&.
.RE

.LP
.nf

.B
port(Socket) -> {ok, Port} | {error, any()}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Socket = \fBsocket()\fR\&
.br
Port = \fBport_number()\fR\&
.br
.RE
.RE
.RS
.LP
Returns the local port number for a socket\&.
.RE

.LP
.nf

.B
setopts(Socket, Options) -> ok | {error, posix()}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Socket = \fBsocket()\fR\&
.br
Options = [\fBsocket_setopt()\fR\&]
.br
.RE
.RE
.RS
.LP
Sets one or more options for a socket\&.
.LP
The following options are available:
.RS 2
.TP 2
.B
\fI{active, true | false | once | N}\fR\&:
If the value is \fItrue\fR\&, which is the default, everything received from the socket is sent as messages to the receiving process\&.
.RS 2
.LP
If the value is \fIfalse\fR\& (passive mode), the process must explicitly receive incoming data by calling \fB\fIgen_tcp:recv/2,3\fR\&\fR\&, \fB\fIgen_udp:recv/2,3\fR\&\fR\&, or \fB\fIgen_sctp:recv/1,2\fR\&\fR\& (depending on the type of socket)\&.
.RE

.RS 2
.LP
If the value is \fIonce\fR\& (\fI{active, once}\fR\&), \fIone\fR\& data message from the socket is sent to the process\&. To receive one more message, \fIsetopts/2\fR\& must be called again with option \fI{active, once}\fR\&\&.
.RE

.RS 2
.LP
If the value is an integer \fIN\fR\& in the range -32768 to 32767 (inclusive), the value is added to the socket\&'s count of data messages sent to the controlling process\&. A socket\&'s default message count is \fI0\fR\&\&. If a negative value is specified, and its magnitude is equal to or greater than the socket\&'s current message count, the socket\&'s message count is set to \fI0\fR\&\&. Once the socket\&'s message count reaches \fI0\fR\&, either because of sending received data messages to the process or by being explicitly set, the process is then notified by a special message, specific to the type of socket, that the socket has entered passive mode\&. Once the socket enters passive mode, to receive more messages \fIsetopts/2\fR\& must be called again to set the socket back into an active mode\&.
.RE

.RS 2
.LP
When using \fI{active, once}\fR\& or \fI{active, N}\fR\&, the socket changes behavior automatically when data is received\&. This can be confusing in combination with connection-oriented sockets (that is, \fIgen_tcp\fR\&), as a socket with \fI{active, false}\fR\& behavior reports closing differently than a socket with \fI{active, true}\fR\& behavior\&. To simplify programming, a socket where the peer closed, and this is detected while in \fI{active, false}\fR\& mode, still generates message \fI{tcp_closed,Socket}\fR\& when set to \fI{active, once}\fR\&, \fI{active, true}\fR\&, or \fI{active, N}\fR\& mode\&. It is therefore safe to assume that message \fI{tcp_closed,Socket}\fR\&, possibly followed by socket port termination (depending on option \fIexit_on_close\fR\&) eventually appears when a socket changes back and forth between \fI{active, true}\fR\& and \fI{active, false}\fR\& mode\&. However, \fIwhen\fR\& peer closing is detected it is all up to the underlying TCP/IP stack and protocol\&.
.RE

.RS 2
.LP
Notice that \fI{active, true}\fR\& mode provides no flow control; a fast sender can easily overflow the receiver with incoming messages\&. The same is true for \fI{active, N}\fR\& mode, while the message count is greater than zero\&.
.RE

.RS 2
.LP
Use active mode only if your high-level protocol provides its own flow control (for example, acknowledging received messages) or the amount of data exchanged is small\&. \fI{active, false}\fR\& mode, use of the \fI{active, once}\fR\& mode, or \fI{active, N}\fR\& mode with values of \fIN\fR\& appropriate for the application provides flow control\&. The other side cannot send faster than the receiver can read\&.
.RE

.TP 2
.B
\fI{broadcast, Boolean}\fR\& (UDP sockets):
Enables/disables permission to send broadcasts\&.
.TP 2
.B
\fI{buffer, Size}\fR\&:
The size of the user-level buffer used by the driver\&. Not to be confused with options \fIsndbuf\fR\& and \fIrecbuf\fR\&, which correspond to the Kernel socket buffers\&. For TCP it is recommended to have \fIval(buffer) >= val(recbuf)\fR\& to avoid performance issues because of unnecessary copying\&. For UDP the same recommendation applies, but the max should not be larger than the MTU of the network path\&. \fIval(buffer)\fR\& is automatically set to the above maximum when \fIrecbuf\fR\& is set\&. However, as the size set for \fIrecbuf\fR\& usually become larger, you are encouraged to use \fB\fIgetopts/2\fR\&\fR\& to analyze the behavior of your operating system\&.
.RS 2
.LP
Note that this is also the maximum amount of data that can be received from a single recv call\&. If you are using higher than normal MTU consider setting buffer higher\&.
.RE

.TP 2
.B
\fI{delay_send, Boolean}\fR\&:
Normally, when an Erlang process sends to a socket, the driver tries to send the data immediately\&. If that fails, the driver uses any means available to queue up the message to be sent whenever the operating system says it can handle it\&. Setting \fI{delay_send, true}\fR\& makes \fIall\fR\& messages queue up\&. The messages sent to the network are then larger but fewer\&. The option affects the scheduling of send requests versus Erlang processes instead of changing any real property of the socket\&. The option is implementation-specific\&. Defaults to \fIfalse\fR\&\&.
.TP 2
.B
\fI{deliver, port | term}\fR\&:
When \fI{active, true}\fR\&, data is delivered on the form \fIport\fR\& : \fI{S, {data, [H1,\&.\&.Hsz | Data]}}\fR\& or \fIterm\fR\& : \fI{tcp, S, [H1\&.\&.Hsz | Data]}\fR\&\&.
.TP 2
.B
\fI{dontroute, Boolean}\fR\&:
Enables/disables routing bypass for outgoing messages\&.
.TP 2
.B
\fI{exit_on_close, Boolean}\fR\&:
This option is set to \fItrue\fR\& by default\&.
.RS 2
.LP
The only reason to set it to \fIfalse\fR\& is if you want to continue sending data to the socket after a close is detected, for example, if the peer uses \fB\fIgen_tcp:shutdown/2\fR\&\fR\& to shut down the write side\&.
.RE

.TP 2
.B
\fI{header, Size}\fR\&:
This option is only meaningful if option \fIbinary\fR\& was specified when the socket was created\&. If option \fIheader\fR\& is specified, the first \fISize\fR\& number bytes of data received from the socket are elements of a list, and the remaining data is a binary specified as the tail of the same list\&. For example, if \fISize == 2\fR\&, the data received matches \fI[Byte1,Byte2|Binary]\fR\&\&.
.TP 2
.B
\fI{high_msgq_watermark, Size}\fR\&:
The socket message queue is set to a busy state when the amount of data on the message queue reaches this limit\&. Notice that this limit only concerns data that has not yet reached the ERTS internal socket implementation\&. Defaults to 8 kB\&.
.RS 2
.LP
Senders of data to the socket are suspended if either the socket message queue is busy or the socket itself is busy\&.
.RE

.RS 2
.LP
For more information, see options \fIlow_msgq_watermark\fR\&, \fIhigh_watermark\fR\&, and \fIlow_watermark\fR\&\&.
.RE

.RS 2
.LP
Notice that distribution sockets disable the use of \fIhigh_msgq_watermark\fR\& and \fIlow_msgq_watermark\fR\&\&. Instead use the \fBdistribution buffer busy limit\fR\&, which is a similar feature\&.
.RE

.TP 2
.B
\fI{high_watermark, Size}\fR\& (TCP/IP sockets):
The socket is set to a busy state when the amount of data queued internally by the ERTS socket implementation reaches this limit\&. Defaults to 8 kB\&.
.RS 2
.LP
Senders of data to the socket are suspended if either the socket message queue is busy or the socket itself is busy\&.
.RE

.RS 2
.LP
For more information, see options \fIlow_watermark\fR\&, \fIhigh_msgq_watermark\fR\&, and \fIlow_msqg_watermark\fR\&\&.
.RE

.TP 2
.B
\fI{ipv6_v6only, Boolean}\fR\&:
Restricts the socket to use only IPv6, prohibiting any IPv4 connections\&. This is only applicable for IPv6 sockets (option \fIinet6\fR\&)\&.
.RS 2
.LP
On most platforms this option must be set on the socket before associating it to an address\&. It is therefore only reasonable to specify it when creating the socket and not to use it when calling function (\fB\fIsetopts/2\fR\&\fR\&) containing this description\&.
.RE

.RS 2
.LP
The behavior of a socket with this option set to \fItrue\fR\& is 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 \fI{ipv6_v6only,false}\fR\& to override the recommended system default value), forbidden by OpenBSD (the supported GENERIC kernel), and impossible on Windows (which has separate IPv4 and IPv6 protocol stacks)\&. Most Linux distros still have a system default value of \fIfalse\fR\&\&. This policy shift among operating systems to separate IPv6 from IPv4 traffic has evolved, as it gradually proved hard and complicated to get a dual stack implementation correct and secure\&.
.RE

.RS 2
.LP
On some platforms, the only allowed value for this option is \fItrue\fR\&, for example, OpenBSD and Windows\&. Trying to set this option to \fIfalse\fR\&, when creating the socket, fails in this case\&.
.RE

.RS 2
.LP
Setting this option on platforms where it does not exist is ignored\&. Getting this option with \fB\fIgetopts/2\fR\&\fR\& returns no value, that is, the returned list does not contain an \fI{ipv6_v6only,_}\fR\& tuple\&. On Windows, the option does not exist, but it is emulated as a read-only option with value \fItrue\fR\&\&.
.RE

.RS 2
.LP
Therefore, setting this option to \fItrue\fR\& when creating a socket never fails, except possibly on a platform where you have customized the kernel to only allow \fIfalse\fR\&, which can be doable (but awkward) on, for example, OpenBSD\&.
.RE

.RS 2
.LP
If you read back the option value using \fB\fIgetopts/2\fR\&\fR\& and get no value, the option does not exist in the host operating system\&. The behavior of both an IPv6 and an IPv4 socket listening on the same port, and for an IPv6 socket getting IPv4 traffic is then no longer predictable\&.
.RE

.TP 2
.B
\fI{keepalive, Boolean}\fR\&(TCP/IP sockets):
Enables/disables periodic transmission on a connected socket when no other data is exchanged\&. If the other end does not respond, the connection is considered broken and an error message is sent to the controlling process\&. Defaults to \fIdisabled\fR\&\&.
.TP 2
.B
\fI{linger, {true|false, Seconds}}\fR\&:
Determines the time-out, in seconds, for flushing unsent data in the \fIclose/1\fR\& socket call\&. If the first component of the value tuple is \fIfalse\fR\&, the second is ignored\&. This means that \fIclose/1\fR\& returns immediately, not waiting for data to be flushed\&. Otherwise, the second component is the flushing time-out, in seconds\&.
.TP 2
.B
\fI{low_msgq_watermark, Size}\fR\&:
If the socket message queue is in a busy state, the socket message queue is set in a not busy state when the amount of data queued in the message queue falls below this limit\&. Notice that this limit only concerns data that has not yet reached the ERTS internal socket implementation\&. Defaults to 4 kB\&.
.RS 2
.LP
Senders that are suspended because of either a busy message queue or a busy socket are resumed when the socket message queue and the socket are not busy\&.
.RE

.RS 2
.LP
For more information, see options \fIhigh_msgq_watermark\fR\&, \fIhigh_watermark\fR\&, and \fIlow_watermark\fR\&\&.
.RE

.RS 2
.LP
Notice that distribution sockets disable the use of \fIhigh_msgq_watermark\fR\& and \fIlow_msgq_watermark\fR\&\&. Instead they use the \fBdistribution buffer busy limit\fR\&, which is a similar feature\&.
.RE

.TP 2
.B
\fI{low_watermark, Size}\fR\& (TCP/IP sockets):
If the socket is in a busy state, the socket is set in a not busy state when the amount of data queued internally by the ERTS socket implementation falls below this limit\&. Defaults to 4 kB\&.
.RS 2
.LP
Senders that are suspended because of a busy message queue or a busy socket are resumed when the socket message queue and the socket are not busy\&.
.RE

.RS 2
.LP
For more information, see options \fIhigh_watermark\fR\&, \fIhigh_msgq_watermark\fR\&, and \fIlow_msgq_watermark\fR\&\&.
.RE

.TP 2
.B
\fI{mode, Mode :: binary | list}\fR\&:
Received \fIPacket\fR\& is delivered as defined by \fIMode\fR\&\&.
.TP 2
.B
\fI{netns, Namespace :: file:filename_all()}\fR\&:
Sets a network namespace for the socket\&. Parameter \fINamespace\fR\& is a filename defining the namespace, for example, \fI"/var/run/netns/example"\fR\&, typically created by command \fIip netns add example\fR\&\&. This option must be used in a function call that creates a socket, that is, \fB\fIgen_tcp:connect/3,4\fR\&\fR\&, \fB\fIgen_tcp:listen/2\fR\&\fR\&, \fB\fIgen_udp:open/1,2\fR\&\fR\& or \fB\fIgen_sctp:open/0,1,2\fR\&\fR\&, and also \fB\fIgetifaddrs/1\fR\&\fR\&\&.
.RS 2
.LP
This option uses the Linux-specific syscall \fIsetns()\fR\&, such as in Linux kernel 3\&.0 or later, and therefore only exists when the runtime system is compiled for such an operating system\&.
.RE

.RS 2
.LP
The virtual machine also needs elevated privileges, either running as superuser or (for Linux) having capability \fICAP_SYS_ADMIN\fR\& according to the documentation for \fIsetns(2)\fR\&\&. However, during testing also \fICAP_SYS_PTRACE\fR\& and \fICAP_DAC_READ_SEARCH\fR\& have proven to be necessary\&.
.RE

.RS 2
.LP
\fIExample:\fR\&
.RE

.LP
.nf

setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp
.fi
.RS 2
.LP
Notice that the filesystem containing the virtual machine executable (\fIbeam\&.smp\fR\& in the example) must be local, mounted without flag \fInosetuid\fR\&, support extended attributes, and the kernel must support file capabilities\&. All this runs out of the box on at least Ubuntu 12\&.04 LTS, except that SCTP sockets appear to not support network namespaces\&.
.RE

.RS 2
.LP
\fINamespace\fR\& is a filename and is encoded and decoded as discussed in module \fBfile\fR\&, with the following exceptions:
.RE

.RS 2
.TP 2
*
Emulator flag \fI+fnu\fR\& is ignored\&.
.LP
.TP 2
*
\fB\fIgetopts/2\fR\&\fR\& for this option returns a binary for the filename if the stored filename cannot be decoded\&. This is only to occur if you set the option using a binary that cannot be decoded with the emulator\&'s filename encoding: \fB\fIfile:native_name_encoding/0\fR\&\fR\&\&.
.LP
.RE

.TP 2
.B
\fI{bind_to_device, Ifname :: binary()}\fR\&:
Binds a socket to a specific network interface\&. This option must be used in a function call that creates a socket, that is, \fB\fIgen_tcp:connect/3,4\fR\&\fR\&, \fB\fIgen_tcp:listen/2\fR\&\fR\&, \fB\fIgen_udp:open/1,2\fR\&\fR\&, or \fB\fIgen_sctp:open/0,1,2\fR\&\fR\&\&.
.RS 2
.LP
Unlike \fB\fIgetifaddrs/0\fR\&\fR\&, Ifname is encoded a binary\&. In the unlikely case that a system is using non-7-bit-ASCII characters in network device names, special care has to be taken when encoding this argument\&.
.RE

.RS 2
.LP
This option uses the Linux-specific socket option \fISO_BINDTODEVICE\fR\&, such as in Linux kernel 2\&.0\&.30 or later, and therefore only exists when the runtime system is compiled for such an operating system\&.
.RE

.RS 2
.LP
Before Linux 3\&.8, this socket option could be set, but could not retrieved with \fB\fIgetopts/2\fR\&\fR\&\&. Since Linux 3\&.8, it is readable\&.
.RE

.RS 2
.LP
The virtual machine also needs elevated privileges, either running as superuser or (for Linux) having capability \fICAP_NET_RAW\fR\&\&.
.RE

.RS 2
.LP
The primary use case for this option is to bind sockets into Linux VRF instances\&.
.RE

.TP 2
.B
\fIlist\fR\&:
Received \fIPacket\fR\& is delivered as a list\&.
.TP 2
.B
\fIbinary\fR\&:
Received \fIPacket\fR\& is delivered as a binary\&.
.TP 2
.B
\fI{nodelay, Boolean}\fR\&(TCP/IP sockets):
If \fIBoolean == true\fR\&, option \fITCP_NODELAY\fR\& is turned on for the socket, which means that also small amounts of data are sent immediately\&.
.TP 2
.B
\fI{nopush, Boolean}\fR\&(TCP/IP sockets):
This translates to \fITCP_NOPUSH\fR\& on BSD and to \fITCP_CORK\fR\& on Linux\&.
.RS 2
.LP
If \fIBoolean == true\fR\&, the corresponding option is turned on for the socket, which means that small amounts of data are accumulated until a full MSS-worth of data is available or this option is turned off\&.
.RE

.RS 2
.LP
Note that while \fITCP_NOPUSH\fR\& socket option is available on OSX, its semantics is very different (e\&.g\&., unsetting it does not cause immediate send of accumulated data)\&. Hence, \fInopush\fR\& option is intentionally ignored on OSX\&.
.RE

.TP 2
.B
\fI{packet, PacketType}\fR\&(TCP/IP sockets):
Defines the type of packets to use for a socket\&. Possible values:
.RS 2
.TP 2
.B
\fIraw | 0\fR\&:
No packaging is done\&.
.TP 2
.B
\fI1 | 2 | 4\fR\&:
Packets consist of a header specifying the number of bytes in the packet, followed by that number of bytes\&. The header length can be one, two, or four bytes, and containing an unsigned integer in big-endian byte order\&. Each send operation generates the header, and the header is stripped off on each receive operation\&.
.RS 2
.LP
The 4-byte header is limited to 2Gb\&.
.RE

.TP 2
.B
\fIasn1 | cdr | sunrm | fcgi | tpkt | line\fR\&:
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, one message is sent to the controlling process for each complete packet received, and, similarly, each call to \fIgen_tcp:recv/2,3\fR\& returns one complete packet\&. The header is \fInot\fR\& stripped off\&.
.RS 2
.LP
The meanings of the packet types are as follows:
.RE

.RS 2
.TP 2
*
\fIasn1\fR\& - ASN\&.1 BER
.LP
.TP 2
*
\fIsunrm\fR\& - Sun\&'s RPC encoding
.LP
.TP 2
*
\fIcdr\fR\& - CORBA (GIOP 1\&.1)
.LP
.TP 2
*
\fIfcgi\fR\& - Fast CGI
.LP
.TP 2
*
\fItpkt\fR\& - TPKT format [RFC1006]
.LP
.TP 2
*
\fIline\fR\& - Line mode, a packet is a line-terminated with newline, lines longer than the receive buffer are truncated
.LP
.RE

.TP 2
.B
\fIhttp | http_bin\fR\&:
The Hypertext Transfer Protocol\&. The packets are returned with the format according to \fIHttpPacket\fR\& described in \fB\fIerlang:decode_packet/3\fR\&\fR\& in ERTS\&. A socket in passive mode returns \fI{ok, HttpPacket}\fR\& from \fIgen_tcp:recv\fR\& while an active socket sends messages like \fI{http, Socket, HttpPacket}\fR\&\&.
.TP 2
.B
\fIhttph | httph_bin\fR\&:
These two types are often not needed, as the socket automatically switches from \fIhttp\fR\&/\fIhttp_bin\fR\& to \fIhttph\fR\&/\fIhttph_bin\fR\& internally after the first line is read\&. However, there can be occasions when they are useful, such as parsing trailers from chunked encoding\&.
.RE
.TP 2
.B
\fI{packet_size, Integer}\fR\&(TCP/IP sockets):
Sets the maximum allowed length of the packet body\&. If the packet header indicates that the length of the packet is longer than the maximum allowed length, the packet is considered invalid\&. The same occurs if the packet header is too large for the socket receive buffer\&.
.RS 2
.LP
For line-oriented protocols (\fIline\fR\&, \fIhttp*\fR\&), option \fIpacket_size\fR\& also guarantees that lines up to the indicated length are accepted and not considered invalid because of internal buffer limitations\&.
.RE

.TP 2
.B
\fI{line_delimiter, Char}\fR\&(TCP/IP sockets):
Sets the line delimiting character for line-oriented protocols (\fIline\fR\&)\&. Defaults to \fI$\\n\fR\&\&.
.TP 2
.B
\fI{raw, Protocol, OptionNum, ValueBin}\fR\&:
See below\&.
.TP 2
.B
\fI{read_packets, Integer}\fR\&(UDP sockets):
Sets the maximum 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\&. Defaults to \fI5\fR\&\&. If this parameter is set too high, the system can become unresponsive because of UDP packet flooding\&.
.TP 2
.B
\fI{recbuf, Size}\fR\&:
The minimum size of the receive buffer to use for the socket\&. You are encouraged to use \fB\fIgetopts/2\fR\&\fR\& to retrieve the size set by your operating system\&.
.TP 2
.B
\fI{recvtclass, Boolean}\fR\&:
If set to \fItrue\fR\& activates returning the received \fITCLASS\fR\& value on platforms that implements the protocol \fIIPPROTO_IPV6\fR\& option \fIIPV6_RECVTCLASS\fR\& or \fIIPV6_2292RECVTCLASS\fR\& for the socket\&. The value is returned as a \fI{tclass,TCLASS}\fR\& tuple regardless of if the platform returns an \fIIPV6_TCLASS\fR\& or an \fIIPV6_RECVTCLASS\fR\& CMSG value\&.
.RS 2
.LP
For packet oriented sockets that supports receiving ancillary data with the payload data (\fIgen_udp\fR\& and \fIgen_sctp\fR\&), the \fITCLASS\fR\& value is returned in an extended return tuple contained in an \fB ancillary data \fR\& list\&. For stream oriented sockets (\fIgen_tcp\fR\&) the only way to get the \fITCLASS\fR\& value is if the platform supports the \fB\fIpktoptions\fR\&\fR\& option\&.
.RE

.TP 2
.B
\fI{recvtos, Boolean}\fR\&:
If set to \fItrue\fR\& activates returning the received \fITOS\fR\& value on platforms that implements the protocol \fIIPPROTO_IP\fR\& option \fIIP_RECVTOS\fR\& for the socket\&. The value is returned as a \fI{tos,TOS}\fR\& tuple regardless of if the platform returns an \fIIP_TOS\fR\& or an \fIIP_RECVTOS\fR\& CMSG value\&.
.RS 2
.LP
For packet oriented sockets that supports receiving ancillary data with the payload data (\fIgen_udp\fR\& and \fIgen_sctp\fR\&), the \fITOS\fR\& value is returned in an extended return tuple contained in an \fB ancillary data \fR\& list\&. For stream oriented sockets (\fIgen_tcp\fR\&) the only way to get the \fITOS\fR\& value is if the platform supports the \fB\fIpktoptions\fR\&\fR\& option\&.
.RE

.TP 2
.B
\fI{recvttl, Boolean}\fR\&:
If set to \fItrue\fR\& activates returning the received \fITTL\fR\& value on platforms that implements the protocol \fIIPPROTO_IP\fR\& option \fIIP_RECVTTL\fR\& for the socket\&. The value is returned as a \fI{ttl,TTL}\fR\& tuple regardless of if the platform returns an \fIIP_TTL\fR\& or an \fIIP_RECVTTL\fR\& CMSG value\&.
.RS 2
.LP
For packet oriented sockets that supports receiving ancillary data with the payload data (\fIgen_udp\fR\& and \fIgen_sctp\fR\&), the \fITTL\fR\& value is returned in an extended return tuple contained in an \fB ancillary data \fR\& list\&. For stream oriented sockets (\fIgen_tcp\fR\&) the only way to get the \fITTL\fR\& value is if the platform supports the \fB\fIpktoptions\fR\&\fR\& option\&.
.RE

.TP 2
.B
\fI{reuseaddr, Boolean}\fR\&:
Allows or disallows local reuse of port numbers\&. By default, reuse is disallowed\&.
.TP 2
.B
\fI{send_timeout, Integer}\fR\&:
Only allowed for connection-oriented sockets\&.
.RS 2
.LP
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 returns \fI{error,timeout}\fR\&\&. How much of a packet that got sent is unknown; the socket is therefore to be closed whenever a time-out has occurred (see \fIsend_timeout_close\fR\& below)\&. Defaults to \fIinfinity\fR\&\&.
.RE

.TP 2
.B
\fI{send_timeout_close, Boolean}\fR\&:
Only allowed for connection-oriented sockets\&.
.RS 2
.LP
Used together with \fIsend_timeout\fR\& to specify whether the socket is to be automatically closed when the send operation returns \fI{error,timeout}\fR\&\&. The recommended setting is \fItrue\fR\&, which automatically closes the socket\&. Defaults to \fIfalse\fR\& because of backward compatibility\&.
.RE

.TP 2
.B
\fI{show_econnreset, Boolean}\fR\&(TCP/IP sockets):
When this option is set to \fIfalse\fR\&, which is default, an RST received from the TCP peer is treated as a normal close (as though an FIN was sent)\&. A caller to \fB\fIgen_tcp:recv/2\fR\&\fR\& gets \fI{error, closed}\fR\&\&. In active mode, the controlling process receives a \fI{tcp_closed, Socket}\fR\& message, indicating that the peer has closed the connection\&.
.RS 2
.LP
Setting this option to \fItrue\fR\& allows you to distinguish between a connection that was closed normally, and one that was aborted (intentionally or unintentionally) by the TCP peer\&. A call to \fB\fIgen_tcp:recv/2\fR\&\fR\& returns \fI{error, econnreset}\fR\&\&. In active mode, the controlling process receives a \fI{tcp_error, Socket, econnreset}\fR\& message before the usual \fI{tcp_closed, Socket}\fR\&, as is the case for any other socket error\&. Calls to \fB\fIgen_tcp:send/2\fR\&\fR\& also returns \fI{error, econnreset}\fR\& when it is detected that a TCP peer has sent an RST\&.
.RE

.RS 2
.LP
A connected socket returned from \fB\fIgen_tcp:accept/1\fR\&\fR\& inherits the \fIshow_econnreset\fR\& setting from the listening socket\&.
.RE

.TP 2
.B
\fI{sndbuf, Size}\fR\&:
The minimum size of the send buffer to use for the socket\&. You are encouraged to use \fB\fIgetopts/2\fR\&\fR\&, to retrieve the size set by your operating system\&.
.TP 2
.B
\fI{priority, Integer}\fR\&:
Sets the \fISO_PRIORITY\fR\& socket level option on platforms where this is implemented\&. The behavior and allowed range varies between different systems\&. The option is ignored on platforms where it is not implemented\&. Use with caution\&.
.TP 2
.B
\fI{tos, Integer}\fR\&:
Sets \fIIP_TOS IP\fR\& level options on platforms where this is implemented\&. The behavior and allowed range varies between different systems\&. The option is ignored on platforms where it is not implemented\&. Use with caution\&.
.TP 2
.B
\fI{tclass, Integer}\fR\&:
Sets \fIIPV6_TCLASS IP\fR\& level options on platforms where this is implemented\&. The behavior and allowed range varies between different systems\&. The option is ignored on platforms where it is not implemented\&. Use with caution\&.
.RE
.LP
In addition to these options, \fIraw\fR\& option specifications can be used\&. The raw options are specified as a tuple of arity four, beginning with tag \fIraw\fR\&, followed by the protocol level, the option number, and the option value specified as a binary\&. This corresponds to the second, third, and fourth arguments to the \fIsetsockopt\fR\& call in the C socket API\&. The option value must be coded in the native endianess of the platform and, if a structure is required, must follow the structure alignment conventions on the specific platform\&.
.LP
Using raw socket options requires detailed knowledge about the current operating system and TCP stack\&.
.LP
\fIExample:\fR\&
.LP
This example concerns the use of raw options\&. Consider a Linux system where you want to set option \fITCP_LINGER2\fR\& on protocol level \fIIPPROTO_TCP\fR\& in the stack\&. You know that on this particular system it defaults to 60 (seconds), but you want to lower it to 30 for a particular socket\&. Option \fITCP_LINGER2\fR\& is not explicitly supported by \fIinet\fR\&, but you know that the protocol level translates to number 6, the option number to number 8, and the value is to be specified as a 32-bit integer\&. You can use this code line to set the option for the socket named \fISock\fR\&:
.LP
.nf

inet:setopts(Sock,[{raw,6,8,<<30:32/native>>}]),
.fi
.LP
As many options are silently discarded by the stack if they are specified out of range; it can be a good idea to check that a raw option is accepted\&. The following code places the value in variable \fITcpLinger2:\fR\&
.LP
.nf

{ok,[{raw,6,8,<<TcpLinger2:32/native>>}]}=inet:getopts(Sock,[{raw,6,8,4}]),
.fi
.LP
Code such as these examples is inherently non-portable, even different versions of the same OS on the same platform can respond differently to this kind of option manipulation\&. Use with care\&.
.LP
Notice that the default options for TCP/IP sockets can be changed with the Kernel configuration parameters mentioned in the beginning of this manual page\&.
.RE

.LP
.nf

.B
sockname(Socket :: socket()) ->
.B
            {ok,
.B
             {ip_address(), port_number()} |
.B
             returned_non_ip_address()} |
.B
            {error, posix()}
.br
.fi
.br
.RS
.LP
Returns the local address and port number for a socket\&.
.LP
Notice that for SCTP sockets this function returns only one of the socket addresses\&. Function \fB\fIsocknames/1,2\fR\&\fR\& returns all\&.
.RE

.LP
.nf

.B
socknames(Socket :: socket()) ->
.B
             {ok,
.B
              [{ip_address(), port_number()} |
.B
               returned_non_ip_address()]} |
.B
             {error, posix()}
.br
.fi
.br
.RS
.LP
Equivalent to \fB\fIsocknames(Socket, 0)\fR\&\fR\&\&.
.RE

.LP
.nf

.B
socknames(Socket, Assoc) ->
.B
             {ok, [{Address, Port}]} | {error, posix()}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Socket = \fBsocket()\fR\&
.br
Assoc = #sctp_assoc_change{} | \fBgen_sctp:assoc_id()\fR\&
.br
Address = \fBip_address()\fR\&
.br
Port = integer() >= 0
.br
.RE
.RE
.RS
.LP
Returns a list of all local address/port number pairs for a socket for the specified association \fIAssoc\fR\&\&.
.LP
This function can return multiple addresses for multihomed sockets, such as SCTP sockets\&. For other sockets it returns a one-element list\&.
.LP
Notice that parameter \fIAssoc\fR\& is by the SCTP Sockets API Extensions defined to be ignored for one-to-one style sockets\&. For one-to-many style sockets, the special value \fI0\fR\& is defined to mean that the returned addresses must be without any particular association\&. How different SCTP implementations interpret this varies somewhat\&.
.RE

.SH "POSIX ERROR CODES"

.RS 2
.TP 2
*
\fIe2big\fR\& - Too long argument list
.LP
.TP 2
*
\fIeacces\fR\& - Permission denied
.LP
.TP 2
*
\fIeaddrinuse\fR\& - Address already in use
.LP
.TP 2
*
\fIeaddrnotavail\fR\& - Cannot assign requested address
.LP
.TP 2
*
\fIeadv\fR\& - Advertise error
.LP
.TP 2
*
\fIeafnosupport\fR\& - Address family not supported by protocol family
.LP
.TP 2
*
\fIeagain\fR\& - Resource temporarily unavailable
.LP
.TP 2
*
\fIealign\fR\& - EALIGN
.LP
.TP 2
*
\fIealready\fR\& - Operation already in progress
.LP
.TP 2
*
\fIebade\fR\& - Bad exchange descriptor
.LP
.TP 2
*
\fIebadf\fR\& - Bad file number
.LP
.TP 2
*
\fIebadfd\fR\& - File descriptor in bad state
.LP
.TP 2
*
\fIebadmsg\fR\& - Not a data message
.LP
.TP 2
*
\fIebadr\fR\& - Bad request descriptor
.LP
.TP 2
*
\fIebadrpc\fR\& - Bad RPC structure
.LP
.TP 2
*
\fIebadrqc\fR\& - Bad request code
.LP
.TP 2
*
\fIebadslt\fR\& - Invalid slot
.LP
.TP 2
*
\fIebfont\fR\& - Bad font file format
.LP
.TP 2
*
\fIebusy\fR\& - File busy
.LP
.TP 2
*
\fIechild\fR\& - No children
.LP
.TP 2
*
\fIechrng\fR\& - Channel number out of range
.LP
.TP 2
*
\fIecomm\fR\& - Communication error on send
.LP
.TP 2
*
\fIeconnaborted\fR\& - Software caused connection abort
.LP
.TP 2
*
\fIeconnrefused\fR\& - Connection refused
.LP
.TP 2
*
\fIeconnreset\fR\& - Connection reset by peer
.LP
.TP 2
*
\fIedeadlk\fR\& - Resource deadlock avoided
.LP
.TP 2
*
\fIedeadlock\fR\& - Resource deadlock avoided
.LP
.TP 2
*
\fIedestaddrreq\fR\& - Destination address required
.LP
.TP 2
*
\fIedirty\fR\& - Mounting a dirty fs without force
.LP
.TP 2
*
\fIedom\fR\& - Math argument out of range
.LP
.TP 2
*
\fIedotdot\fR\& - Cross mount point
.LP
.TP 2
*
\fIedquot\fR\& - Disk quota exceeded
.LP
.TP 2
*
\fIeduppkg\fR\& - Duplicate package name
.LP
.TP 2
*
\fIeexist\fR\& - File already exists
.LP
.TP 2
*
\fIefault\fR\& - Bad address in system call argument
.LP
.TP 2
*
\fIefbig\fR\& - File too large
.LP
.TP 2
*
\fIehostdown\fR\& - Host is down
.LP
.TP 2
*
\fIehostunreach\fR\& - Host is unreachable
.LP
.TP 2
*
\fIeidrm\fR\& - Identifier removed
.LP
.TP 2
*
\fIeinit\fR\& - Initialization error
.LP
.TP 2
*
\fIeinprogress\fR\& - Operation now in progress
.LP
.TP 2
*
\fIeintr\fR\& - Interrupted system call
.LP
.TP 2
*
\fIeinval\fR\& - Invalid argument
.LP
.TP 2
*
\fIeio\fR\& - I/O error
.LP
.TP 2
*
\fIeisconn\fR\& - Socket is already connected
.LP
.TP 2
*
\fIeisdir\fR\& - Illegal operation on a directory
.LP
.TP 2
*
\fIeisnam\fR\& - Is a named file
.LP
.TP 2
*
\fIel2hlt\fR\& - Level 2 halted
.LP
.TP 2
*
\fIel2nsync\fR\& - Level 2 not synchronized
.LP
.TP 2
*
\fIel3hlt\fR\& - Level 3 halted
.LP
.TP 2
*
\fIel3rst\fR\& - Level 3 reset
.LP
.TP 2
*
\fIelbin\fR\& - ELBIN
.LP
.TP 2
*
\fIelibacc\fR\& - Cannot access a needed shared library
.LP
.TP 2
*
\fIelibbad\fR\& - Accessing a corrupted shared library
.LP
.TP 2
*
\fIelibexec\fR\& - Cannot exec a shared library directly
.LP
.TP 2
*
\fIelibmax\fR\& - Attempting to link in more shared libraries than system limit
.LP
.TP 2
*
\fIelibscn\fR\& - \fI\&.lib\fR\& section in \fIa\&.out\fR\& corrupted
.LP
.TP 2
*
\fIelnrng\fR\& - Link number out of range
.LP
.TP 2
*
\fIeloop\fR\& - Too many levels of symbolic links
.LP
.TP 2
*
\fIemfile\fR\& - Too many open files
.LP
.TP 2
*
\fIemlink\fR\& - Too many links
.LP
.TP 2
*
\fIemsgsize\fR\& - Message too long
.LP
.TP 2
*
\fIemultihop\fR\& - Multihop attempted
.LP
.TP 2
*
\fIenametoolong\fR\& - Filename too long
.LP
.TP 2
*
\fIenavail\fR\& - Unavailable
.LP
.TP 2
*
\fIenet\fR\& - ENET
.LP
.TP 2
*
\fIenetdown\fR\& - Network is down
.LP
.TP 2
*
\fIenetreset\fR\& - Network dropped connection on reset
.LP
.TP 2
*
\fIenetunreach\fR\& - Network is unreachable
.LP
.TP 2
*
\fIenfile\fR\& - File table overflow
.LP
.TP 2
*
\fIenoano\fR\& - Anode table overflow
.LP
.TP 2
*
\fIenobufs\fR\& - No buffer space available
.LP
.TP 2
*
\fIenocsi\fR\& - No CSI structure available
.LP
.TP 2
*
\fIenodata\fR\& - No data available
.LP
.TP 2
*
\fIenodev\fR\& - No such device
.LP
.TP 2
*
\fIenoent\fR\& - No such file or directory
.LP
.TP 2
*
\fIenoexec\fR\& - Exec format error
.LP
.TP 2
*
\fIenolck\fR\& - No locks available
.LP
.TP 2
*
\fIenolink\fR\& - Link has been severed
.LP
.TP 2
*
\fIenomem\fR\& - Not enough memory
.LP
.TP 2
*
\fIenomsg\fR\& - No message of desired type
.LP
.TP 2
*
\fIenonet\fR\& - Machine is not on the network
.LP
.TP 2
*
\fIenopkg\fR\& - Package not installed
.LP
.TP 2
*
\fIenoprotoopt\fR\& - Bad protocol option
.LP
.TP 2
*
\fIenospc\fR\& - No space left on device
.LP
.TP 2
*
\fIenosr\fR\& - Out of stream resources or not a stream device
.LP
.TP 2
*
\fIenosym\fR\& - Unresolved symbol name
.LP
.TP 2
*
\fIenosys\fR\& - Function not implemented
.LP
.TP 2
*
\fIenotblk\fR\& - Block device required
.LP
.TP 2
*
\fIenotconn\fR\& - Socket is not connected
.LP
.TP 2
*
\fIenotdir\fR\& - Not a directory
.LP
.TP 2
*
\fIenotempty\fR\& - Directory not empty
.LP
.TP 2
*
\fIenotnam\fR\& - Not a named file
.LP
.TP 2
*
\fIenotsock\fR\& - Socket operation on non-socket
.LP
.TP 2
*
\fIenotsup\fR\& - Operation not supported
.LP
.TP 2
*
\fIenotty\fR\& - Inappropriate device for \fIioctl\fR\&
.LP
.TP 2
*
\fIenotuniq\fR\& - Name not unique on network
.LP
.TP 2
*
\fIenxio\fR\& - No such device or address
.LP
.TP 2
*
\fIeopnotsupp\fR\& - Operation not supported on socket
.LP
.TP 2
*
\fIeperm\fR\& - Not owner
.LP
.TP 2
*
\fIepfnosupport\fR\& - Protocol family not supported
.LP
.TP 2
*
\fIepipe\fR\& - Broken pipe
.LP
.TP 2
*
\fIeproclim\fR\& - Too many processes
.LP
.TP 2
*
\fIeprocunavail\fR\& - Bad procedure for program
.LP
.TP 2
*
\fIeprogmismatch\fR\& - Wrong program version
.LP
.TP 2
*
\fIeprogunavail\fR\& - RPC program unavailable
.LP
.TP 2
*
\fIeproto\fR\& - Protocol error
.LP
.TP 2
*
\fIeprotonosupport\fR\& - Protocol not supported
.LP
.TP 2
*
\fIeprototype\fR\& - Wrong protocol type for socket
.LP
.TP 2
*
\fIerange\fR\& - Math result unrepresentable
.LP
.TP 2
*
\fIerefused\fR\& - EREFUSED
.LP
.TP 2
*
\fIeremchg\fR\& - Remote address changed
.LP
.TP 2
*
\fIeremdev\fR\& - Remote device
.LP
.TP 2
*
\fIeremote\fR\& - Pathname hit remote filesystem
.LP
.TP 2
*
\fIeremoteio\fR\& - Remote I/O error
.LP
.TP 2
*
\fIeremoterelease\fR\& - EREMOTERELEASE
.LP
.TP 2
*
\fIerofs\fR\& - Read-only filesystem
.LP
.TP 2
*
\fIerpcmismatch\fR\& - Wrong RPC version
.LP
.TP 2
*
\fIerremote\fR\& - Object is remote
.LP
.TP 2
*
\fIeshutdown\fR\& - Cannot send after socket shutdown
.LP
.TP 2
*
\fIesocktnosupport\fR\& - Socket type not supported
.LP
.TP 2
*
\fIespipe\fR\& - Invalid seek
.LP
.TP 2
*
\fIesrch\fR\& - No such process
.LP
.TP 2
*
\fIesrmnt\fR\& - Srmount error
.LP
.TP 2
*
\fIestale\fR\& - Stale remote file handle
.LP
.TP 2
*
\fIesuccess\fR\& - Error 0
.LP
.TP 2
*
\fIetime\fR\& - Timer expired
.LP
.TP 2
*
\fIetimedout\fR\& - Connection timed out
.LP
.TP 2
*
\fIetoomanyrefs\fR\& - Too many references
.LP
.TP 2
*
\fIetxtbsy\fR\& - Text file or pseudo-device busy
.LP
.TP 2
*
\fIeuclean\fR\& - Structure needs cleaning
.LP
.TP 2
*
\fIeunatch\fR\& - Protocol driver not attached
.LP
.TP 2
*
\fIeusers\fR\& - Too many users
.LP
.TP 2
*
\fIeversion\fR\& - Version mismatch
.LP
.TP 2
*
\fIewouldblock\fR\& - Operation would block
.LP
.TP 2
*
\fIexdev\fR\& - Cross-domain link
.LP
.TP 2
*
\fIexfull\fR\& - Message tables full
.LP
.TP 2
*
\fInxdomain\fR\& - Hostname or domain name cannot be found
.LP
.RE