PageRenderTime 49ms CodeModel.GetById 3ms app.highlight 25ms RepoModel.GetById 1ms app.codeStats 1ms

/lib/kernel/doc/src/inet.xml

https://github.com/bsmr-erlang/otp
XML | 1703 lines | 1665 code | 38 blank | 0 comment | 0 complexity | 1f633f9b429f318c3e5a0c8a36e3e7ab MD5 | raw file

Large files files are truncated, but you can click here to view the full file

   1<?xml version="1.0" encoding="utf-8" ?>
   2<!DOCTYPE erlref SYSTEM "erlref.dtd">
   3
   4<erlref>
   5  <header>
   6    <copyright>
   7      <year>1997</year><year>2018</year>
   8      <holder>Ericsson AB. All Rights Reserved.</holder>
   9    </copyright>
  10    <legalnotice>
  11      Licensed under the Apache License, Version 2.0 (the "License");
  12      you may not use this file except in compliance with the License.
  13      You may obtain a copy of the License at
  14
  15          http://www.apache.org/licenses/LICENSE-2.0
  16
  17      Unless required by applicable law or agreed to in writing, software
  18      distributed under the License is distributed on an "AS IS" BASIS,
  19      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  20      See the License for the specific language governing permissions and
  21      limitations under the License.
  22
  23    </legalnotice>
  24
  25    <title>inet</title>
  26    <prepared>bjorn@erix.ericsson.se</prepared>
  27    <docno></docno>
  28    <date>1998-02-04</date>
  29    <rev>A</rev>
  30  </header>
  31  <module since="">inet</module>
  32  <modulesummary>Access to TCP/IP protocols.</modulesummary>
  33  <description>
  34    <p>This module provides access to TCP/IP protocols.</p>
  35    <p>See also
  36      <seealso marker="erts:inet_cfg">ERTS User's Guide:
  37      Inet Configuration</seealso> for more information about how to
  38      configure an Erlang runtime system for IP communication.</p>
  39    <p>The following two Kernel configuration parameters affect the
  40      behavior of all sockets opened on an Erlang node:</p>
  41    <list type="bulleted">
  42      <item><p><c>inet_default_connect_options</c> can contain a list of
  43        default options used for all sockets returned when doing
  44        <c>connect</c>.</p></item>
  45      <item><p><c>inet_default_listen_options</c> can contain a list of
  46        default options used when issuing a <c>listen</c> call.</p></item>
  47    </list>
  48    <p>When <c>accept</c> is issued, the values of the listening socket options
  49      are inherited. No such application variable is therefore needed for
  50      <c>accept</c>.</p>
  51    <p>Using the Kernel configuration parameters above, one
  52      can set default options for all TCP sockets on a node, but use this
  53      with care. Options such as <c>{delay_send,true}</c> can be
  54      specified in this way. The following is an example of starting an Erlang
  55      node with all sockets using delayed send:</p>
  56    <pre>
  57$ <input>erl -sname test -kernel \</input>
  58<input>inet_default_connect_options '[{delay_send,true}]' \</input>
  59<input>inet_default_listen_options '[{delay_send,true}]'</input></pre>
  60    <p>Notice that default option <c>{active, true}</c>
  61      cannot be changed, for internal reasons.</p>
  62    <p>Addresses as inputs to functions can be either a string or a
  63      tuple. For example, the IP address 150.236.20.73 can be passed to
  64      <c>gethostbyaddr/1</c>, either as string <c>"150.236.20.73"</c>
  65      or as tuple <c>{150, 236, 20, 73}</c>.</p>
  66    <p><em>IPv4 address examples:</em></p>
  67    <code type="none">
  68Address          ip_address()
  69-------          ------------
  70127.0.0.1        {127,0,0,1}
  71192.168.42.2     {192,168,42,2}</code>
  72    <p><em>IPv6 address examples:</em></p>
  73    <code type="none">
  74Address          ip_address()
  75-------          ------------
  76::1             {0,0,0,0,0,0,0,1}
  77::192.168.42.2  {0,0,0,0,0,0,(192 bsl 8) bor 168,(42 bsl 8) bor 2}
  78::FFFF:192.168.42.2
  79                {0,0,0,0,0,16#FFFF,(192 bsl 8) bor 168,(42 bsl 8) bor 2}
  803ffe:b80:1f8d:2:204:acff:fe17:bf38
  81                {16#3ffe,16#b80,16#1f8d,16#2,16#204,16#acff,16#fe17,16#bf38}
  82fe80::204:acff:fe17:bf38
  83                {16#fe80,0,0,0,0,16#204,16#acff,16#fe17,16#bf38}</code>
  84    <p>Function
  85      <seealso marker="#parse_address/1"><c>parse_address/1</c></seealso>
  86        can be useful:</p>
  87    <pre>
  881> <input>inet:parse_address("192.168.42.2").</input>
  89{ok,{192,168,42,2}}
  902> <input>inet:parse_address("::FFFF:192.168.42.2").</input>
  91{ok,{0,0,0,0,0,65535,49320,10754}}</pre>
  92  </description>
  93
  94  <datatypes>
  95    <datatype>
  96      <name name="hostent"/>
  97      <desc>
  98        <p>The record is defined in the Kernel include file
  99          <c>"inet.hrl"</c>.</p>
 100        <p>Add the following directive to the module:</p>
 101        <code>
 102-include_lib("kernel/include/inet.hrl").</code>
 103      </desc>
 104    </datatype>
 105    <datatype>
 106      <name name="hostname"/>
 107    </datatype>
 108    <datatype>
 109      <name name="ip_address"/>
 110    </datatype>
 111    <datatype>
 112      <name name="ip4_address"/>
 113    </datatype>
 114    <datatype>
 115      <name name="ip6_address"/>
 116    </datatype>
 117    <datatype>
 118      <name name="port_number"/>
 119    </datatype>
 120    <datatype>
 121      <name name="local_address"/>
 122      <desc>
 123	<p>
 124	  This address family only works on Unix-like systems.
 125	</p>
 126	<p>
 127	  <c><anno>File</anno></c> is normally a file pathname
 128	  in a local filesystem.  It is limited in length by the
 129	  operating system, traditionally to 108 bytes.
 130	</p>
 131	<p>
 132	  A <c>binary()</c> is passed as is to the operating system,
 133	  but a <c>string()</c> is encoded according to the
 134	  <seealso marker="file#native_name_encoding/0">
 135	    system filename encoding mode.
 136	  </seealso>
 137	</p>
 138	<p>
 139	  Other addresses are possible, for example Linux implements
 140	  "Abstract Addresses".  See the documentation for
 141	  Unix Domain Sockets on your system,
 142	  normally <c>unix</c> in manual section 7.
 143	</p>
 144	<p>
 145	  In most API functions where you can use
 146	  this address family the port number must be <c>0</c>.
 147	</p>
 148      </desc>
 149    </datatype>
 150    <datatype>
 151      <name name="socket_address"/>
 152    </datatype>
 153    <datatype>
 154      <name name="socket_getopt"/>
 155    </datatype>
 156    <datatype>
 157      <name name="socket_setopt"/>
 158    </datatype>
 159    <datatype>
 160      <name name="returned_non_ip_address"/>
 161      <desc>
 162	<p>
 163	  Addresses besides
 164	  <seealso marker="#type-ip_address">
 165	    <c>ip_address()</c>
 166	  </seealso>
 167	  ones that are returned from socket API functions.
 168	  See in particular
 169	  <seealso marker="#type-local_address">
 170	    <c>local_address()</c>.
 171	  </seealso>
 172	  The <c>unspec</c> family corresponds to AF_UNSPEC and can
 173	  occur if the other side has no socket address.
 174	  The <c>undefined</c> family can only occur in the unlikely
 175	  event of an address family that the VM does not recognize.
 176	</p>
 177      </desc>
 178    </datatype>
 179    <datatype>
 180      <name name="ancillary_data"/>
 181      <desc>
 182	<p>
 183	  Ancillary data received with the data packet
 184	  or read with the socket option
 185	  <seealso marker="gen_tcp#type-pktoptions_value">
 186	    <c>pktoptions</c>
 187	  </seealso>
 188	  from a TCP socket.
 189	</p>
 190	<p>
 191	  The value(s) correspond to the currently active socket
 192	  <seealso marker="#type-socket_setopt">options</seealso>
 193	  <seealso marker="inet#option-recvtos"><c>recvtos</c></seealso>,
 194	  <seealso marker="inet#option-recvtclass"><c>recvtclass</c></seealso>
 195	  and
 196	  <seealso marker="inet#option-recvttl"><c>recvttl</c></seealso>.
 197	</p>
 198      </desc>
 199    </datatype>
 200    <datatype>
 201      <name name="getifaddrs_ifopts"/>
 202      <desc>
 203	<p>
 204	  Interface address description list returned from
 205	  <seealso marker="#getifaddrs/0"><c>getifaddrs/0,1</c></seealso>
 206	  for a named interface, translated from the returned
 207	  data of the POSIX API function <c>getaddrinfo()</c>.
 208	</p>
 209        <p>
 210	  <c><anno>Hwaddr</anno></c> is hardware dependent,
 211	  for example, on Ethernet interfaces it is
 212	the 6-byte Ethernet address (MAC address (EUI-48 address)).
 213	</p>
 214        <p>
 215	  The tuples <c>{addr,<anno>Addr</anno>}</c>,
 216	  <c>{netmask,<anno>Netmask</anno>}</c>, and possibly
 217	  <c>{broadaddr,<anno>Broadaddr</anno>}</c> or
 218	  <c>{dstaddr,<anno>Dstaddr</anno>}</c>
 219	  are repeated in the list
 220	  if the interface has got multiple addresses.
 221	  An interface may have multiple <c>{flag,_}</c> tuples
 222	  for example if it has different flags
 223	  for different address families.
 224	  Multiple <c>{hwaddr,<anno>Hwaddr</anno>}</c> tuples
 225	  is hard to say anything definite about, though.
 226	  The tuple <c>{flag,<anno>Flags</anno>}</c> is mandatory,
 227	  all others are optional.
 228	</p>
 229        <p>
 230	  Do not rely too much on the order
 231	  of <c><anno>Flags</anno></c> atoms
 232          or the <c><anno>Ifopt</anno></c> tuples.
 233	  There are however some rules:
 234	</p>
 235        <list type="bulleted">
 236	  <item><p>
 237	    A <c>{flag,_}</c> tuple applies to all other tuples that follow.
 238	  </p></item>
 239          <item><p>
 240	    Immediately after <c>{addr,_}</c> follows <c>{netmask,_}</c>.
 241	  </p></item>
 242          <item><p>
 243	    Immediately thereafter may <c>{broadaddr,_}</c> follow
 244	    if <c>broadcast</c> is member of <c><anno>Flags</anno></c>,
 245	    or <c>{dstaddr,_}</c> if <c>pointtopoint</c>
 246	    is member of <c><anno>Flags</anno></c>.
 247	    Both <c>{dstaddr,_}</c> and <c>{broadaddr,_}</c>
 248	    does not occur for the same <c>{addr,_}</c>.
 249	  </p></item>
 250          <item><p>
 251	    Any <c>{netmask,_}</c>, <c>{broadaddr,_}</c>, or
 252            <c>{dstaddr,_}</c> tuples that follow an
 253	    <c>{addr,<anno>Addr</anno>}</c>
 254            tuple concerns the address <c><anno>Addr</anno></c>.
 255	  </p></item>
 256        </list>
 257        <p>
 258	  The tuple <c>{hwaddr,_}</c> is not returned on Solaris, as the
 259          hardware address historically belongs to the link layer
 260	  and it is not returned by the Solaris API function
 261	  <c>getaddrinfo()</c>.
 262	</p>
 263	<warning>
 264	  <p>
 265	    On Windows, the data is fetched from different
 266	    OS API functions, so the <c><anno>Netmask</anno></c>
 267	    and <c><anno>Broadaddr</anno></c> values may be calculated,
 268	    just as some <c><anno>Flags</anno></c> values.
 269	  </p>
 270	</warning>
 271      </desc>
 272    </datatype>
 273    <datatype>
 274      <name name="posix"/>
 275      <desc>
 276        <p>An atom that is named from the POSIX error codes used in Unix,
 277          and in the runtime libraries of most C compilers. See section
 278          <seealso marker="#error_codes">POSIX Error Codes</seealso>.</p>
 279      </desc>
 280    </datatype>
 281    <datatype>
 282      <name>socket()</name>
 283      <desc>
 284        <p>See
 285          <seealso marker="gen_tcp#type-socket"><c>gen_tcp:type-socket</c></seealso>
 286          and
 287          <seealso marker="gen_udp#type-socket"><c>gen_udp:type-socket</c></seealso>.
 288        </p>
 289      </desc>
 290    </datatype>
 291    <datatype>
 292      <name name="address_family"/>
 293    </datatype>
 294    <datatype>
 295      <name name="socket_protocol"/>
 296    </datatype>
 297    <datatype>
 298      <name name="stat_option"/>
 299    </datatype>
 300  </datatypes>
 301
 302  <funcs>
 303    <func>
 304      <name name="close" arity="1" since=""/>
 305      <fsummary>Close a socket of any type.</fsummary>
 306      <desc>
 307        <p>Closes a socket of any type.</p>
 308      </desc>
 309    </func>
 310
 311    <func>
 312      <name name="format_error" arity="1" since=""/>
 313      <fsummary>Return a descriptive string for an error reason.</fsummary>
 314      <desc>
 315        <p>Returns a diagnostic error string. For possible POSIX values and
 316          corresponding strings, see section
 317          <seealso marker="#error_codes">POSIX Error Codes</seealso>.</p>
 318      </desc>
 319    </func>
 320
 321    <func>
 322      <name name="get_rc" arity="0" since=""/>
 323      <fsummary>Return a list of IP configuration parameters.</fsummary>
 324      <desc>
 325        <p>
 326	  Returns the state of the <c>Inet</c> configuration database in
 327          form of a list of recorded configuration parameters. For more
 328          information, see <seealso marker="erts:inet_cfg">ERTS User's Guide:
 329          Inet Configuration</seealso>.
 330	</p>
 331        <p>
 332	  Only actual parameters with other than default values
 333	  are returned, for example not directives that specify
 334	  other sources for configuration parameters nor
 335	  directives that clear parameters.
 336	</p>
 337      </desc>
 338    </func>
 339
 340    <func>
 341      <name name="getaddr" arity="2" since=""/>
 342      <fsummary>Return the IP address for a host.</fsummary>
 343      <desc>
 344        <p>Returns the IP address for <c><anno>Host</anno></c> as a tuple of
 345          integers. <c><anno>Host</anno></c> can be an IP address, a single
 346          hostname, or a fully qualified hostname.</p>
 347      </desc>
 348    </func>
 349
 350    <func>
 351      <name name="getaddrs" arity="2" since=""/>
 352      <fsummary>Return the IP addresses for a host.</fsummary>
 353      <desc>
 354        <p>Returns a list of all IP addresses for <c><anno>Host</anno></c>.
 355          <c><anno>Host</anno></c> can be an IP address, a single hostname, or
 356          a fully qualified hostname.</p>
 357      </desc>
 358    </func>
 359
 360    <func>
 361      <name name="gethostbyaddr" arity="1" since=""/>
 362      <fsummary>Return a hostent record for the host with the specified
 363        address.</fsummary>
 364      <desc>
 365        <p>Returns a <c>hostent</c> record for the host with the specified
 366          address.</p></desc>
 367    </func>
 368
 369    <func>
 370      <name name="gethostbyname" arity="1" since=""/>
 371      <fsummary>Return a hostent record for the host with the specified name.
 372      </fsummary>
 373      <desc>
 374        <p>Returns a <c>hostent</c> record for the host with the specified
 375          hostname.</p>
 376        <p>If resolver option <c>inet6</c> is <c>true</c>,
 377          an IPv6 address is looked up.</p>
 378      </desc>
 379    </func>
 380
 381    <func>
 382      <name name="gethostbyname" arity="2" since=""/>
 383      <fsummary>Return a hostent record for the host with the specified name.
 384      </fsummary>
 385      <desc>
 386        <p>Returns a <c>hostent</c> record for the host with the specified
 387          name, restricted to the specified address family.</p>
 388      </desc>
 389    </func>
 390
 391    <func>
 392      <name name="gethostname" arity="0" since=""/>
 393      <fsummary>Return the local hostname.</fsummary>
 394      <desc>
 395        <p>Returns the local hostname. Never fails.</p>
 396      </desc>
 397    </func>
 398
 399    <func>
 400      <name name="getifaddrs" arity="0" since="OTP R14B01"/>
 401      <fsummary>Return a list of interfaces and their addresses.</fsummary>
 402      <desc>
 403        <p>
 404	  Returns a list of 2-tuples containing interface names and
 405	  the interfaces' addresses. <c><anno>Ifname</anno></c>
 406	  is a Unicode string and
 407	  <c><anno>Ifopts</anno></c> is a list of
 408	  interface address description tuples.
 409	</p>
 410        <p>
 411	  The interface address description tuples
 412	  are documented under the type of the
 413          <seealso marker="#type-getifaddrs_ifopts">
 414	    <c><anno>Ifopts</anno></c>
 415	  </seealso>
 416	  value.
 417	</p>
 418      </desc>
 419    </func>
 420
 421    <func>
 422      <name since="OTP 21.2">getifaddrs(Opts) ->
 423        {ok, [{Ifname, Ifopts}]} | {error, Posix}
 424      </name>
 425      <fsummary>Return a list of interfaces and their addresses.</fsummary>
 426      <type>
 427	<v>
 428	  Opts = [{netns, Namespace}]
 429	</v>
 430	<v>
 431	  Namespace =
 432	  <seealso marker="file#type-filename_all">
 433	    file:filename_all()
 434	  </seealso>
 435	</v>
 436	<v>Ifname = string()</v>
 437	<v>
 438	  Ifopts =
 439	  <seealso marker="#type-getifaddrs_ifopts">
 440	    getifaddrs_ifopts()
 441	  </seealso>
 442	</v>
 443	<v>Posix = <seealso marker="#type-posix">posix()</seealso></v>
 444      </type>
 445      <desc>
 446	<p>
 447	  The same as
 448	  <seealso marker="#getifaddrs/0"><c>getifaddrs/0</c></seealso>
 449	  but the <c>Option</c>
 450	  <c>{netns, Namespace}</c> sets a network namespace
 451	  for the OS call, on platforms that supports that feature.
 452	</p>
 453	<p>
 454	  See the socket option
 455	  <seealso marker="#option-netns">
 456	    <c>{netns, Namespace}</c>
 457	  </seealso>
 458	  under
 459	  <seealso marker="#setopts/2"><c>setopts/2</c></seealso>.
 460	</p>
 461      </desc>
 462    </func>
 463
 464    <func>
 465      <name name="getopts" arity="2" since=""/>
 466      <fsummary>Get one or more options for a socket.</fsummary>
 467      <desc>
 468        <p>Gets one or more options for a socket. For a list of available
 469          options, see
 470          <seealso marker="#setopts/2"><c>setopts/2</c></seealso>.
 471	  See also the description for the type
 472          <seealso marker="gen_tcp#type-pktoptions_value">
 473	    <c>gen_tcp:pktoptions_value()</c>
 474	  </seealso>.</p>
 475        <p>The number of elements in the returned
 476          <c><anno>OptionValues</anno></c>
 477          list does not necessarily correspond to the number of options
 478          asked for. If the operating system fails to support an option,
 479          it is left out in the returned list. An error tuple is returned
 480          only when getting options for the socket is impossible (that is,
 481          the socket is closed or the buffer size in a raw request
 482          is too large). This behavior is kept for backward
 483          compatibility reasons.</p>
 484        <p>A raw option request
 485          <c>RawOptReq = {raw, Protocol, OptionNum, ValueSpec}</c>
 486          can be used to get information about
 487          socket options not (explicitly) supported by the emulator. The
 488          use of raw socket options makes the code non-portable, but
 489          allows the Erlang programmer to take advantage of unusual features
 490          present on a particular platform.</p>
 491        <p><c>RawOptReq</c> consists of tag <c>raw</c> followed
 492          by the protocol level, the option number, and either a binary
 493          or the size, in bytes, of the
 494          buffer in which the option value is to be stored. A binary is to be
 495          used when the underlying <c>getsockopt</c> requires <em>input</em>
 496          in the argument field. In this case, the binary size
 497          is to correspond to the required buffer
 498          size of the return value. The supplied values in a <c>RawOptReq</c>
 499          correspond to the second, third, and fourth/fifth parameters to the
 500          <c>getsockopt</c> call in the C socket API. The value stored
 501          in the buffer is returned as a binary <c>ValueBin</c>,
 502          where all values are coded in the native endianess.</p>
 503        <p>Asking for and inspecting raw socket options require low-level
 504          information about the current operating system and TCP stack.</p>
 505        <p><em>Example:</em></p>
 506        <p>Consider a Linux machine where option
 507          <c>TCP_INFO</c> can be used to collect TCP statistics
 508          for a socket. Assume you are interested in field
 509          <c>tcpi_sacked</c> of <c>struct tcp_info</c>
 510          filled in when asking for <c>TCP_INFO</c>. To be able to access
 511          this information, you need to know the following:</p>
 512        <list type="bulleted">
 513          <item>The numeric value of protocol level <c>IPPROTO_TCP</c></item>
 514          <item>The numeric value of option <c>TCP_INFO</c></item>
 515          <item>The size of <c>struct tcp_info</c></item>
 516          <item>The size and offset of the specific field</item>
 517        </list>
 518        <p>By inspecting the headers or writing a small C program, it is found
 519          that <c>IPPROTO_TCP</c> is 6, <c>TCP_INFO</c> is 11, the structure
 520          size is 92 (bytes), the offset of <c>tcpi_sacked</c> is 28 bytes,
 521          and the value is a 32-bit integer. The following code can be used
 522          to retrieve the value:</p>
 523        <code type="none"><![CDATA[
 524get_tcpi_sacked(Sock) ->
 525    {ok,[{raw,_,_,Info}]} = inet:getopts(Sock,[{raw,6,11,92}]),
 526    <<_:28/binary,TcpiSacked:32/native,_/binary>> = Info,
 527    TcpiSacked.]]></code>
 528        <p>Preferably, you would check the machine type, the operating system,
 529          and the Kernel version before executing anything similar to
 530          this code.</p>
 531      </desc>
 532    </func>
 533
 534    <func>
 535      <name name="getstat" arity="1" since=""/>
 536      <name name="getstat" arity="2" since=""/>
 537      <fsummary>Get one or more statistic options for a socket.</fsummary>
 538      <type name="stat_option"/>
 539      <desc>
 540        <p>Gets one or more statistic options for a socket.</p>
 541        <p><c>getstat(<anno>Socket</anno>)</c> is equivalent to
 542          <c>getstat(<anno>Socket</anno>, [recv_avg, recv_cnt, recv_dvi,
 543          recv_max, recv_oct, send_avg, send_cnt, send_dvi, send_max,
 544          send_oct])</c>.</p>
 545        <p>The following options are available:</p>
 546        <taglist>
 547          <tag><c>recv_avg</c></tag>
 548          <item>
 549            <p>Average size of packets, in bytes, received by the socket.</p>
 550          </item>
 551          <tag><c>recv_cnt</c></tag>
 552          <item>
 553            <p>Number of packets received by the socket.</p>
 554          </item>
 555          <tag><c>recv_dvi</c></tag>
 556          <item>
 557            <p>Average packet size deviation, in bytes, received by the socket.</p>
 558          </item>
 559          <tag><c>recv_max</c></tag>
 560          <item>
 561            <p>Size of the largest packet, in bytes, received by the socket.</p>
 562          </item>
 563          <tag><c>recv_oct</c></tag>
 564          <item>
 565            <p>Number of bytes received by the socket.</p>
 566          </item>
 567          <tag><c>send_avg</c></tag>
 568          <item>
 569            <p>Average size of packets, in bytes, sent from the socket.</p>
 570          </item>
 571          <tag><c>send_cnt</c></tag>
 572          <item>
 573            <p>Number of packets sent from the socket.</p>
 574          </item>
 575          <tag><c>send_dvi</c></tag>
 576          <item>
 577            <p>Average packet size deviation, in bytes, sent from the socket.</p>
 578          </item>
 579          <tag><c>send_max</c></tag>
 580          <item>
 581            <p>Size of the largest packet, in bytes, sent from the socket.</p>
 582          </item>
 583          <tag><c>send_oct</c></tag>
 584          <item>
 585            <p>Number of bytes sent from the socket.</p>
 586          </item>
 587        </taglist>
 588      </desc>
 589    </func>
 590
 591    <func>
 592      <name name="i" arity="0"  since="OTP 21.0"/>
 593      <name name="i" arity="1"  since="OTP 21.0"/>
 594      <name name="i" arity="2"  since="OTP 21.0"/>
 595      <fsummary>Displays information and statistics about sockets on the terminal</fsummary>
 596      <desc>
 597        <p>
 598          Lists all TCP, UDP and SCTP sockets, including those that the Erlang runtime system uses as well as
 599          those created by the application.
 600        </p>
 601        <p>
 602          The following options are available:
 603        </p>
 604
 605        <taglist>
 606          <tag><c>port</c></tag>
 607          <item>
 608            <p>The internal index of the port.</p>
 609          </item>
 610          <tag><c>module</c></tag>
 611          <item>
 612            <p>The callback module of the socket.</p>
 613          </item>
 614          <tag><c>recv</c></tag>
 615          <item>
 616            <p>Number of bytes received by the socket.</p>
 617          </item>
 618          <tag><c>sent</c></tag>
 619          <item>
 620            <p>Number of bytes sent from the socket.</p>
 621          </item>
 622          <tag><c>owner</c></tag>
 623          <item>
 624            <p>The socket owner process.</p>
 625          </item>
 626          <tag><c>local_address</c></tag>
 627          <item>
 628            <p>The local address of the socket.</p>
 629          </item>
 630          <tag><c>foreign_address</c></tag>
 631          <item>
 632            <p>The address and port of the other end of the connection.</p>
 633          </item>
 634          <tag><c>state</c></tag>
 635          <item>
 636            <p>The connection state.</p>
 637          </item>
 638          <tag><c>type</c></tag>
 639          <item>
 640            <p>STREAM or DGRAM or SEQPACKET.</p>
 641          </item>
 642        </taglist>
 643      </desc>
 644    </func>
 645
 646    <func>
 647      <name name="ntoa" arity="1"  since="OTP R16B02"/>
 648      <fsummary>Convert IPv6/IPV4 address to ASCII.</fsummary>
 649      <desc>
 650	<p>Parses an
 651          <seealso marker="#type-ip_address"><c>ip_address()</c></seealso>
 652          and returns an IPv4 or IPv6 address string.</p>
 653      </desc>
 654    </func>
 655
 656    <func>
 657      <name name="parse_address" arity="1"  since="OTP R16B"/>
 658      <fsummary>Parse an IPv4 or IPv6 address.</fsummary>
 659      <desc>
 660	<p>Parses an IPv4 or IPv6 address string and returns an
 661          <seealso marker="#type-ip4_address"><c>ip4_address()</c></seealso> or
 662          <seealso marker="#type-ip6_address"><c>ip6_address()</c></seealso>.
 663          Accepts a shortened IPv4 address string.</p>
 664      </desc>
 665    </func>
 666
 667    <func>
 668      <name name="parse_ipv4_address" arity="1"  since="OTP R16B"/>
 669      <fsummary>Parse an IPv4 address.</fsummary>
 670      <desc>
 671	<p>Parses an IPv4 address string and returns an
 672          <seealso marker="#type-ip4_address"><c>ip4_address()</c></seealso>.
 673	  Accepts a shortened IPv4 address string.</p>
 674      </desc>
 675    </func>
 676
 677    <func>
 678      <name name="parse_ipv4strict_address" arity="1"  since="OTP R16B"/>
 679      <fsummary>Parse an IPv4 address strict.</fsummary>
 680      <desc>
 681	<p>Parses an IPv4 address string containing four fields, that is,
 682          <em>not</em> shortened, and returns an
 683          <seealso marker="#type-ip4_address"><c>ip4_address()</c></seealso>.
 684        </p>
 685      </desc>
 686    </func>
 687
 688    <func>
 689      <name name="parse_ipv6_address" arity="1"  since="OTP R16B"/>
 690      <fsummary>Parse an IPv6 address.</fsummary>
 691      <desc>
 692	<p>Parses an IPv6 address string and returns an
 693          <seealso marker="#type-ip6_address"><c>ip6_address()</c></seealso>.
 694          If an IPv4 address string is specified, an IPv4-mapped IPv6 address
 695          is returned.</p>
 696      </desc>
 697    </func>
 698
 699    <func>
 700      <name name="parse_ipv6strict_address" arity="1"  since="OTP R16B"/>
 701      <fsummary>Parse an IPv6 address strict.</fsummary>
 702      <desc>
 703	<p>Parses an IPv6 address string and returns an
 704          <seealso marker="#type-ip6_address"><c>ip6_address()</c></seealso>.
 705          Does <em>not</em> accept IPv4 addresses.</p>
 706      </desc>
 707    </func>
 708
 709    <func>
 710      <name name="ipv4_mapped_ipv6_address" arity="1"  since="OTP 21.0"/>
 711      <fsummary>Convert to and from IPv4-mapped IPv6 address.</fsummary>
 712      <desc>
 713	<p>
 714	  Convert an IPv4 address to an IPv4-mapped IPv6 address
 715	  or the reverse.  When converting from an IPv6 address
 716	  all but the 2 low words are ignored so this function also
 717	  works on some other types of addresses than IPv4-mapped.
 718	</p>
 719      </desc>
 720    </func>
 721
 722    <func>
 723      <name name="parse_strict_address" arity="1"  since="OTP R16B"/>
 724      <fsummary>Parse an IPv4 or IPv6 address strict.</fsummary>
 725      <desc>
 726	<p>Parses an IPv4 or IPv6 address string and returns an
 727          <seealso marker="#type-ip4_address"><c>ip4_address()</c></seealso> or
 728          <seealso marker="#type-ip6_address"><c>ip6_address()</c></seealso>.
 729          Does <em>not</em> accept a shortened IPv4 address string.</p>
 730      </desc>
 731    </func>
 732
 733    <func>
 734      <name name="peername" arity="1" since=""/>
 735      <fsummary>Return the address and port for the other end of a connection.
 736      </fsummary>
 737      <desc>
 738        <p>Returns the address and port for the other end of a connection.</p>
 739	<p>Notice that for SCTP sockets, this function returns only
 740	  one of the peer addresses of the socket. Function
 741	  <seealso marker="#peernames/1"><c>peernames/1,2</c></seealso>
 742	  returns all.</p>
 743      </desc>
 744    </func>
 745
 746    <func>
 747      <name name="peernames" arity="1" since="OTP R16B03"/>
 748      <fsummary>Return all address/port numbers for the other end of a
 749        connection.</fsummary>
 750      <desc>
 751	<p>Equivalent to
 752	  <seealso marker="#peernames/2"><c>peernames(<anno>Socket</anno>, 0)</c></seealso>.
 753        </p>
 754        <p>Notice that the behavior of this function for an SCTP
 755	  one-to-many style socket is not defined by the
 756	  <url href="http://tools.ietf.org/html/draft-ietf-tsvwg-sctpsocket-13">SCTP Sockets API Extensions</url>.</p>
 757      </desc>
 758    </func>
 759
 760    <func>
 761      <name name="peernames" arity="2" since="OTP R16B03"/>
 762      <fsummary>Return all address/port numbers for the other end of a
 763        connection.</fsummary>
 764      <desc>
 765	<p>Returns a list of all address/port number pairs for the other end
 766	  of an association <c><anno>Assoc</anno></c> of a socket.</p>
 767	<p>This function can return multiple addresses for multihomed
 768	  sockets, such as SCTP sockets. For other sockets it
 769	  returns a one-element list.</p>
 770	<p>Notice that parameter <c><anno>Assoc</anno></c> is by the
 771	  <url href="http://tools.ietf.org/html/draft-ietf-tsvwg-sctpsocket-13">SCTP Sockets API Extensions</url>
 772	  defined to be ignored for
 773	  one-to-one style sockets. What the special value <c>0</c>
 774	  means, hence its behavior for one-to-many style sockets,
 775	  is unfortunately undefined.</p>
 776      </desc>
 777    </func>
 778
 779    <func>
 780      <name name="port" arity="1" since=""/>
 781      <fsummary>Return the local port number for a socket.</fsummary>
 782      <desc>
 783        <p>Returns the local port number for a socket.</p>
 784      </desc>
 785    </func>
 786
 787    <func>
 788      <name name="setopts" arity="2" since=""/>
 789      <fsummary>Set one or more options for a socket.</fsummary>
 790      <desc>
 791        <p>Sets one or more options for a socket.</p>
 792        <p>The following options are available:</p>
 793        <taglist>
 794          <tag><c>{active, true | false | once | N}</c></tag>
 795          <item>
 796            <p>If the value is <c>true</c>, which is the default,
 797              everything received from the socket is sent as
 798              messages to the receiving process.</p>
 799            <p>If the value is <c>false</c> (passive mode), the process must
 800              explicitly receive incoming data by calling
 801              <seealso marker="gen_tcp#recv/2"><c>gen_tcp:recv/2,3</c></seealso>,
 802              <seealso marker="gen_udp#recv/2"><c>gen_udp:recv/2,3</c></seealso>,
 803              or <seealso marker="gen_sctp#recv/1"><c>gen_sctp:recv/1,2</c></seealso>
 804              (depending on the type of socket).</p>
 805            <p>If the value is <c>once</c> (<c>{active, once}</c>),
 806              <em>one</em> data message from the socket is sent
 807              to the process. To receive one more message,
 808              <c>setopts/2</c> must be called again with option
 809              <c>{active, once}</c>.</p>
 810            <p>If the value is an integer <c>N</c> in the range -32768 to 32767
 811              (inclusive), the value is added to the socket's count of data
 812              messages sent to the controlling process. A socket's default
 813              message count is <c>0</c>. If a negative value is specified, and
 814              its magnitude is equal to or greater than the socket's current
 815              message count, the socket's message count is set to <c>0</c>.
 816              Once the socket's message count reaches <c>0</c>, either because
 817              of sending
 818              received data messages to the process or by being explicitly set,
 819              the process is then notified by a special message, specific to
 820              the type of socket, that the socket has entered passive
 821              mode. Once the socket enters passive mode, to receive more
 822              messages <c>setopts/2</c> must be called again to set the
 823              socket back into an active mode.</p>
 824            <p>When using <c>{active, once}</c> or <c>{active, N}</c>, the
 825              socket changes behavior automatically when data is received.
 826              This can be confusing in combination with connection-oriented
 827              sockets (that is, <c>gen_tcp</c>), as a socket
 828              with <c>{active, false}</c> behavior reports closing
 829              differently than a socket with <c>{active, true}</c>
 830              behavior. To simplify programming, a socket where
 831              the peer closed, and this is detected while in
 832              <c>{active, false}</c> mode, still generates message
 833              <c>{tcp_closed,Socket}</c> when set to <c>{active, once}</c>,
 834              <c>{active, true}</c>, or <c>{active, N}</c> mode.
 835              It is therefore safe to assume that message
 836              <c>{tcp_closed,Socket}</c>, possibly followed by socket port
 837              termination (depending on option <c>exit_on_close</c>)
 838              eventually appears when a socket changes
 839              back and forth between <c>{active, true}</c> and
 840              <c>{active, false}</c> mode. However,
 841              <em>when</em> peer closing is detected it is all up to the
 842              underlying TCP/IP stack and protocol.</p>
 843            <p>Notice that <c>{active, true}</c> mode provides no flow
 844              control; a fast sender can easily overflow the
 845              receiver with incoming messages. The same is true for
 846              <c>{active, N}</c> mode, while the message count is greater
 847              than zero.</p>
 848            <p>Use active mode only if
 849              your high-level protocol provides its own flow control
 850              (for example, acknowledging received messages) or the
 851              amount of data exchanged is small. <c>{active, false}</c>
 852              mode, use of the <c>{active, once}</c> mode, or <c>{active, N}</c>
 853              mode with values of <c>N</c> appropriate for the application
 854              provides flow control. The other side cannot send
 855              faster than the receiver can read.</p>
 856          </item>
 857          <tag><c>{broadcast, Boolean}</c> (UDP sockets)</tag>
 858          <item>
 859            <p>Enables/disables permission to send broadcasts.</p>
 860            <marker id="option-buffer"></marker>
 861          </item>
 862          <tag><c>{buffer, Size}</c></tag>
 863          <item>
 864            <p>The size of the user-level buffer used by
 865              the driver. Not to be confused with options <c>sndbuf</c>
 866              and <c>recbuf</c>, which correspond to the
 867              Kernel socket buffers. For TCP it is recommended
 868              to have <c>val(buffer) &gt;= val(recbuf)</c> to
 869              avoid performance issues because of unnecessary copying.
 870              For UDP the same recommendation applies, but the max should
 871              not be larger than the MTU of the network path.
 872              <c>val(buffer)</c> is automatically set to the above
 873              maximum when <c>recbuf</c> is set.
 874              However, as the size set for <c>recbuf</c>
 875              usually become larger, you are encouraged to use
 876              <seealso marker="#getopts/2"><c>getopts/2</c></seealso>
 877              to analyze the behavior of your operating system.</p>
 878            <p>Note that this is also the maximum amount of data that can be
 879	       received from a single recv call. If you are using higher than
 880	       normal MTU consider setting buffer higher.</p>
 881          </item>
 882          <tag><c>{delay_send, Boolean}</c></tag>
 883          <item>
 884            <p>Normally, when an Erlang process sends to a socket,
 885              the driver tries to send the data immediately. If that
 886              fails, the driver uses any means available to queue
 887              up the message to be sent whenever the operating system
 888              says it can handle it. Setting <c>{delay_send, true}</c>
 889              makes <em>all</em> messages queue up. The messages sent
 890              to the network are then larger but fewer.
 891              The option affects the scheduling of send
 892              requests versus Erlang processes instead of changing any
 893              real property of the socket. The option is
 894              implementation-specific. Defaults to <c>false</c>.</p>
 895          </item>
 896          <tag><c>{deliver, port | term}</c></tag>
 897          <item>
 898            <p>When <c>{active, true}</c>, data is delivered on the form
 899              <c>port</c> : <c>{S, {data, [H1,..Hsz | Data]}}</c> or
 900              <c>term</c> : <c>{tcp, S, [H1..Hsz | Data]}</c>.</p>
 901          </item>
 902          <tag><c>{dontroute, Boolean}</c></tag>
 903          <item>
 904            <p>Enables/disables routing bypass for outgoing messages.</p>
 905          </item>
 906          <tag><c>{exit_on_close, Boolean}</c></tag>
 907          <item>
 908            <p>This option is set to <c>true</c> by default.</p>
 909            <p>The only reason to set it to <c>false</c> is if you want
 910              to continue sending data to the socket after a close is
 911              detected, for example, if the peer uses
 912              <seealso marker="gen_tcp#shutdown/2"><c>gen_tcp:shutdown/2</c></seealso>
 913              to shut down the write side.</p>
 914          </item>
 915          <tag><c>{header, Size}</c></tag>
 916          <item>
 917            <p>This option is only meaningful if option <c>binary</c>
 918              was specified when the socket was created. If option
 919              <c>header</c> is specified, the first
 920              <c>Size</c> number bytes of data received from the socket
 921              are elements of a list, and the remaining data is
 922              a binary specified as the tail of the same list. For example,
 923              if <c>Size == 2</c>, the data received matches
 924              <c>[Byte1,Byte2|Binary]</c>.</p>
 925          </item>
 926          <tag><c>{high_msgq_watermark, Size}</c></tag>
 927          <item>
 928	    <p>The socket message queue is set to a busy
 929	      state when the amount of data on the message
 930	      queue reaches this limit. Notice that this limit only
 931	      concerns data that has not yet reached the ERTS internal
 932	      socket implementation. Defaults to 8 kB.</p>
 933	    <p>Senders of data to the socket are suspended if
 934	      either the socket message queue is busy or the socket
 935	      itself is busy.</p>
 936	    <p>For more information, see options <c>low_msgq_watermark</c>,
 937	      <c>high_watermark</c>, and <c>low_watermark</c>.</p>
 938	    <p>Notice that distribution sockets disable the use of
 939	      <c>high_msgq_watermark</c> and <c>low_msgq_watermark</c>.
 940	      Instead use the
 941	      <seealso marker="erts:erlang#system_info_dist_buf_busy_limit">distribution buffer busy limit</seealso>,
 942              which is a similar feature.</p>
 943          </item>
 944          <tag><c>{high_watermark, Size}</c> (TCP/IP sockets)</tag>
 945          <item>
 946	    <p>The socket is set to a busy state when the amount
 947	      of data queued internally by the ERTS socket implementation
 948	      reaches this limit. Defaults to 8 kB.</p>
 949	    <p>Senders of data to the socket are suspended if
 950	      either the socket message queue is busy or the socket
 951	      itself is busy.</p>
 952	    <p>For more information, see options <c>low_watermark</c>,
 953	      <c>high_msgq_watermark</c>, and <c>low_msqg_watermark</c>.</p>
 954          </item>
 955	  <tag><c>{ipv6_v6only, Boolean}</c></tag>
 956	  <item>
 957	    <p>Restricts the socket to use only IPv6, prohibiting any
 958	      IPv4 connections. This is only applicable for
 959	      IPv6 sockets (option <c>inet6</c>).</p>
 960            <p>On most platforms this option must be set on the socket
 961	      before associating it to an address. It is therefore only
 962	      reasonable to specify it when creating the socket and not
 963	      to use it when calling function
 964	      (<seealso marker="#setopts/2"><c>setopts/2</c></seealso>)
 965	      containing this description.</p>
 966	    <p>The behavior of a socket with this option set to
 967	      <c>true</c> is the only portable one. The original
 968	      idea when IPv6 was new of using IPv6 for all traffic
 969	      is now not recommended by FreeBSD (you can use
 970	      <c>{ipv6_v6only,false}</c> to override the recommended
 971	      system default value),
 972	      forbidden by OpenBSD (the supported GENERIC kernel),
 973	      and impossible on Windows (which has separate
 974	      IPv4 and IPv6 protocol stacks). Most Linux distros
 975	      still have a system default value of <c>false</c>.
 976	      This policy shift among operating systems to
 977	      separate IPv6 from IPv4 traffic has evolved, as
 978	      it gradually proved hard and complicated to get
 979	      a dual stack implementation correct and secure.</p>
 980	    <p>On some platforms, the only allowed value for this option
 981	      is <c>true</c>, for example, OpenBSD and Windows. Trying to set
 982	      this option to <c>false</c>, when creating the socket, fails
 983	      in this case.</p>
 984	    <p>Setting this option on platforms where it does not exist
 985	      is ignored. Getting this option with
 986	      <seealso marker="#getopts/2"><c>getopts/2</c></seealso>
 987	      returns no value, that is, the returned list does not contain an
 988	      <c>{ipv6_v6only,_}</c> tuple. On Windows, the option
 989	      does not exist, but it is emulated as a
 990	      read-only option with value <c>true</c>.</p>
 991	    <p>Therefore, setting this option to <c>true</c>
 992	      when creating a socket never fails, except possibly on a
 993              platform where you
 994	      have customized the kernel to only allow <c>false</c>,
 995	      which can be doable (but awkward) on, for example, OpenBSD.</p>
 996	    <p>If you read back the option value using
 997	      <seealso marker="#getopts/2"><c>getopts/2</c></seealso>
 998	      and get no value, the option does not exist in the host
 999              operating system. The behavior of both an IPv6 and an IPv4
1000	      socket listening on the same port, and for an IPv6 socket
1001	      getting IPv4 traffic is then no longer predictable.</p>
1002	  </item>
1003          <tag><c>{keepalive, Boolean}</c>(TCP/IP sockets)</tag>
1004          <item>
1005            <p>Enables/disables periodic transmission on a connected
1006              socket when no other data is exchanged. If
1007              the other end does not respond, the connection is
1008              considered broken and an error message is sent to
1009              the controlling process. Defaults to <c>disabled</c>.</p>
1010            <marker id="option-linger"></marker>
1011          </item>
1012          <tag><c>{linger, {true|false, Seconds}}</c></tag>
1013	  <item>
1014            <p>Determines the time-out, in seconds, for flushing unsent data
1015              in the <c>close/1</c> socket call. </p>
1016	    <p>The first component is if linger is enabled, the second component
1017	    is the flushing time-out, in seconds. There are 3 alternatives:</p>
1018	    <taglist>
1019	      <tag><c>{false, _}</c></tag>
1020	      <item>
1021		<p>close/1 or shutdown/2 returns immediately,
1022		not waiting for data to be flushed, with closing
1023		happening in the background.</p>
1024	      </item>
1025	      <tag><c>{true, 0}</c></tag>
1026	      <item>
1027		<p>Aborts the connection when it is closed.
1028		Discards any data still remaining in the send buffers
1029		and sends RST to the peer.</p>
1030		<p>This avoids TCP's TIME_WAIT state, but leaves open
1031		the possibility that another "incarnation" of this connection
1032		being created.</p>
1033	      </item>
1034	      <tag><c>{true, Time} when Time > 0</c></tag>
1035	      <item>
1036		<p>close/1 or shutdown/2 will not return until
1037		all queued messages for the socket have been successfully
1038		sent or the linger timeout (Time) has been reached.</p>
1039	      </item>
1040	    </taglist>
1041          </item>
1042          <tag><c>{low_msgq_watermark, Size}</c></tag>
1043          <item>
1044	    <p>If the socket message queue is in a busy state, the
1045	      socket message queue is set in a not busy state when
1046	      the amount of data queued in the message queue falls
1047	      below this limit. Notice that this limit only concerns data
1048	      that has not yet reached the ERTS internal socket
1049	      implementation. Defaults to 4 kB.</p>
1050	    <p>Senders that are suspended because of either a
1051	      busy message queue or a busy socket are resumed
1052	      when the socket message queue and the socket
1053	      are not busy.</p>
1054	    <p>For more information, see options <c>high_msgq_watermark</c>,
1055	      <c>high_watermark</c>, and <c>low_watermark</c>.</p>
1056	    <p>Notice that distribution sockets disable the use of
1057	      <c>high_msgq_watermark</c> and <c>low_msgq_watermark</c>.
1058	      Instead they use the
1059	      <seealso marker="erts:erlang#system_info_dist_buf_busy_limit">distribution
1060	      buffer busy limit</seealso>, which is a similar feature.</p>
1061          </item>
1062          <tag><c>{low_watermark, Size}</c> (TCP/IP sockets)</tag>
1063          <item>
1064	    <p>If the socket is in a busy state, the socket is
1065	      set in a not busy state when the amount of data
1066	      queued internally by the ERTS socket implementation
1067	      falls below this limit. Defaults to 4 kB.</p>
1068	    <p>Senders that are suspended because of a
1069	      busy message queue or a busy socket are resumed
1070	      when the socket message queue and the socket are not busy.</p>
1071	    <p>For more information, see options <c>high_watermark</c>,
1072	      <c>high_msgq_watermark</c>, and <c>low_msgq_watermark</c>.</p>
1073          </item>
1074          <tag><c>{mode, Mode :: binary | list}</c></tag>
1075          <item>
1076            <p>
1077	      Received <c>Packet</c> is delivered as defined by <c>Mode</c>.
1078            </p>
1079          </item>
1080	  <tag>
1081	    <marker id="option-netns"/>
1082	    <c>{netns, Namespace :: file:filename_all()}</c>
1083	  </tag>
1084	  <item>
1085	    <p>
1086	      Sets a network namespace for the socket. Parameter
1087	      <c>Namespace</c> is a filename defining the namespace, for
1088	      example, <c>"/var/run/netns/example"</c>, typically created by
1089	      command <c>ip netns add example</c>. This option must be used in
1090	      a function call that creates a socket, that is,
1091	      <seealso marker="gen_tcp#connect/3"><c>gen_tcp:connect/3,4</c></seealso>,
1092	      <seealso marker="gen_tcp#listen/2"><c>gen_tcp:listen/2</c></seealso>,
1093	      <seealso marker="gen_udp#open/1"><c>gen_udp:open/1,2</c></seealso>
1094	      or
1095	      <seealso marker="gen_sctp#open/0"><c>gen_sctp:open/0,1,2</c></seealso>,
1096	      and also
1097	      <seealso marker="#getifaddrs/1"><c>getifaddrs/1</c></seealso>.
1098	    </p>
1099	    <p>This option uses the Linux-specific syscall
1100	      <c>setns()</c>, such as in Linux kernel 3.0 or later,
1101	      and therefore only exists when the runtime system
1102	      is compiled for such an operating system.</p>
1103	    <p>The virtual machine also needs elevated privileges, either
1104	      running as superuser or (for Linux) having capability
1105	      <c>CAP_SYS_ADMIN</c> according to the documentation for
1106	      <c>setns(2)</c>.
1107	      However, during testing also <c>CAP_SYS_PTRACE</c>
1108	      and <c>CAP_DAC_READ_SEARCH</c> have proven to be necessary.</p>
1109            <p><em>Example:</em></p>
1110	    <code>
1111setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp</code>
1112            <p>Notice that the filesystem containing the virtual machine
1113	      executable (<c>beam.smp</c> in the example) must be local,
1114	      mounted without flag <c>nosetuid</c>,
1115	      support extended attributes, and
1116	      the kernel must support file capabilities.
1117	      All this runs out of the box on at least Ubuntu 12.04 LTS,
1118	      except that SCTP sockets appear to not support
1119	      network namespaces.</p>
1120	    <p><c>Namespace</c> is a filename and is encoded
1121	      and decoded as discussed in module
1122	      <seealso marker="file">file</seealso>, with the
1123              following exceptions:</p>
1124	    <list type="bulleted">
1125	      <item><p>Emulator flag <c>+fnu</c> is ignored.</p></item>
1126	      <item><p><seealso marker="#getopts/2"><c>getopts/2</c></seealso>
1127	      for this option returns a binary for the filename if the stored
1128	      filename cannot be decoded. This is only to occur if you set the
1129	      option using a binary that cannot be decoded with the emulator's
1130	      filename encoding:
1131	      <seealso marker="file#native_name_encoding/0"><c>file:native_name_encoding/0</c></seealso>.</p></item>
1132	    </list>
1133          </item>
1134	  <tag><c>{bind_to_device, Ifname :: binary()}</c></tag>
1135	  <item>
1136	    <p>Binds a socket to a specific network interface. This option
1137	      must be used in a function call that creates a socket, that is,
1138	      <seealso marker="gen_tcp#connect/3"><c>gen_tcp:connect/3,4</c></seealso>,
1139	      <seealso marker="gen_tcp#listen/2"><c>gen_tcp:listen/2</c></seealso>,
1140	      <seealso marker="gen_udp#open/1"><c>gen_udp:open/1,2</c></seealso>, or
1141	      <seealso marker="gen_sctp#open/0"><c>gen_sctp:open/0,1,2</c></seealso>.</p>
1142	    <p>Unlike <seealso marker="#getifaddrs/0"><c>getifaddrs/0</c></seealso>, Ifname
1143	      is encoded a binary. In the unlikely case that a system is using
1144	      non-7-bit-ASCII characters in network device names, special care
1145	      has to be taken when encoding this argument.</p>
1146	    <p>This option uses the Linux-specific socket option
1147	      <c>SO_BINDTODEVICE</c>, such as in Linux kernel 2.0.30 or later,
1148	      and therefore only exists when the runtime system
1149	      is compiled for such an operating system.</p>
1150	    <p>Before Linux 3.8, this socket option could be set, but could not retrieved
1151	      with <seealso marker="#getopts/2"><c>getopts/2</c></seealso>. Since Linux 3.8,
1152	      it is readable.</p>
1153	    <p>The virtual machine also needs elevated privileges, either
1154	      running as superuser or (for Linux) having capability
1155	    <c>CAP_NET_RAW</c>.</p>
1156	    <p>The primary use case for this option is to bind sockets into
1157	      <url href="http://www.kernel.org/doc/Documentation/networking/vrf.txt">Linux VRF instances</url>.
1158	    </p>
1159	  </item>
1160          <tag><c>list</c></tag>
1161          <item>
1162            <p>Received <c>Packet</c> is delivered as a list.</p>
1163          </item>
1164          <tag><c>binary</c></tag>
1165          <item>
1166            <p>Received <c>Packet</c> is delivered as a binary.</p>
1167          </item>
1168          <tag><c>{nodelay, Boolean}</c>(TCP/IP sockets)</tag>
1169          <item>
1170            <p>If <c>Boolean == true</c>, option <c>TCP_NODELAY</c>
1171              is turned on for the socket, which means that also small
1172              amounts of data are sent immediately.</p>
1173          </item>
1174          <tag><c>{nopush, Boolean}</c>(TCP/IP sockets)</tag>
1175          <item>
1176            <p>This translates to <c>TCP_NOPUSH</c> on BSD and
1177              to <c>TCP_CORK</c> on Linux.</p>
1178            <p>If <c>Boolean == true</c>, the corresponding option
1179              is turned on for the socket, which means that small
1180              amounts of data are accumulated until a full MSS-worth
1181              of data is available or this option is turned off.</p>
1182            <p>Note that while <c>TCP_NOPUSH</c> socket option is available on OSX, its semantics
1183              is very different (e.g., unsetting it does not cause immediate send
1184              of accumulated data). Hence, <c>nopush</c> option is intentionally ignored on OSX.</p>
1185          </item>
1186          <tag><c>{packet, PacketType}</c>(TCP/IP sockets)</tag>
1187          <item>
1188            <p><marker id="packet"/>Defines the type of packets to use for a socket.
1189	      Possible values:</p>
1190            <taglist>
1191              <tag><c>raw | 0</c></tag>
1192              <item>
1193                <p>No packaging is done.</p>
1194              </item>
1195              <tag><c>1 | 2 | 4</c></tag>
1196

Large files files are truncated, but you can click here to view the full file