/lib/kernel/doc/src/inet.xml
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) >= 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