PageRenderTime 59ms CodeModel.GetById 3ms app.highlight 38ms RepoModel.GetById 2ms app.codeStats 0ms

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

https://github.com/cobusc/otp
XML | 1439 lines | 1402 code | 37 blank | 0 comment | 0 complexity | e20c312f7505653a4dfb06175d9d1025 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>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="posix"/>
 181      <desc>
 182        <p>An atom that is named from the POSIX error codes used in Unix,
 183          and in the runtime libraries of most C compilers. See section
 184          <seealso marker="#error_codes">POSIX Error Codes</seealso>.</p>
 185      </desc>
 186    </datatype>
 187    <datatype>
 188      <name>socket()</name>
 189      <desc>
 190        <p>See
 191          <seealso marker="gen_tcp#type-socket"><c>gen_tcp:type-socket</c></seealso>
 192          and
 193          <seealso marker="gen_udp#type-socket"><c>gen_udp:type-socket</c></seealso>.
 194        </p>
 195      </desc>
 196    </datatype>
 197    <datatype>
 198      <name name="address_family"/>
 199    </datatype>
 200    <datatype>
 201      <name name="socket_protocol"/>
 202    </datatype>
 203  </datatypes>
 204
 205  <funcs>
 206    <func>
 207      <name name="close" arity="1"/>
 208      <fsummary>Close a socket of any type.</fsummary>
 209      <desc>
 210        <p>Closes a socket of any type.</p>
 211      </desc>
 212    </func>
 213
 214    <func>
 215      <name name="format_error" arity="1"/>
 216      <fsummary>Return a descriptive string for an error reason.</fsummary>
 217      <desc>
 218        <p>Returns a diagnostic error string. For possible POSIX values and
 219          corresponding strings, see section
 220          <seealso marker="#error_codes">POSIX Error Codes</seealso>.</p>
 221      </desc>
 222    </func>
 223
 224    <func>
 225      <name name="get_rc" arity="0"/>
 226      <fsummary>Return a list of IP configuration parameters.</fsummary>
 227      <desc>
 228        <p>
 229	  Returns the state of the <c>Inet</c> configuration database in
 230          form of a list of recorded configuration parameters. For more
 231          information, see <seealso marker="erts:inet_cfg">ERTS User's Guide:
 232          Inet Configuration</seealso>.
 233	</p>
 234        <p>
 235	  Only actual parameters with other than default values
 236	  are returned, for example not directives that specify
 237	  other sources for configuration parameters nor
 238	  directives that clear parameters.
 239	</p>
 240      </desc>
 241    </func>
 242
 243    <func>
 244      <name name="getaddr" arity="2"/>
 245      <fsummary>Return the IP address for a host.</fsummary>
 246      <desc>
 247        <p>Returns the IP address for <c><anno>Host</anno></c> as a tuple of
 248          integers. <c><anno>Host</anno></c> can be an IP address, a single
 249          hostname, or a fully qualified hostname.</p>
 250      </desc>
 251    </func>
 252
 253    <func>
 254      <name name="getaddrs" arity="2"/>
 255      <fsummary>Return the IP addresses for a host.</fsummary>
 256      <desc>
 257        <p>Returns a list of all IP addresses for <c><anno>Host</anno></c>.
 258          <c><anno>Host</anno></c> can be an IP address, a single hostname, or
 259          a fully qualified hostname.</p>
 260      </desc>
 261    </func>
 262
 263    <func>
 264      <name name="gethostbyaddr" arity="1"/>
 265      <fsummary>Return a hostent record for the host with the specified
 266        address.</fsummary>
 267      <desc>
 268        <p>Returns a <c>hostent</c> record for the host with the specified
 269          address.</p></desc>
 270    </func>
 271
 272    <func>
 273      <name name="gethostbyname" arity="1"/>
 274      <fsummary>Return a hostent record for the host with the specified name.
 275      </fsummary>
 276      <desc>
 277        <p>Returns a <c>hostent</c> record for the host with the specified
 278          hostname.</p>
 279        <p>If resolver option <c>inet6</c> is <c>true</c>,
 280          an IPv6 address is looked up.</p>
 281      </desc>
 282    </func>
 283
 284    <func>
 285      <name name="gethostbyname" arity="2"/>
 286      <fsummary>Return a hostent record for the host with the specified name.
 287      </fsummary>
 288      <desc>
 289        <p>Returns a <c>hostent</c> record for the host with the specified
 290          name, restricted to the specified address family.</p>
 291      </desc>
 292    </func>
 293
 294    <func>
 295      <name name="gethostname" arity="0"/>
 296      <fsummary>Return the local hostname.</fsummary>
 297      <desc>
 298        <p>Returns the local hostname. Never fails.</p>
 299      </desc>
 300    </func>
 301
 302    <func>
 303      <name name="getifaddrs" arity="0"/>
 304      <fsummary>Return a list of interfaces and their addresses.</fsummary>
 305      <desc>
 306        <p>Returns a list of 2-tuples containing interface names and the
 307          interface addresses. <c><anno>Ifname</anno></c> is a Unicode string.
 308          <c><anno>Hwaddr</anno></c> is hardware dependent, for example, on
 309          Ethernet interfaces
 310          it is the 6-byte Ethernet address (MAC address (EUI-48 address)).</p>
 311        <p>The tuples <c>{addr,<anno>Addr</anno>}</c>, <c>{netmask,_}</c>, and
 312          <c>{broadaddr,_}</c> are repeated in the result list if the interface
 313          has multiple addresses. If you come across an interface with
 314          multiple <c>{flag,_}</c> or <c>{hwaddr,_}</c> tuples, you have
 315          a strange interface or possibly a bug in this function. The tuple
 316          <c>{flag,_}</c> is mandatory, all others are optional.</p>
 317        <p>Do not rely too much on the order of <c><anno>Flag</anno></c> atoms
 318          or <c><anno>Ifopt</anno></c> tuples. There are however some rules:</p>
 319        <list type="bulleted">
 320          <item><p>Immediately after
 321            <c>{addr,_}</c> follows <c>{netmask,_}</c>.</p></item>
 322          <item><p>Immediately thereafter follows <c>{broadaddr,_}</c> if flag
 323            <c>broadcast</c> is <em>not</em> set and flag
 324            <c>pointtopoint</c> <em>is</em> set.</p></item>
 325          <item><p>Any <c>{netmask,_}</c>, <c>{broadaddr,_}</c>, or
 326            <c>{dstaddr,_}</c> tuples that follow an <c>{addr,_}</c>
 327            tuple concerns that address.</p></item>
 328        </list>
 329        <p>The tuple <c>{hwaddr,_}</c> is not returned on Solaris, as the
 330          hardware address historically belongs to the link layer and only
 331          the superuser can read such addresses.</p>
 332	<warning>
 333	  <p>On Windows, the data is fetched from different OS API functions,
 334            so the <c><anno>Netmask</anno></c> and <c><anno>Broadaddr</anno></c>
 335            values can be calculated, just as some <c><anno>Flag</anno></c>
 336            values. Report flagrant bugs.</p>
 337	</warning>
 338      </desc>
 339    </func>
 340
 341    <func>
 342      <name name="getopts" arity="2"/>
 343      <fsummary>Get one or more options for a socket.</fsummary>
 344      <desc>
 345        <p>Gets one or more options for a socket. For a list of available
 346          options, see
 347          <seealso marker="#setopts/2"><c>setopts/2</c></seealso>.</p>
 348        <p>The number of elements in the returned
 349          <c><anno>OptionValues</anno></c>
 350          list does not necessarily correspond to the number of options
 351          asked for. If the operating system fails to support an option,
 352          it is left out in the returned list. An error tuple is returned
 353          only when getting options for the socket is impossible (that is,
 354          the socket is closed or the buffer size in a raw request
 355          is too large). This behavior is kept for backward
 356          compatibility reasons.</p>
 357        <p>A raw option request
 358          <c>RawOptReq = {raw, Protocol, OptionNum, ValueSpec}</c>
 359          can be used to get information about
 360          socket options not (explicitly) supported by the emulator. The
 361          use of raw socket options makes the code non-portable, but
 362          allows the Erlang programmer to take advantage of unusual features
 363          present on the current platform.</p>
 364        <p><c>RawOptReq</c> consists of tag <c>raw</c> followed
 365          by the protocol level, the option number, and either a binary
 366          or the size, in bytes, of the
 367          buffer in which the option value is to be stored. A binary is to be
 368          used when the underlying <c>getsockopt</c> requires <em>input</em>
 369          in the argument field. In this case, the binary size
 370          is to correspond to the required buffer
 371          size of the return value. The supplied values in a <c>RawOptReq</c>
 372          correspond to the second, third, and fourth/fifth parameters to the
 373          <c>getsockopt</c> call in the C socket API. The value stored
 374          in the buffer is returned as a binary <c>ValueBin</c>,
 375          where all values are coded in the native endianess.</p>
 376        <p>Asking for and inspecting raw socket options require low-level
 377          information about the current operating system and TCP stack.</p>
 378        <p><em>Example:</em></p>
 379        <p>Consider a Linux machine where option
 380          <c>TCP_INFO</c> can be used to collect TCP statistics
 381          for a socket. Assume you are interested in field
 382          <c>tcpi_sacked</c> of <c>struct tcp_info</c>
 383          filled in when asking for <c>TCP_INFO</c>. To be able to access
 384          this information, you need to know the following:</p>
 385        <list type="bulleted">
 386          <item>The numeric value of protocol level <c>IPPROTO_TCP</c></item>
 387          <item>The numeric value of option <c>TCP_INFO</c></item>
 388          <item>The size of <c>struct tcp_info</c></item>
 389          <item>The size and offset of the specific field</item>
 390        </list>
 391        <p>By inspecting the headers or writing a small C program, it is found
 392          that <c>IPPROTO_TCP</c> is 6, <c>TCP_INFO</c> is 11, the structure
 393          size is 92 (bytes), the offset of <c>tcpi_sacked</c> is 28 bytes,
 394          and the value is a 32-bit integer. The following code can be used
 395          to retrieve the value:</p>
 396        <code type="none"><![CDATA[
 397get_tcpi_sacked(Sock) ->
 398    {ok,[{raw,_,_,Info}]} = inet:getopts(Sock,[{raw,6,11,92}]),
 399    <<_:28/binary,TcpiSacked:32/native,_/binary>> = Info,
 400    TcpiSacked.]]></code>
 401        <p>Preferably, you would check the machine type, the operating system,
 402          and the Kernel version before executing anything similar to
 403          this code.</p>
 404      </desc>
 405    </func>
 406
 407    <func>
 408      <name name="getstat" arity="1"/>
 409      <name name="getstat" arity="2"/>
 410      <fsummary>Get one or more statistic options for a socket.</fsummary>
 411      <type name="stat_option"/>
 412      <desc>
 413        <p>Gets one or more statistic options for a socket.</p>
 414        <p><c>getstat(<anno>Socket</anno>)</c> is equivalent to
 415          <c>getstat(<anno>Socket</anno>, [recv_avg, recv_cnt, recv_dvi,
 416          recv_max, recv_oct, send_avg, send_cnt, send_dvi, send_max,
 417          send_oct])</c>.</p>
 418        <p>The following options are available:</p>
 419        <taglist>
 420          <tag><c>recv_avg</c></tag>
 421          <item>
 422            <p>Average size of packets, in bytes, received by the socket.</p>
 423          </item>
 424          <tag><c>recv_cnt</c></tag>
 425          <item>
 426            <p>Number of packets received by the socket.</p>
 427          </item>
 428          <tag><c>recv_dvi</c></tag>
 429          <item>
 430            <p>Average packet size deviation, in bytes, received by the socket.</p>
 431          </item>
 432          <tag><c>recv_max</c></tag>
 433          <item>
 434            <p>Size of the largest packet, in bytes, received by the socket.</p>
 435          </item>
 436          <tag><c>recv_oct</c></tag>
 437          <item>
 438            <p>Number of bytes received by the socket.</p>
 439          </item>
 440          <tag><c>send_avg</c></tag>
 441          <item>
 442            <p>Average size of packets, in bytes, sent from the socket.</p>
 443          </item>
 444          <tag><c>send_cnt</c></tag>
 445          <item>
 446            <p>Number of packets sent from the socket.</p>
 447          </item>
 448          <tag><c>send_dvi</c></tag>
 449          <item>
 450            <p>Average packet size deviation, in bytes, sent from the socket.</p>
 451          </item>
 452          <tag><c>send_max</c></tag>
 453          <item>
 454            <p>Size of the largest packet, in bytes, sent from the socket.</p>
 455          </item>
 456          <tag><c>send_oct</c></tag>
 457          <item>
 458            <p>Number of bytes sent from the socket.</p>
 459          </item>
 460        </taglist>
 461      </desc>
 462    </func>
 463
 464    <func>
 465      <name name="i" arity="0" />
 466      <name name="i" arity="1" />
 467      <name name="i" arity="2" />
 468      <fsummary>Displays information and statistics about sockets on the terminal</fsummary>
 469      <desc>
 470        <p>
 471          Lists all TCP, UDP and SCTP sockets, including those that the Erlang runtime system uses as well as
 472          those created by the application.
 473        </p>
 474        <p>
 475          The following options are available:
 476        </p>
 477
 478        <taglist>
 479          <tag><c>port</c></tag>
 480          <item>
 481            <p>The internal index of the port.</p>
 482          </item>
 483          <tag><c>module</c></tag>
 484          <item>
 485            <p>The callback module of the socket.</p>
 486          </item>
 487          <tag><c>recv</c></tag>
 488          <item>
 489            <p>Number of bytes received by the socket.</p>
 490          </item>
 491          <tag><c>sent</c></tag>
 492          <item>
 493            <p>Number of bytes sent from the socket.</p>
 494          </item>
 495          <tag><c>owner</c></tag>
 496          <item>
 497            <p>The socket owner process.</p>
 498          </item>
 499          <tag><c>local_address</c></tag>
 500          <item>
 501            <p>The local address of the socket.</p>
 502          </item>
 503          <tag><c>foreign_address</c></tag>
 504          <item>
 505            <p>The address and port of the other end of the connection.</p>
 506          </item>
 507          <tag><c>state</c></tag>
 508          <item>
 509            <p>The connection state.</p>
 510          </item>
 511          <tag><c>type</c></tag>
 512          <item>
 513            <p>STREAM or DGRAM or SEQPACKET.</p>
 514          </item>
 515        </taglist>
 516      </desc>
 517    </func>
 518
 519    <func>
 520      <name name="ntoa" arity="1" />
 521      <fsummary>Convert IPv6/IPV4 address to ASCII.</fsummary>
 522      <desc>
 523	<p>Parses an
 524          <seealso marker="#type-ip_address"><c>ip_address()</c></seealso>
 525          and returns an IPv4 or IPv6 address string.</p>
 526      </desc>
 527    </func>
 528
 529    <func>
 530      <name name="parse_address" arity="1" />
 531      <fsummary>Parse an IPv4 or IPv6 address.</fsummary>
 532      <desc>
 533	<p>Parses an IPv4 or IPv6 address string and returns an
 534          <seealso marker="#type-ip4_address"><c>ip4_address()</c></seealso> or
 535          <seealso marker="#type-ip6_address"><c>ip6_address()</c></seealso>.
 536          Accepts a shortened IPv4 address string.</p>
 537      </desc>
 538    </func>
 539
 540    <func>
 541      <name name="parse_ipv4_address" arity="1" />
 542      <fsummary>Parse an IPv4 address.</fsummary>
 543      <desc>
 544	<p>Parses an IPv4 address string and returns an
 545          <seealso marker="#type-ip4_address"><c>ip4_address()</c></seealso>.
 546	  Accepts a shortened IPv4 address string.</p>
 547      </desc>
 548    </func>
 549
 550    <func>
 551      <name name="parse_ipv4strict_address" arity="1" />
 552      <fsummary>Parse an IPv4 address strict.</fsummary>
 553      <desc>
 554	<p>Parses an IPv4 address string containing four fields, that is,
 555          <em>not</em> shortened, and returns an
 556          <seealso marker="#type-ip4_address"><c>ip4_address()</c></seealso>.
 557        </p>
 558      </desc>
 559    </func>
 560
 561    <func>
 562      <name name="parse_ipv6_address" arity="1" />
 563      <fsummary>Parse an IPv6 address.</fsummary>
 564      <desc>
 565	<p>Parses an IPv6 address string and returns an
 566          <seealso marker="#type-ip6_address"><c>ip6_address()</c></seealso>.
 567          If an IPv4 address string is specified, an IPv4-mapped IPv6 address
 568          is returned.</p>
 569      </desc>
 570    </func>
 571
 572    <func>
 573      <name name="parse_ipv6strict_address" arity="1" />
 574      <fsummary>Parse an IPv6 address strict.</fsummary>
 575      <desc>
 576	<p>Parses an IPv6 address string and returns an
 577          <seealso marker="#type-ip6_address"><c>ip6_address()</c></seealso>.
 578          Does <em>not</em> accept IPv4 addresses.</p>
 579      </desc>
 580    </func>
 581
 582    <func>
 583      <name name="ipv4_mapped_ipv6_address" arity="1" />
 584      <fsummary>Convert to and from IPv4-mapped IPv6 address.</fsummary>
 585      <desc>
 586	<p>
 587	  Convert an IPv4 address to an IPv4-mapped IPv6 address
 588	  or the reverse.  When converting from an IPv6 address
 589	  all but the 2 low words are ignored so this function also
 590	  works on some other types of addresses than IPv4-mapped.
 591	</p>
 592      </desc>
 593    </func>
 594
 595    <func>
 596      <name name="parse_strict_address" arity="1" />
 597      <fsummary>Parse an IPv4 or IPv6 address strict.</fsummary>
 598      <desc>
 599	<p>Parses an IPv4 or IPv6 address string and returns an
 600          <seealso marker="#type-ip4_address"><c>ip4_address()</c></seealso> or
 601          <seealso marker="#type-ip6_address"><c>ip6_address()</c></seealso>.
 602          Does <em>not</em> accept a shortened IPv4 address string.</p>
 603      </desc>
 604    </func>
 605
 606    <func>
 607      <name name="peername" arity="1"/>
 608      <fsummary>Return the address and port for the other end of a connection.
 609      </fsummary>
 610      <desc>
 611        <p>Returns the address and port for the other end of a connection.</p>
 612	<p>Notice that for SCTP sockets, this function returns only
 613	  one of the peer addresses of the socket. Function
 614	  <seealso marker="#peernames/1"><c>peernames/1,2</c></seealso>
 615	  returns all.</p>
 616      </desc>
 617    </func>
 618
 619    <func>
 620      <name name="peernames" arity="1"/>
 621      <fsummary>Return all address/port numbers for the other end of a
 622        connection.</fsummary>
 623      <desc>
 624	<p>Equivalent to
 625	  <seealso marker="#peernames/2"><c>peernames(<anno>Socket</anno>, 0)</c></seealso>.
 626        </p>
 627        <p>Notice that the behavior of this function for an SCTP
 628	  one-to-many style socket is not defined by the
 629	  <url href="http://tools.ietf.org/html/draft-ietf-tsvwg-sctpsocket-13">SCTP Sockets API Extensions</url>.</p>
 630      </desc>
 631    </func>
 632
 633    <func>
 634      <name name="peernames" arity="2"/>
 635      <fsummary>Return all address/port numbers for the other end of a
 636        connection.</fsummary>
 637      <desc>
 638	<p>Returns a list of all address/port number pairs for the other end
 639	  of an association <c><anno>Assoc</anno></c> of a socket.</p>
 640	<p>This function can return multiple addresses for multihomed
 641	  sockets, such as SCTP sockets. For other sockets it
 642	  returns a one-element list.</p>
 643	<p>Notice that parameter <c><anno>Assoc</anno></c> is by the
 644	  <url href="http://tools.ietf.org/html/draft-ietf-tsvwg-sctpsocket-13">SCTP Sockets API Extensions</url>
 645	  defined to be ignored for
 646	  one-to-one style sockets. What the special value <c>0</c>
 647	  means, hence its behavior for one-to-many style sockets,
 648	  is unfortunately undefined.</p>
 649      </desc>
 650    </func>
 651
 652    <func>
 653      <name name="port" arity="1"/>
 654      <fsummary>Return the local port number for a socket.</fsummary>
 655      <desc>
 656        <p>Returns the local port number for a socket.</p>
 657      </desc>
 658    </func>
 659
 660    <func>
 661      <name name="setopts" arity="2"/>
 662      <fsummary>Set one or more options for a socket.</fsummary>
 663      <desc>
 664        <p>Sets one or more options for a socket.</p>
 665        <p>The following options are available:</p>
 666        <taglist>
 667          <tag><c>{active, true | false | once | N}</c></tag>
 668          <item>
 669            <p>If the value is <c>true</c>, which is the default,
 670              everything received from the socket is sent as
 671              messages to the receiving process.</p>
 672            <p>If the value is <c>false</c> (passive mode), the process must
 673              explicitly receive incoming data by calling
 674              <seealso marker="gen_tcp#recv/2"><c>gen_tcp:recv/2,3</c></seealso>,
 675              <seealso marker="gen_udp#recv/2"><c>gen_udp:recv/2,3</c></seealso>,
 676              or <seealso marker="gen_sctp#recv/1"><c>gen_sctp:recv/1,2</c></seealso>
 677              (depending on the type of socket).</p>
 678            <p>If the value is <c>once</c> (<c>{active, once}</c>),
 679              <em>one</em> data message from the socket is sent
 680              to the process. To receive one more message,
 681              <c>setopts/2</c> must be called again with option
 682              <c>{active, once}</c>.</p>
 683            <p>If the value is an integer <c>N</c> in the range -32768 to 32767
 684              (inclusive), the value is added to the socket's count of data
 685              messages sent to the controlling process. A socket's default
 686              message count is <c>0</c>. If a negative value is specified, and
 687              its magnitude is equal to or greater than the socket's current
 688              message count, the socket's message count is set to <c>0</c>.
 689              Once the socket's message count reaches <c>0</c>, either because
 690              of sending
 691              received data messages to the process or by being explicitly set,
 692              the process is then notified by a special message, specific to
 693              the type of socket, that the socket has entered passive
 694              mode. Once the socket enters passive mode, to receive more
 695              messages <c>setopts/2</c> must be called again to set the
 696              socket back into an active mode.</p>
 697            <p>When using <c>{active, once}</c> or <c>{active, N}</c>, the
 698              socket changes behavior automatically when data is received.
 699              This can be confusing in combination with connection-oriented
 700              sockets (that is, <c>gen_tcp</c>), as a socket
 701              with <c>{active, false}</c> behavior reports closing
 702              differently than a socket with <c>{active, true}</c>
 703              behavior. To simplify programming, a socket where
 704              the peer closed, and this is detected while in
 705              <c>{active, false}</c> mode, still generates message
 706              <c>{tcp_closed,Socket}</c> when set to <c>{active, once}</c>,
 707              <c>{active, true}</c>, or <c>{active, N}</c> mode.
 708              It is therefore safe to assume that message
 709              <c>{tcp_closed,Socket}</c>, possibly followed by socket port
 710              termination (depending on option <c>exit_on_close</c>)
 711              eventually appears when a socket changes
 712              back and forth between <c>{active, true}</c> and
 713              <c>{active, false}</c> mode. However,
 714              <em>when</em> peer closing is detected it is all up to the
 715              underlying TCP/IP stack and protocol.</p>
 716            <p>Notice that <c>{active, true}</c> mode provides no flow
 717              control; a fast sender can easily overflow the
 718              receiver with incoming messages. The same is true for
 719              <c>{active, N}</c> mode, while the message count is greater
 720              than zero.</p>
 721            <p>Use active mode only if
 722              your high-level protocol provides its own flow control
 723              (for example, acknowledging received messages) or the
 724              amount of data exchanged is small. <c>{active, false}</c>
 725              mode, use of the <c>{active, once}</c> mode, or <c>{active, N}</c>
 726              mode with values of <c>N</c> appropriate for the application
 727              provides flow control. The other side cannot send
 728              faster than the receiver can read.</p>
 729          </item>
 730          <tag><c>{broadcast, Boolean}</c> (UDP sockets)</tag>
 731          <item>
 732            <p>Enables/disables permission to send broadcasts.</p>
 733            <marker id="option-buffer"></marker>
 734          </item>
 735          <tag><c>{buffer, Size}</c></tag>
 736          <item>
 737            <p>The size of the user-level software buffer used by
 738              the driver. 
 739              Not to be confused with options <c>sndbuf</c>
 740              and <c>recbuf</c>, which correspond to the
 741              Kernel socket buffers. It is recommended
 742              to have <c>val(buffer) &gt;= max(val(sndbuf),val(recbuf))</c> to
 743              avoid performance issues because of unnecessary copying.
 744              <c>val(buffer)</c> is automatically set to the above
 745              maximum when values <c>sndbuf</c> or <c>recbuf</c> are set.
 746              However, as the sizes set for <c>sndbuf</c> and <c>recbuf</c>
 747              usually become larger, you are encouraged to use
 748              <seealso marker="#getopts/2"><c>getopts/2</c></seealso>
 749              to analyze the behavior of your operating system.</p>
 750            <p>Note that this is also the maximum amount of data that can be
 751	       received from a single recv call. If you are using higher than 
 752	       normal MTU consider setting buffer higher.</p> 
 753          </item>
 754          <tag><c>{delay_send, Boolean}</c></tag>
 755          <item>
 756            <p>Normally, when an Erlang process sends to a socket,
 757              the driver tries to send the data immediately. If that
 758              fails, the driver uses any means available to queue
 759              up the message to be sent whenever the operating system
 760              says it can handle it. Setting <c>{delay_send, true}</c>
 761              makes <em>all</em> messages queue up. The messages sent
 762              to the network are then larger but fewer.
 763              The option affects the scheduling of send
 764              requests versus Erlang processes instead of changing any
 765              real property of the socket. The option is
 766              implementation-specific. Defaults to <c>false</c>.</p>
 767          </item>
 768          <tag><c>{deliver, port | term}</c></tag>
 769          <item>
 770            <p>When <c>{active, true}</c>, data is delivered on the form
 771              <c>port</c> : <c>{S, {data, [H1,..Hsz | Data]}}</c> or
 772              <c>term</c> : <c>{tcp, S, [H1..Hsz | Data]}</c>.</p>
 773          </item>
 774          <tag><c>{dontroute, Boolean}</c></tag>
 775          <item>
 776            <p>Enables/disables routing bypass for outgoing messages.</p>
 777          </item>
 778          <tag><c>{exit_on_close, Boolean}</c></tag>
 779          <item>
 780            <p>This option is set to <c>true</c> by default.</p>
 781            <p>The only reason to set it to <c>false</c> is if you want
 782              to continue sending data to the socket after a close is
 783              detected, for example, if the peer uses
 784              <seealso marker="gen_tcp#shutdown/2"><c>gen_tcp:shutdown/2</c></seealso>
 785              to shut down the write side.</p>
 786          </item>
 787          <tag><c>{header, Size}</c></tag>
 788          <item>
 789            <p>This option is only meaningful if option <c>binary</c>
 790              was specified when the socket was created. If option
 791              <c>header</c> is specified, the first
 792              <c>Size</c> number bytes of data received from the socket
 793              are elements of a list, and the remaining data is
 794              a binary specified as the tail of the same list. For example,
 795              if <c>Size == 2</c>, the data received matches
 796              <c>[Byte1,Byte2|Binary]</c>.</p>
 797          </item>
 798          <tag><c>{high_msgq_watermark, Size}</c></tag>
 799          <item>
 800	    <p>The socket message queue is set to a busy
 801	      state when the amount of data on the message
 802	      queue reaches this limit. Notice that this limit only
 803	      concerns data that has not yet reached the ERTS internal
 804	      socket implementation. Defaults to 8 kB.</p>
 805	    <p>Senders of data to the socket are suspended if
 806	      either the socket message queue is busy or the socket
 807	      itself is busy.</p>
 808	    <p>For more information, see options <c>low_msgq_watermark</c>,
 809	      <c>high_watermark</c>, and <c>low_watermark</c>.</p>
 810	    <p>Notice that distribution sockets disable the use of
 811	      <c>high_msgq_watermark</c> and <c>low_msgq_watermark</c>.
 812	      Instead use the
 813	      <seealso marker="erts:erlang#system_info_dist_buf_busy_limit">distribution buffer busy limit</seealso>,
 814              which is a similar feature.</p>
 815          </item>
 816          <tag><c>{high_watermark, Size}</c> (TCP/IP sockets)</tag>
 817          <item>
 818	    <p>The socket is set to a busy state when the amount
 819	      of data queued internally by the ERTS socket implementation
 820	      reaches this limit. Defaults to 8 kB.</p>
 821	    <p>Senders of data to the socket are suspended if
 822	      either the socket message queue is busy or the socket
 823	      itself is busy.</p>
 824	    <p>For more information, see options <c>low_watermark</c>,
 825	      <c>high_msgq_watermark</c>, and <c>low_msqg_watermark</c>.</p>
 826          </item>
 827	  <tag><c>{ipv6_v6only, Boolean}</c></tag>
 828	  <item>
 829	    <p>Restricts the socket to use only IPv6, prohibiting any
 830	      IPv4 connections. This is only applicable for
 831	      IPv6 sockets (option <c>inet6</c>).</p>
 832            <p>On most platforms this option must be set on the socket
 833	      before associating it to an address. It is therefore only
 834	      reasonable to specify it when creating the socket and not
 835	      to use it when calling function
 836	      (<seealso marker="#setopts/2"><c>setopts/2</c></seealso>)
 837	      containing this description.</p>
 838	    <p>The behavior of a socket with this option set to
 839	      <c>true</c> is the only portable one. The original
 840	      idea when IPv6 was new of using IPv6 for all traffic
 841	      is now not recommended by FreeBSD (you can use
 842	      <c>{ipv6_v6only,false}</c> to override the recommended
 843	      system default value),
 844	      forbidden by OpenBSD (the supported GENERIC kernel),
 845	      and impossible on Windows (which has separate
 846	      IPv4 and IPv6 protocol stacks). Most Linux distros
 847	      still have a system default value of <c>false</c>.
 848	      This policy shift among operating systems to
 849	      separate IPv6 from IPv4 traffic has evolved, as
 850	      it gradually proved hard and complicated to get
 851	      a dual stack implementation correct and secure.</p>
 852	    <p>On some platforms, the only allowed value for this option
 853	      is <c>true</c>, for example, OpenBSD and Windows. Trying to set
 854	      this option to <c>false</c>, when creating the socket, fails
 855	      in this case.</p>
 856	    <p>Setting this option on platforms where it does not exist
 857	      is ignored. Getting this option with
 858	      <seealso marker="#getopts/2"><c>getopts/2</c></seealso>
 859	      returns no value, that is, the returned list does not contain an
 860	      <c>{ipv6_v6only,_}</c> tuple. On Windows, the option
 861	      does not exist, but it is emulated as a
 862	      read-only option with value <c>true</c>.</p>
 863	    <p>Therefore, setting this option to <c>true</c>
 864	      when creating a socket never fails, except possibly on a
 865              platform where you
 866	      have customized the kernel to only allow <c>false</c>,
 867	      which can be doable (but awkward) on, for example, OpenBSD.</p>
 868	    <p>If you read back the option value using
 869	      <seealso marker="#getopts/2"><c>getopts/2</c></seealso>
 870	      and get no value, the option does not exist in the host
 871              operating system. The behavior of both an IPv6 and an IPv4
 872	      socket listening on the same port, and for an IPv6 socket
 873	      getting IPv4 traffic is then no longer predictable.</p>
 874	  </item>
 875          <tag><c>{keepalive, Boolean}</c>(TCP/IP sockets)</tag>
 876          <item>
 877            <p>Enables/disables periodic transmission on a connected
 878              socket when no other data is exchanged. If
 879              the other end does not respond, the connection is
 880              considered broken and an error message is sent to
 881              the controlling process. Defaults to <c>disabled</c>.</p>
 882            <marker id="option-linger"></marker>
 883          </item>
 884          <tag><c>{linger, {true|false, Seconds}}</c></tag>
 885          <item>
 886            <p>Determines the time-out, in seconds, for flushing unsent data
 887              in the <c>close/1</c> socket call. If the first component of
 888              the value tuple is <c>false</c>, the second is ignored. This
 889              means that <c>close/1</c> returns immediately, not waiting
 890              for data to be flushed. Otherwise, the second component is
 891              the flushing time-out, in seconds.</p>
 892          </item>
 893          <tag><c>{low_msgq_watermark, Size}</c></tag>
 894          <item>
 895	    <p>If the socket message queue is in a busy state, the
 896	      socket message queue is set in a not busy state when
 897	      the amount of data queued in the message queue falls
 898	      below this limit. Notice that this limit only concerns data
 899	      that has not yet reached the ERTS internal socket
 900	      implementation. Defaults to 4 kB.</p>
 901	    <p>Senders that are suspended because of either a
 902	      busy message queue or a busy socket are resumed
 903	      when the socket message queue and the socket
 904	      are not busy.</p>
 905	    <p>For more information, see options <c>high_msgq_watermark</c>,
 906	      <c>high_watermark</c>, and <c>low_watermark</c>.</p>
 907	    <p>Notice that distribution sockets disable the use of
 908	      <c>high_msgq_watermark</c> and <c>low_msgq_watermark</c>.
 909	      Instead they use the
 910	      <seealso marker="erts:erlang#system_info_dist_buf_busy_limit">distribution
 911	      buffer busy limit</seealso>, which is a similar feature.</p>
 912          </item>
 913          <tag><c>{low_watermark, Size}</c> (TCP/IP sockets)</tag>
 914          <item>
 915	    <p>If the socket is in a busy state, the socket is
 916	      set in a not busy state when the amount of data
 917	      queued internally by the ERTS socket implementation
 918	      falls below this limit. Defaults to 4 kB.</p>
 919	    <p>Senders that are suspended because of a
 920	      busy message queue or a busy socket are resumed
 921	      when the socket message queue and the socket are not busy.</p>
 922	    <p>For more information, see options <c>high_watermark</c>,
 923	      <c>high_msgq_watermark</c>, and <c>low_msgq_watermark</c>.</p>
 924          </item>
 925          <tag><c>{mode, Mode :: binary | list}</c></tag>
 926          <item>
 927            <p>Received <c>Packet</c> is delivered as defined by <c>Mode</c>.
 928            </p>
 929          </item>
 930	  <tag><c>{netns, Namespace :: file:filename_all()}</c></tag>
 931	  <item>
 932	    <p>Sets a network namespace for the socket. Parameter
 933	      <c>Namespace</c> is a filename defining the namespace, for
 934	      example, <c>"/var/run/netns/example"</c>, typically created by
 935	      command <c>ip netns add example</c>. This option must be used in
 936	      a function call that creates a socket, that is,
 937	      <seealso marker="gen_tcp#connect/3"><c>gen_tcp:connect/3,4</c></seealso>,
 938	      <seealso marker="gen_tcp#listen/2"><c>gen_tcp:listen/2</c></seealso>,
 939	      <seealso marker="gen_udp#open/1"><c>gen_udp:open/1,2</c></seealso>, or
 940	    <seealso marker="gen_sctp#open/0"><c>gen_sctp:open/0,1,2</c></seealso>.</p>
 941	    <p>This option uses the Linux-specific syscall
 942	      <c>setns()</c>, such as in Linux kernel 3.0 or later,
 943	      and therefore only exists when the runtime system
 944	      is compiled for such an operating system.</p>
 945	    <p>The virtual machine also needs elevated privileges, either
 946	      running as superuser or (for Linux) having capability
 947	      <c>CAP_SYS_ADMIN</c> according to the documentation for
 948	      <c>setns(2)</c>.
 949	      However, during testing also <c>CAP_SYS_PTRACE</c>
 950	      and <c>CAP_DAC_READ_SEARCH</c> have proven to be necessary.</p>
 951            <p><em>Example:</em></p>
 952	    <code>
 953setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp</code>
 954            <p>Notice that the filesystem containing the virtual machine
 955	      executable (<c>beam.smp</c> in the example) must be local,
 956	      mounted without flag <c>nosetuid</c>,
 957	      support extended attributes, and
 958	      the kernel must support file capabilities.
 959	      All this runs out of the box on at least Ubuntu 12.04 LTS,
 960	      except that SCTP sockets appear to not support
 961	      network namespaces.</p>
 962	    <p><c>Namespace</c> is a filename and is encoded
 963	      and decoded as discussed in module
 964	      <seealso marker="file">file</seealso>, with the
 965              following exceptions:</p>
 966	    <list type="bulleted">
 967	      <item><p>Emulator flag <c>+fnu</c> is ignored.</p></item>
 968	      <item><p><seealso marker="#getopts/2"><c>getopts/2</c></seealso>
 969	      for this option returns a binary for the filename if the stored
 970	      filename cannot be decoded. This is only to occur if you set the
 971	      option using a binary that cannot be decoded with the emulator's
 972	      filename encoding:
 973	      <seealso marker="file#native_name_encoding/0"><c>file:native_name_encoding/0</c></seealso>.</p></item>
 974	    </list>
 975          </item>
 976	  <tag><c>{bind_to_device, Ifname :: binary()}</c></tag>
 977	  <item>
 978	    <p>Binds a socket to a specific network interface. This option
 979	      must be used in a function call that creates a socket, that is,
 980	      <seealso marker="gen_tcp#connect/3"><c>gen_tcp:connect/3,4</c></seealso>,
 981	      <seealso marker="gen_tcp#listen/2"><c>gen_tcp:listen/2</c></seealso>,
 982	      <seealso marker="gen_udp#open/1"><c>gen_udp:open/1,2</c></seealso>, or
 983	      <seealso marker="gen_sctp#open/0"><c>gen_sctp:open/0,1,2</c></seealso>.</p>
 984	    <p>Unlike <seealso marker="#getifaddrs/0"><c>getifaddrs/0</c></seealso>, Ifname
 985	      is encoded a binary. In the unlikely case that a system is using
 986	      non-7-bit-ASCII characters in network device names, special care
 987	      has to be taken when encoding this argument.</p>
 988	    <p>This option uses the Linux-specific socket option
 989	      <c>SO_BINDTODEVICE</c>, such as in Linux kernel 2.0.30 or later,
 990	      and therefore only exists when the runtime system
 991	      is compiled for such an operating system.</p>
 992	    <p>Before Linux 3.8, this socket option could be set, but could not retrieved
 993	      with <seealso marker="#getopts/2"><c>getopts/2</c></seealso>. Since Linux 3.8,
 994	      it is readable.</p>
 995	    <p>The virtual machine also needs elevated privileges, either
 996	      running as superuser or (for Linux) having capability
 997	    <c>CAP_NET_RAW</c>.</p>
 998	    <p>The primary use case for this option is to bind sockets into
 999	      <url href="http://www.kernel.org/doc/Documentation/networking/vrf.txt">Linux VRF instances</url>.
