Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       inet - Access to TCP/IP Protocols

DESCRIPTION

       Provides access to TCP/IP protocols.

       See also ERTS User's Guide, Inet configuration for more information on how to configure an
       Erlang runtime system for IP communication.

       Two Kernel configuration parameters affect the behaviour  of  all  sockets  opened  on  an
       Erlang  node:  inet_default_connect_options can contain a list of default options used for
       all sockets returned when doing connect, and  inet_default_listen_options  can  contain  a
       list of default options used when issuing a listen call. When accept is issued, the values
       of the listensocket options are inherited, why no such application variable is needed  for
       accept.

       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
       {delay_send,true}  might  be  specified in this way. An example of starting an Erlang node
       with all sockets using delayed send could look like this:

       $ erl -sname test -kernel \
       inet_default_connect_options '[{delay_send,true}]' \
       inet_default_listen_options '[{delay_send,true}]'

       Note that the default option {active, true} currently  cannot  be  changed,  for  internal
       reasons.

       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   gethostbyaddr/1   either   as   the   string
       "150.236.20.73" or as the tuple {150, 236, 20, 73}.

       IPv4 address examples:

       Address          ip_address()
       -------          ------------
       127.0.0.1        {127,0,0,1}
       192.168.42.2     {192,168,42,2}

       IPv6 address examples:

       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}

       A function that may be useful is parse_address/1:

       1> inet:parse_address("192.168.42.2").
       {ok,{192,168,42,2}}
       2> inet:parse_address("FFFF::192.168.42.2").
       {ok,{65535,0,0,0,0,0,49320,10754}}

DATA TYPES

       hostent() =
           #hostent{h_name = undefined | inet:hostname(),
                    h_aliases = [inet:hostname()],
                    h_addrtype = undefined | inet | inet6,
                    h_length = undefined | integer() >= 0,
                    h_addr_list = [inet:ip_address()]}

              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() = ip4_address() | ip6_address()

       ip4_address() = {0..255, 0..255, 0..255, 0..255}

       ip6_address() =
           {0..65535,
            0..65535,
            0..65535,
            0..65535,
            0..65535,
            0..65535,
            0..65535,
            0..65535}

       port_number() = 0..65535

       posix() = exbadport | exbadseq | file:posix()

              An atom which is named from the Posix error codes used in Unix, and in the  runtime
              libraries of most C compilers. See POSIX Error Codes.

       socket()

              See gen_tcp(3erl) and gen_udp(3erl).

       address_family() = inet | inet6