1000	    </p>
1001	  </item>
1002          <tag><c>list</c></tag>
1003          <item>
1004            <p>Received <c>Packet</c> is delivered as a list.</p>
1005          </item>
1006          <tag><c>binary</c></tag>
1007          <item>
1008            <p>Received <c>Packet</c> is delivered as a binary.</p>
1009          </item>
1010          <tag><c>{nodelay, Boolean}</c>(TCP/IP sockets)</tag>
1011          <item>
1012            <p>If <c>Boolean == true</c>, option <c>TCP_NODELAY</c>
1013              is turned on for the socket, which means that also small
1014              amounts of data are sent immediately.</p>
1015          </item>
1016          <tag><c>{packet, PacketType}</c>(TCP/IP sockets)</tag>
1017          <item>
1018            <p><marker id="packet"/>Defines the type of packets to use for a socket.
1019	      Possible values:</p>
1020            <taglist>
1021              <tag><c>raw | 0</c></tag>
1022              <item>
1023                <p>No packaging is done.</p>
1024              </item>
1025              <tag><c>1 | 2 | 4</c></tag>
1026              <item>
1027                <p>Packets consist of a header specifying the number of
1028                  bytes in the packet, followed by that number of bytes.
1029                  The header length can be one, two, or four bytes, and
1030                  containing an unsigned integer in big-endian byte order.
1031                  Each send operation generates the header, and the header
1032                  is stripped off on each receive operation.</p>
1033                <p>The 4-byte header is limited to 2Gb.</p>
1034              </item>
1035              <tag><c>asn1 | cdr | sunrm | fcgi | tpkt | line</c></tag>
1036              <item>
1037                <p>These packet types only have effect on receiving.
1038                  When sending a packet, it is the responsibility of
1039                  the application to supply a correct header. On
1040                  receiving, however, one message is sent to
1041                  the controlling process for each complete packet
1042                  received, and, similarly, each call to
1043                  <c>gen_tcp:recv/2,3</c> returns one complete packet.
1044                  The header is <em>not</em> stripped off.</p>
1045                <p>The meanings of the packet types are as follows:</p>
1046		<list type="bulleted">
1047		  <item><c>asn1</c> - ASN.1 BER</item>
1048		  <item><c>sunrm</c> - Sun's RPC encoding</item>
1049		  <item><c>cdr</c> - CORBA (GIOP 1.1)</item>
1050		  <item><c>fcgi</c> - Fast CGI</item>
1051		  <item><c>tpkt</c> - TPKT format [RFC1006]</item>
1052		  <item><c>line</c> - Line mode, a packet is a line-terminated
1053		    with newline, lines longer than the receive buffer are
1054		    truncated</item>
1055		</list>
1056	      </item>
1057              <tag><c>http | http_bin</c></tag>
1058              <item>
1059                <p>The Hypertext Transfer Protocol. The packets
1060                 are returned with the format according to <c>HttpPacket</c>
1061                 described in
1062                 <seealso marker="erts:erlang#decode_packet/3">
1063                 <c>erlang:decode_packet/3</c></seealso> in ERTS.
1064                 A socket in passive
1065                 mode returns <c>{ok, HttpPacket}</c> from <c>gen_tcp:recv</c>
1066                 while an active socket sends messages like
1067		 <c>{http, Socket, HttpPacket}</c>.</p>
1068              </item>
1069              <tag><c>httph | httph_bin</c></tag>
1070              <item>
1071                <p>These two types are often not needed, as the socket
1072		automatically switches from <c>http</c>/<c>http_bin</c> to
1073		<c>httph</c>/<c>httph_bin</c> internally after the first line
1074		is read. However, there can be occasions when they are
1075		useful, such as parsing trailers from chunked encoding.</p>
1076              </item>
1077            </taglist>
1078          </item>
1079          <tag><c>{packet_size, Integer}</c>(TCP/IP sockets)</tag>
1080          <item>
1081            <p>Sets the maximum allowed length of the packet body. If
1082              the packet header indicates that the length of the packet
1083              is longer than the maximum allowed length, the packet is
1084              considered invalid. The same occurs if the packet header
1085              is too large for the socket receive buffer.</p>
1086	    <p>For line-oriented protocols (<c>line</c>, <c>http*</c>),
1087	      option <c>packet_size</c> also guarantees that lines up to the
1088	      indicated length are accepted and not considered invalid
1089	      because of internal buffer limitations.</p>
1090          </item>
1091          <tag><c>{line_delimiter, Char}</c>(TCP/IP sockets)</tag>
1092          <item>
1093            <p>Sets the line delimiting character for line-oriented protocols
1094              (<c>line</c>). Defaults to <c>$\n</c>.</p>
1095          </item>
1096          <tag><c>{raw, Protocol, OptionNum, ValueBin}</c></tag>
1097          <item>
1098            <p>See below.</p>
1099          </item>
1100          <tag><c>{read_packets, Integer}</c>(UDP sockets)</tag>
1101          <item>
1102            <p>Sets the maximum number of UDP packets to read without
1103              intervention from the socket when data is available.
1104              When this many packets have been read and delivered
1105              to the destination process, new packets are not read
1106              until a new notification of available data has arrived.
1107              Defaults to <c>5</c>. If this parameter is set too
1108              high, the system can become unresponsive because of
1109              UDP packet flooding.</p>
1110          </item>
1111          <tag><c>{recbuf, Size}</c></tag>
1112          <item>
1113            <p>The minimum size of the receive buffer to use for
1114              the socket. You are encouraged to use
1115              <seealso marker="#getopts/2"><c>getopts/2</c></seealso>
1116              to retrieve the size set by your operating system.</p>
1117          </item>
1118          <tag><c>{reuseaddr, Boolean}</c></tag>
1119          <item>
1120            <p>Allows or disallows local reuse of port numbers. By
1121              default, reuse is disallowed.</p>
1122          </item>
1123          <tag><c>{send_timeout, Integer}</c></tag>
1124          <item>
1125            <p>Only allowed for connection-oriented sockets.</p>
1126

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