EXPORTS

       close(Socket) -> ok

              Types:

                 Socket = socket()

              Closes a socket of any type.

       get_rc() -> [{Par :: any(), Val :: any()}]

              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.

       format_error(Reason) -> string()

              Types:

                 Reason = posix() | system_limit

              Returns  a diagnostic error string. See the section below for possible Posix values
              and the corresponding strings.

       getaddr(Host, Family) -> {ok, Address} | {error, posix()}

              Types:

                 Host = ip_address() | hostname()
                 Family = address_family()
                 Address = ip_address()

              Returns the IP-address for Host as a tuple of integers. Host can be an  IP-address,
              a single hostname or a fully qualified hostname.

       getaddrs(Host, Family) -> {ok, Addresses} | {error, posix()}

              Types:

                 Host = ip_address() | hostname()
                 Family = address_family()
                 Addresses = [ip_address()]

              Returns  a  list  of all IP-addresses for Host. Host can be an IP-address, a single
              hostname or a fully qualified hostname.

       gethostbyaddr(Address) -> {ok, Hostent} | {error, posix()}

              Types:

                 Address = string() | ip_address()
                 Hostent = hostent()

              Returns a hostent record given an address.

       gethostbyname(Hostname) -> {ok, Hostent} | {error, posix()}

              Types:

                 Hostname = hostname()
                 Hostent = hostent()

              Returns a hostent record given a hostname.

       gethostbyname(Hostname, Family) ->
                        {ok, Hostent} | {error, posix()}

              Types:

                 Hostname = hostname()
                 Family = address_family()
                 Hostent = hostent()

              Returns a hostent record given a hostname, restricted to the given address family.

       gethostname() -> {ok, Hostname}

              Types:

                 Hostname = string()

              Returns the local hostname. Will never fail.

       getifaddrs() -> {ok, Iflist} | {error, posix()}

              Types:

                 Iflist = [{Ifname, [Ifopt]}]
                 Ifname = string()
                 Ifopt = {flag, [Flag]}
                       | {addr, Addr}
                       | {netmask, Netmask}
                       | {broadaddr, Broadaddr}
                       | {dstaddr, Dstaddr}
                       | {hwaddr, Hwaddr}
                 Flag = up
                      | broadcast
                      | loopback
                      | pointtopoint
                      | running
                      | multicast
                 Addr = Netmask = Broadaddr = Dstaddr = ip_address()
                 Hwaddr = [byte()]

              Returns  a  list  of  2-tuples  containing  interface  names  and  the  interface's
              addresses.  Ifname  is  a  Unicode  string.  Hwaddr  is  hardware dependent, e.g on
              Ethernet interfaces  it  is  the  6-byte  Ethernet  address  (MAC  address  (EUI-48
              address)).

              The  {addr,Addr},  {netmask,_}  and {broadaddr,_} tuples are repeated in the result
              list iff the interface has multiple addresses. If you come across an interface that
              has  multiple  {flag,_} or {hwaddr,_} tuples you have a really strange interface or
              possibly a bug in this  function.  The  {flag,_}  tuple  is  mandatory,  all  other
              optional.

              Do  not  rely  too  much on the order of Flag atoms or Ifopt tuples. There are some
              rules, though:

                *
                   Immediately after {addr,_} follows {netmask,_}

                *
                   Immediately thereafter follows {broadaddr,_} if the broadcast flag is not  set
                  and the pointtopoint flag is set.

                *
                   Any  {netmask,_},  {broadaddr,_} or {dstaddr,_} tuples that follow an {addr,_}
                  tuple concerns that address.

              The {hwaddr,_} tuple  is  not  returned  on  Solaris  since  the  hardware  address
              historically  belongs  to  the  link  layer  and  only  the superuser can read such
              addresses.

              On Windows, the data is fetched from quite  different  OS  API  functions,  so  the
              Netmask  and Broadaddr values may be calculated, just as some Flag values. You have
              been warned. Report flagrant bugs.

       getopts(Socket, Options) -> {ok, OptionValues} | {error, posix()}

              Types:

                 Socket = socket()
                 Options = [socket_getopt()]
                 OptionValues = [socket_setopt()]
                 socket_getopt() = gen_sctp:option_name()
                                 | gen_tcp:option_name()
                                 | gen_udp:option_name()
                 socket_setopt() = gen_sctp:option()
                                 | gen_tcp:option()
                                 | gen_udp:option()

              Gets one or more options for a socket.  See  setopts/2  for  a  list  of  available
              options.

              The  number  of  elements  in  the  returned OptionValues 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.

              A raw option request RawOptReq = {raw, Protocol, OptionNum, ValueSpec} 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.

              The  RawOptReq  consists  of the tag raw 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 getsockopt
              requires input 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 RawOptReq correspond to the second, third  and  fourth/fifth  parameters  to  the
              getsockopt  call in the C socket API. The value stored in the buffer is returned as
              a binary ValueBin where all values are coded in the native endianess.

              Asking for and inspecting raw socket options require low  level  information  about
              the current operating system and TCP stack.

              As  an example, consider a Linux machine where the TCP_INFO option could be used to
              collect TCP statistics for a socket. Lets say we're interested in  the  tcpi_sacked
              field  of  the  struct  tcp_info  filled in when asking for TCP_INFO. To be able to
              access this information, we need to know both the numeric  value  of  the  protocol
              level IPPROTO_TCP, the numeric value of the option TCP_INFO, the size of the struct
              tcp_info and the size and offset of the specific field. By inspecting  the  headers
              or  writing a small C program, we found IPPROTO_TCP to be 6, TCP_INFO to be 11, the
              structure size to be 92 (bytes), the offset of tcpi_sacked to be 28 bytes  and  the
              actual  value  to  be a 32 bit integer. We could use the following code to retrieve
              the value:

                      get_tcpi_sacked(Sock) ->
                          {ok,[{raw,_,_,Info}]} = inet:getopts(Sock,[{raw,6,11,92}]),
                          <<_:28/binary,TcpiSacked:32/native,_/binary>> = Info,
                          TcpiSacked.

              Preferably, you would check the machine type, the OS and the kernel  version  prior
              to executing anything similar to the code above.

       getstat(Socket) -> {ok, OptionValues} | {error, posix()}

       getstat(Socket, Options) -> {ok, OptionValues} | {error, posix()}

              Types:

                 Socket = socket()
                 Options = [stat_option()]
                 OptionValues = [{stat_option(), integer()}]
                 stat_option() = recv_cnt
                               | recv_max
                               | recv_avg
                               | recv_oct
                               | recv_dvi
                               | send_cnt
                               | send_max
                               | send_avg
                               | send_oct
                               | send_pend

              Gets one or more statistic options for a socket.

              getstat(Socket)  is  equivalent  to  getstat(Socket, [recv_avg, recv_cnt, recv_dvi,
              recv_max, recv_oct, send_avg, send_cnt, send_dvi, send_max, send_oct]).

              The following options are available:

                recv_avg:
                  Average size of packets in bytes received to the socket.

                recv_cnt:
                  Number of packets received to the socket.

                recv_dvi:
                  Average packet size deviation in bytes received to the socket.

                recv_max:
                  The size of the largest packet in bytes received to the socket.

                recv_oct:
                  Number of bytes received to the socket.

                send_avg:
                  Average size of packets in bytes sent from the socket.

                send_cnt:
                  Number of packets sent from the socket.

                send_dvi:
                  Average packet size deviation in bytes received sent from the socket.

                send_max:
                  The size of the largest packet in bytes sent from the socket.

                send_oct:
                  Number of bytes sent from the socket.

       ntoa(IpAddress) -> {ok, Address} | {error, einval}

              Types:

                 Address = string()
                 IpAddress = ip_address()

              Parses an ip_address() and returns an IPv4 or IPv6 address string.

       parse_ipv4_address(Address) -> {ok, IPv4Address} | {error, einval}

              Types:

                 Address = string()
                 IPv4Address = ip_address()

              Parses an IPv4 address string and returns an  ip4_address().  Accepts  a  shortened
              IPv4 shortened address string.

       parse_ipv4strict_address(Address) ->
                                   {ok, IPv4Address} | {error, einval}

              Types:

                 Address = string()
                 IPv4Address = ip_address()

              Parses  an  IPv4  address  string  containing  four fields, i.e not  shortened, and
              returns an ip4_address().

       parse_ipv6_address(Address) -> {ok, IPv6Address} | {error, einval}

              Types:

                 Address = string()
                 IPv6Address = ip_address()

              Parses an IPv6 address string and returns an  ip6_address().  If  an  IPv4  address
              string is passed, an IPv4-mapped IPv6 address is returned.

       parse_ipv6strict_address(Address) ->
                                   {ok, IPv6Address} | {error, einval}

              Types:

                 Address = string()
                 IPv6Address = ip_address()

              Parses  an  IPv6 address string and returns an ip6_address(). Does not  accept IPv4
              adresses.

       parse_address(Address) -> {ok, IPAddress} | {error, einval}

              Types:

                 Address = string()
                 IPAddress = ip_address()

              Parses  an  IPv4  or  IPv6  address  string  and  returns   an   ip4_address()   or
              ip6_address(). Accepts a shortened IPv4 address string.

       parse_strict_address(Address) -> {ok, IPAddress} | {error, einval}

              Types:

                 Address = string()
                 IPAddress = ip_address()

              Parses   an   IPv4   or  IPv6  address  string  and  returns  an  ip4_address()  or
              ip6_address(). Does not  accept a shortened IPv4 address string.

       peername(Socket) -> {ok, {Address, Port}} | {error, posix()}

              Types:

                 Socket = socket()
                 Address = ip_address()
                 Port = integer() >= 0

              Returns the address and port for the other end of a connection.

              Note that for SCTP sockets this function only returns  one  of  the  socket's  peer
              addresses. The function peernames/1,2 returns all.

       peernames(Socket) -> {ok, [{Address, Port}]} | {error, posix()}

              Types:

                 Socket = socket()
                 Address = ip_address()
                 Port = integer() >= 0

              Equivalent to peernames(Socket, 0). Note that this function's behaviour for an SCTP
              one-to-many style socket is not defined by the SCTP Sockets API Extensions.

       peernames(Socket, Assoc) ->
                    {ok, [{Address, Port}]} | {error, posix()}

              Types:

                 Socket = socket()
                 Assoc = #sctp_assoc_change{} | gen_sctp:assoc_id()
                 Address = ip_address()
                 Port = integer() >= 0

              Returns a list of all address/port number pairs for the other  end  of  a  socket's
              association Assoc.

              This  function  can  return  multiple addresses for multihomed sockets such as SCTP
              sockets. For other sockets it returns a one element list.

              Note that the Assoc parameter is by the SCTP Sockets API Extensions defined  to  be
              ignored  for  one-to-one  style  sockets.  What the special value 0 means hence its
              behaviour for one-to-many style sockets is unfortunately not defined.

       port(Socket) -> {ok, Port} | {error, any()}

              Types:

                 Socket = socket()
                 Port = port_number()

              Returns the local port number for a socket.

       sockname(Socket) -> {ok, {Address, Port}} | {error, posix()}

              Types:

                 Socket = socket()
                 Address = ip_address()
                 Port = integer() >= 0

              Returns the local address and port number for a socket.

              Note that for SCTP sockets this function only returns one of the socket  addresses.
              The function socknames/1,2 returns all.

       socknames(Socket) -> {ok, [{Address, Port}]} | {error, posix()}

              Types:

                 Socket = socket()
                 Address = ip_address()
                 Port = integer() >= 0

              Equivalent to socknames(Socket, 0).

       socknames(Socket, Assoc) ->
                    {ok, [{Address, Port}]} | {error, posix()}

              Types:

                 Socket = socket()
                 Assoc = #sctp_assoc_change{} | gen_sctp:assoc_id()
                 Address = ip_address()
                 Port = integer() >= 0

              Returns  a  list  of all local address/port number pairs for a socket for the given
              association Assoc.

              This function can return multiple addresses for multihomed  sockets  such  as  SCTP
              sockets. For other sockets it returns a one element list.

              Note  that  the Assoc parameter 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  0  is defined to mean that the returned addresses shall be without regard to
              any particular association. How  different  SCTP  implementations  interprets  this
              varies somewhat.

       setopts(Socket, Options) -> ok | {error, posix()}

              Types:

                 Socket = socket()
                 Options = [socket_setopt()]
                 socket_setopt() = gen_sctp:option()
                                 | gen_tcp:option()
                                 | gen_udp:option()

              Sets one or more options for a socket. The following options are available:

                {active, true | false | once}:
                  If the value is true, which is the default, everything received from the socket
                  will be sent as messages to the  receiving  process.  If  the  value  is  false
                  (passive  mode),  the  process must explicitly receive incoming data by calling
                  gen_tcp:recv/2,3 or gen_udp:recv/2,3 (depending on the type of socket).

                  If the value is once ({active, once}), one data message from the socket will be
                  sent  to  the  process.  To  receive one more message, setopts/2 must be called
                  again with the {active, once} option.

                  When using {active, once}, the socket changes behaviour automatically when data
                  is  received.  This  can  sometimes be confusing in combination with connection
                  oriented sockets (i.e. gen_tcp) as a  socket  with  {active,  false}  behaviour
                  reports  closing  differently  than  a socket with {active, true} behaviour. To
                  make programming easier, a socket where the peer closed and this  was  detected
                  while   in   {active,   false}   mode,   will   still   generate   the  message
                  {tcp_closed,Socket} when set to {active, once} or {active, true}  mode.  It  is
                  therefore  safe  to  assume  that  the  message  {tcp_closed,Socket},  possibly
                  followed by socket port termination (depending  on  the  exit_on_close  option)
                  will  eventually  appear  when a socket changes back and forth between {active,
                  true} and {active, false} mode. However, when peer closing is detected  is  all
                  up to the underlying TCP/IP stack and protocol.

                  Note  that  {active,true}  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.
                  {active,false}  mode  or  use of the {active, once} mode provides flow control;
                  the other side will not be able send faster than the receiver can read.

                {broadcast, Boolean}(UDP sockets):
                  Enable/disable permission to send broadcasts.

                {buffer, Size}:
                  Determines the size of the user-level software buffer used by the  driver.  Not
                  to  be  confused  with sndbuf and recbuf options which correspond to the kernel
                  socket   buffers.    It    is    recommended    to    have    val(buffer)    >=
                  max(val(sndbuf),val(recbuf)).  In fact, the val(buffer) is automatically set to
                  the above maximum when sndbuf or recbuf values are set.

                {delay_send, Boolean}:
                  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 {delay_send, true} will make all 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 false.

                {deliver, port | term}:
                  When  {active,  true}  delivers data on the forms port : {S, {data, [H1,..Hsz |
                  Data]}} or term : {tcp, S, [H1..Hsz | Data]}.

                {dontroute, Boolean}:
                  Enable/disable routing bypass for outgoing messages.

                {exit_on_close, Boolean}:
                  By default this option is set to true.

                  The only reason to set it to false is if you want to continue sending  data  to
                  the  socket  after a close has been detected, for instance if the peer has used
                  gen_tcp:shutdown/2 to shutdown the write side.

                {header, Size}:
                  This option is only meaningful if the binary  option  was  specified  when  the
                  socket  was  created.  If the header option is specified, the first Size 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
                  Size == 2, the data received will match [Byte1,Byte2|Binary].

                {high_msgq_watermark, Size}:
                  The socket message queue will be set into a busy state when the amount of  data
                  queued  on  the  message  queue  reaches  this limit. Note that this limit only
                  concerns  data  that  have  not  yet   reached   the   ERTS   internal   socket
                  implementation. Default value used is 8 kB.

                  Senders  of  data  to the socket will be suspended if either the socket message
                  queue is busy, or the socket itself is busy.

                  For  more  information  see   the   low_msgq_watermark,   high_watermark,   and
                  low_watermark options.

                  Note  that distribution sockets will disable the use of high_msgq_watermark and
                  low_msgq_watermark, and will instead use the  distribution  buffer  busy  limit
                  which is a similar feature.

                {high_watermark, Size} (TCP/IP sockets):
                  The  socket  will  be  set  into  a  busy  state when the amount of data queued
                  internally by the ERTS socket implementation reaches this limit. Default  value
                  used is 8 kB.

                  Senders  of  data  to the socket will be suspended if either the socket message
                  queue is busy, or the socket itself is busy.

                  For  more  information  see   the   low_watermark,   high_msgq_watermark,   and
                  low_msqg_watermark options.

                {ipv6_v6only, Boolean}:
                  Restricts  the  socket to only use IPv6, prohibiting any IPv4 connections. This
                  is only applicable for IPv6 sockets (option inet6).

                  On most platforms this option has to be set on the socket before associating it
                  to  an  address.  Therefore  it is only reasonable to give it when creating the
                  socket and not to use it when calling the function (setopts/2) containing  this
                  description.

                  The  behaviour  of a socket with this socket option set to true is becoming the
                  only portable one. The original idea when IPv6 was new of using  IPv6  for  all
                  traffic  is  now not recommended by FreeBSD (you can use {ipv6_v6only,false} to
                  override the recommended system  default  value),  forbidden  by  OpenBSD  (the
                  supported GENERIC kernel) and impossible on Windows (that has separate IPv4 and
                  IPv6 protocol stacks). Most Linux distros still have a system default value  of
                  false.  This  policy shift among operating systems towards separating IPv6 from
                  IPv4 traffic has evolved since it gradually proved hard and complicated to  get
                  a dual stack implementation correct and secure.

                  On  some platforms the only allowed value for this option is true, e.g. OpenBSD
                  and Windows. Trying to set this option to false when creating the  socket  will
                  in this case fail.

                  Setting this option on platforms where it does not exist is ignored and getting
                  this option with getopts/2 returns no value i.e  the  returned  list  will  not
                  contain an {ipv6_v6only,_} tuple. On Windows the option acually does not exist,
                  but it is emulated as being a read-only option with the value true.

                  So it boils down to that setting this option to true  when  creating  a  socket
                  will  never  fail  except  possibly (at the time of this writing) on a platform
                  where you have customized the kernel to only allow false, which might be doable
                  (but weird) on e.g. OpenBSD.

                  If  you  read back the option value using getopts/2 and get no value the option
                  does not exist in the host OS and all bets are off regarding the  behaviour  of
                  both  an  IPv6  and an IPv4 socket listening on the same port as well as for an
                  IPv6 socket getting IPv4 traffic.

                {keepalive, Boolean}(TCP/IP sockets):
                  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.

                {linger, {true|false, Seconds}}:
                  Determines  the  timeout  in  seconds  for  flushing unsent data in the close/1
                  socket call. If the 1st component of the value tuple is false, the 2nd  one  is
                  ignored,  which  means that close/1 returns immediately not waiting for data to
                  be flushed. Otherwise, the 2nd component is the flushing time-out in seconds.

                {low_msgq_watermark, Size}:
                  If the socket message queue is in a busy state, the socket message  queue  will
                  be  set in a not busy state when the amount of data queued in the message queue
                  falls below this limit. Note that this limit only concerns data that  have  not
                  yet  reached  the  ERTS internal socket implementation. Default value used is 4
                  kB.

                  Senders that have been suspended due to either a busy message queue or  a  busy
                  socket,  will  be resumed when neither the socket message queue, nor the socket
                  are busy.

                  For  more  information  see  the   high_msgq_watermark,   high_watermark,   and
                  low_watermark options.

                  Note  that distribution sockets will disable the use of high_msgq_watermark and
                  low_msgq_watermark, and will instead use the  distribution  buffer  busy  limit
                  which is a similar feature.

                {low_watermark, Size} (TCP/IP sockets):
                  If  the  socket  is in a busy state, the socket will be set in a not busy state
                  when the amount of data queued internally by  the  ERTS  socket  implementation
                  falls below this limit. Default value used is 4 kB.

                  Senders  that  have been suspended due to either a busy message queue or a busy
                  socket, will be resumed when neither the socket message queue, nor  the  socket
                  are busy.

                  For   more   information   see  the  high_watermark,  high_msgq_watermark,  and
                  low_msgq_watermark options.

                {mode, Mode :: binary | list}:
                  Received Packet is delivered as defined by Mode.

                {netns, Namespace :: file:filename_all()}:
                  Set a network namespace for the socket. The Namespace parameter is  a  filename
                  defining  the  namespace for example "/var/run/netns/example" typically created
                  by the command ip netns add example. This option must be  used  in  a  function
                  call   that  creates  a  socket  i.e   gen_tcp:connect/3,4,   gen_tcp:listen/2,
                  gen_udp:open/1,2 or  gen_sctp:open/0-2.

                  This option uses the Linux specific syscall setns() such as in Linux kernel 3.0
                  or  later  and  therefore only exists when the runtime system has been compiled
                  for such an operating system.

                  The virtual machine also needs elevated privileges either running as  superuser
                  or   (for   Linux)   having  the  capability  CAP_SYS_ADMIN  according  to  the
                  documentation for setns(2). However, during  testing  also  CAP_SYS_PTRACE  and
                  CAP_DAC_READ_SEARCH has proven to be necessary. Example:

                  setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp

                  The  Namespace  is  a file name and is encoded and decoded as discussed in file
                  except that the emulator flag +fnu is ignored and  getopts/2  for  this  option
                  will  return  a  binary  for  the  filename  if  the stored filename can not be
                  decoded, which should only happen if you set the option using a binary that can
                  not     be     decoded     with     the     emulator's    filename    encoding:
                  file:native_name_encoding/0.

                list:
                  Received Packet is delivered as a list.

                binary:
                  Received Packet is delivered as a binary.

                {nodelay, Boolean}(TCP/IP sockets):
                  If Boolean == true, the TCP_NODELAY option is turned on for the  socket,  which
                  means that even small amounts of data will be sent immediately.

                {packet, PacketType}(TCP/IP sockets):
                  Defines  the  type  of  packets  to  use for a socket. The following values are
                  valid:

                  raw | 0:
                    No packaging is done.

                  1 | 2 | 4:
                    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.

                    In current implementation the 4-byte header is limited to 2Gb.

                  asn1 | cdr | sunrm | fcgi | tpkt | line:
                    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
                    gen_tcp:recv/2,3 returns one complete packet. The header is not stripped off.

                    The meanings of the packet types are as follows:
                    asn1 - ASN.1 BER,
                    sunrm - Sun's RPC encoding,
                    cdr - CORBA (GIOP 1.1),
                    fcgi - Fast CGI,
                    tpkt - TPKT format [RFC1006],
                    line - Line mode, a packet is a line terminated with  newline,  lines  longer
                    than the receive buffer are truncated.

                  http | http_bin:
                    The  Hypertext  Transfer  Protocol.  The packets are returned with the format
                    according to HttpPacket described in   erlang:decode_packet/3.  A  socket  in
                    passive  mode  will return {ok, HttpPacket} from gen_tcp:recv while an active
                    socket will send messages like {http, Socket, HttpPacket}.

                  httph | httph_bin:
                    These two types are often not needed as the socket will automatically  switch
                    from  http/http_bin  to  httph/httph_bin  internally after the first line has
                    been read. There might be occasions however when they  are  useful,  such  as
                    parsing trailers from chunked encoding.

                {packet_size, Integer}(TCP/IP sockets):
                  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.

                  For line oriented protocols (line,http*), option  packet_size  also  guarantees
                  that  lines  up to the indicated length are accepted and not considered invalid
                  due to internal buffer limitations.

                {priority, Priority}:
                  Set the protocol-defined priority for all packets to be sent on this socket.

                {raw, Protocol, OptionNum, ValueBin}:
                  See below.

                {read_packets, Integer}(UDP sockets):
                  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.

                {recbuf, Size}:
                  Gives the size of the receive buffer to use for the socket.

                {reuseaddr, Boolean}:
                  Allows or  disallows  local  reuse  of  port  numbers.  By  default,  reuse  is
                  disallowed.

                {send_timeout, Integer}:
                  Only allowed for connection oriented sockets.

                  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 {error,timeout}. How much of a packet that actually got sent is unknown,
                  why  the  socket  should  be  closed  whenever  a  timeout  has  occurred  (see
                  send_timeout_close). Default is infinity.

                {send_timeout_close, Boolean}:
                  Only allowed for connection oriented sockets.

                  Used  together  with  send_timeout  to  specify  whether  the  socket  will  be
                  automatically closed when  the  send  operation  returns  {error,timeout}.  The
                  recommended  setting is true which will automatically close the socket. Default
                  is false due to backward compatibility.

                {sndbuf, Size}:
                  Gives the size of the send buffer to use for the socket.

                {priority, Integer}:
                  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.

                {tos, Integer}:
                  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.

              In  addition to the options mentioned above, raw option specifications can be used.
              The raw options are specified as a tuple of arity four, beginning with the tag raw,
              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  setsockopt 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.

              Using  raw  socket  options  require detailed knowledge about the current operating
              system and TCP stack.

              As an example of the usage of raw options, consider a Linux system where  you  want
              to  set  the TCP_LINGER2 option on the IPPROTO_TCP 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 TCP_LINGER2 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 Sock:

                      inet:setopts(Sock,[{raw,6,8,<<30:32/native>>}]),

              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:

                      {ok,[{raw,6,8,<<TcpLinger2:32/native>>}]}=inet:getopts(Sock,[{raw,6,8,4}]),

              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.

              Note that the default options for TCP/IP sockets can be  changed  with  the  Kernel
              configuration parameters mentioned in the beginning of this document.

POSIX ERROR CODES

         * e2big - argument list too long

         * eacces - permission denied

         * eaddrinuse - address already in use

         * eaddrnotavail - cannot assign requested address

         * eadv - advertise error

         * eafnosupport - address family not supported by protocol family

         * eagain - resource temporarily unavailable

         * ealign - EALIGN

         * ealready - operation already in progress

         * ebade - bad exchange descriptor

         * ebadf - bad file number

         * ebadfd - file descriptor in bad state

         * ebadmsg - not a data message

         * ebadr - bad request descriptor

         * ebadrpc - RPC structure is bad

         * ebadrqc - bad request code

         * ebadslt - invalid slot

         * ebfont - bad font file format

         * ebusy - file busy

         * echild - no children

         * echrng - channel number out of range

         * ecomm - communication error on send

         * econnaborted - software caused connection abort

         * econnrefused - connection refused

         * econnreset - connection reset by peer

         * edeadlk - resource deadlock avoided

         * edeadlock - resource deadlock avoided

         * edestaddrreq - destination address required

         * edirty - mounting a dirty fs w/o force

         * edom - math argument out of range

         * edotdot - cross mount point

         * edquot - disk quota exceeded

         * eduppkg - duplicate package name

         * eexist - file already exists

         * efault - bad address in system call argument

         * efbig - file too large

         * ehostdown - host is down

         * ehostunreach - host is unreachable

         * eidrm - identifier removed

         * einit - initialization error

         * einprogress - operation now in progress

         * eintr - interrupted system call

         * einval - invalid argument

         * eio - I/O error

         * eisconn - socket is already connected

         * eisdir - illegal operation on a directory

         * eisnam - is a named file

         * el2hlt - level 2 halted

         * el2nsync - level 2 not synchronized

         * el3hlt - level 3 halted

         * el3rst - level 3 reset

         * elbin - ELBIN

         * elibacc - cannot access a needed shared library

         * elibbad - accessing a corrupted shared library

         * elibexec - cannot exec a shared library directly

         * elibmax - attempting to link in more shared libraries than system limit

         * elibscn - .lib section in a.out corrupted

         * elnrng - link number out of range

         * eloop - too many levels of symbolic links

         * emfile - too many open files

         * emlink - too many links

         * emsgsize - message too long

         * emultihop - multihop attempted

         * enametoolong - file name too long

         * enavail - not available

         * enet - ENET

         * enetdown - network is down

         * enetreset - network dropped connection on reset

         * enetunreach - network is unreachable

         * enfile - file table overflow

         * enoano - anode table overflow

         * enobufs - no buffer space available

         * enocsi - no CSI structure available

         * enodata - no data available

         * enodev - no such device

         * enoent - no such file or directory

         * enoexec - exec format error

         * enolck - no locks available

         * enolink - link has be severed

         * enomem - not enough memory

         * enomsg - no message of desired type

         * enonet - machine is not on the network

         * enopkg - package not installed

         * enoprotoopt - bad protocol option

         * enospc - no space left on device

         * enosr - out of stream resources or not a stream device

         * enosym - unresolved symbol name

         * enosys - function not implemented

         * enotblk - block device required

         * enotconn - socket is not connected

         * enotdir - not a directory

         * enotempty - directory not empty

         * enotnam - not a named file

         * enotsock - socket operation on non-socket

         * enotsup - operation not supported

         * enotty - inappropriate device for ioctl

         * enotuniq - name not unique on network

         * enxio - no such device or address

         * eopnotsupp - operation not supported on socket

         * eperm - not owner

         * epfnosupport - protocol family not supported

         * epipe - broken pipe

         * eproclim - too many processes

         * eprocunavail - bad procedure for program

         * eprogmismatch - program version wrong

         * eprogunavail - RPC program not available

         * eproto - protocol error

         * eprotonosupport - protocol not supported

         * eprototype - protocol wrong type for socket

         * erange - math result unrepresentable

         * erefused - EREFUSED

         * eremchg - remote address changed

         * eremdev - remote device

         * eremote - pathname hit remote file system

         * eremoteio - remote i/o error

         * eremoterelease - EREMOTERELEASE

         * erofs - read-only file system

         * erpcmismatch - RPC version is wrong

         * erremote - object is remote

         * eshutdown - cannot send after socket shutdown

         * esocktnosupport - socket type not supported

         * espipe - invalid seek

         * esrch - no such process

         * esrmnt - srmount error

         * estale - stale remote file handle

         * esuccess - Error 0

         * etime - timer expired

         * etimedout - connection timed out

         * etoomanyrefs - too many references

         * etxtbsy - text file or pseudo-device busy

         * euclean - structure needs cleaning

         * eunatch - protocol driver not attached

         * eusers - too many users

         * eversion - version mismatch

         * ewouldblock - operation would block

         * exdev - cross-domain link

         * exfull - message tables full

         * nxdomain - the hostname or domain name could not be found