1inet(3) Erlang Module Definition inet(3)
2
6 inet - Access to TCP/IP protocols.
7
9 This module provides access to TCP/IP protocols.
10 See also ERTS User's Guide: Inet Configuration for more information
12 about how to configure an Erlang runtime system for IP communication.
13 The following two Kernel configuration parameters affect the behavior
15 of all sockets opened on an Erlang node:
16 * inet_default_connect_options can contain a list of default options
18 used for all sockets returned when doing connect.
19 * inet_default_listen_options can contain a list of default options
21 used when issuing a listen call.
22 When accept is issued, the values of the listening socket options are
24 inherited. No such application variable is therefore needed for accept.
25 Using the Kernel configuration parameters above, one can set default
27 options for all TCP sockets on a node, but use this with care. Options
28 such as {delay_send,true} can be specified in this way. The following
29 is an example of starting an Erlang node with all sockets using delayed
30 send:
31 $ erl -sname test -kernel \
33 inet_default_connect_options '[{delay_send,true}]' \
34 inet_default_listen_options '[{delay_send,true}]'
35 Notice that default option {active, true} cannot be changed, for inter‐
37 nal reasons.
38 Addresses as inputs to functions can be either a string or a tuple. For
40 example, the IP address 150.236.20.73 can be passed to gethostbyaddr/1,
41 either as string "150.236.20.73" or as tuple {150, 236, 20, 73}.
42 IPv4 address examples:
44 Address ip_address()
46 ------- ------------
47 127.0.0.1 {127,0,0,1}
48 192.168.42.2 {192,168,42,2}
49 IPv6 address examples:
51 Address ip_address()
53 ------- ------------
54 ::1 {0,0,0,0,0,0,0,1}
55 ::192.168.42.2 {0,0,0,0,0,0,(192 bsl 8) bor 168,(42 bsl 8) bor 2}
56 ::FFFF:192.168.42.2
57 {0,0,0,0,0,16#FFFF,(192 bsl 8) bor 168,(42 bsl 8) bor 2}
58 3ffe:b80:1f8d:2:204:acff:fe17:bf38
59 {16#3ffe,16#b80,16#1f8d,16#2,16#204,16#acff,16#fe17,16#bf38}
60 fe80::204:acff:fe17:bf38
61 {16#fe80,0,0,0,16#204,16#acff,16#fe17,16#bf38}
62 Function parse_address/1 can be useful:
64 1> inet:parse_address("192.168.42.2").
66 {ok,{192,168,42,2}}
67 2> inet:parse_address("::FFFF:192.168.42.2").
68 {ok,{0,0,0,0,0,65535,49320,10754}}
69
71 Exported data types
72 hostent() =
73 #hostent{h_name = inet:hostname(),
74 h_aliases = [inet:hostname()],
75 h_addrtype = inet | inet6,
76 h_length = integer() >= 0,
77 h_addr_list = [inet:ip_address()]}
78 The record is defined in the Kernel include file "inet.hrl".
80 Add the following directive to the module:
82 -include_lib("kernel/include/inet.hrl").
84 hostname() = atom() | string()
86 ip_address() = ip4_address() | ip6_address()
88 ip4_address() = {0..255, 0..255, 0..255, 0..255}
90 ip6_address() =
92 {0..65535,
93 0..65535,
94 0..65535,
95 0..65535,
96 0..65535,
97 0..65535,
98 0..65535,
99 0..65535}
100 port_number() = 0..65535
102 family_address() =
104 inet_address() | inet6_address() | local_address()
105 A general address format on the form {Family, Destination} where
107 Family is an atom such as local and the format of Destination
108 depends on Family, and is a complete address (for example an IP
109 address including port number).
110 local_address() = {local, File :: binary() | string()}
112 This address family only works on Unix-like systems.
114 File is normally a file pathname in a local filesystem. It is
116 limited in length by the operating system, traditionally to 108
117 bytes.
118 A binary() is passed as is to the operating system, but a
120 string() is encoded according to the system filename encoding
121 mode.
122 Other addresses are possible, for example Linux implements "Ab‐
124 stract Addresses". See the documentation for Unix Domain Sockets
125 on your system, normally unix in manual section 7.
126 In most API functions where you can use this address family the
128 port number must be 0.
129 inet_backend() = {inet_backend, inet | socket}
131 Select the implementation backend for sockets. The current de‐
133 fault is inet which at the bottom uses inet_drv.c to call the
134 platform's socket API. The value socket instead at the bottom
135 uses the socket module and its NIF implementation.
136 This is a temporary option that will be ignored in a future re‐
138 lease.
139 socket_address() =
141 ip_address() | any | loopback | local_address()
142 socket_getopt() =
144 gen_sctp:option_name() |
145 gen_tcp:option_name() |
146 gen_udp:option_name()
147 socket_setopt() =
149 gen_sctp:option() | gen_tcp:option() | gen_udp:option()
150 socket_optval() =
152 gen_sctp:option_value() |
153 gen_tcp:option() |
154 gen_udp:option() |
155 gen_tcp:pktoptions_value()
156 returned_non_ip_address() =
158 {local, binary()} | {unspec, <<>>} | {undefined, any()}
159 Addresses besides ip_address() ones that are returned from
161 socket API functions. See in particular local_address(). The
162 unspec family corresponds to AF_UNSPEC and can occur if the
163 other side has no socket address. The undefined family can only
164 occur in the unlikely event of an address family that the VM
165 does not recognize.
166 ancillary_data() =
168 [{tos, byte()} | {tclass, byte()} | {ttl, byte()}]
169 Ancillary data received with the data packet, read with the
171 socket option pktoptions from a TCP socket, or to set in a call
172 to gen_udp:send/4 or gen_udp:send/5.
173 The value(s) correspond to the currently active socket options
175 recvtos, recvtclass and recvttl, or for a single send operation
176 the option(s) to override the currently active socket option(s).
177 posix() =
179 eaddrinuse | eaddrnotavail | eafnosupport | ealready |
180 econnaborted | econnrefused | econnreset | edestaddrreq |
181 ehostdown | ehostunreach | einprogress | eisconn | emsgsize |
182 enetdown | enetunreach | enopkg | enoprotoopt | enotconn |
183 enotty | enotsock | eproto | eprotonosupport | eprototype |
184 esocktnosupport | etimedout | ewouldblock | exbadport |
185 exbadseq |
186 file:posix()
187 An atom that is named from the POSIX error codes used in Unix,
189 and in the runtime libraries of most C compilers. See section
190 POSIX Error Codes.
191 socket()
193 See gen_tcp:type-socket and gen_udp:type-socket.
195 address_family() = inet | inet6 | local
197 socket_protocol() = tcp | udp | sctp
199 stat_option() =
201 recv_cnt | recv_max | recv_avg | recv_oct | recv_dvi |
202 send_cnt | send_max | send_avg | send_oct | send_pend
203
205 Internal data types
206 inet_address() =
207 {inet, {ip4_address() | any | loopback, port_number()}}
208 Warning:
210 This address format is for now experimental and for completeness
211 to make all address families have a {Family, Destination} repre‐
212 sentation.
213 inet6_address() =
216 {inet6, {ip6_address() | any | loopback, port_number()}}
217 Warning:
219 This address format is for now experimental and for completeness
220 to make all address families have a {Family, Destination} repre‐
221 sentation.
222 getifaddrs_ifopts() =
225 [Ifopt ::
226 {flags,
227 Flags ::
228 [up | broadcast | loopback | pointtopoint |
229 running | multicast]} |
230 {addr, Addr :: ip_address()} |
231 {netmask, Netmask :: ip_address()} |
232 {broadaddr, Broadaddr :: ip_address()} |
233 {dstaddr, Dstaddr :: ip_address()} |
234 {hwaddr, Hwaddr :: [byte()]}]
235 Interface address description list returned from getifaddrs/0,1
237 for a named interface, translated from the returned data of the
238 POSIX API function getaddrinfo().
239 Hwaddr is hardware dependent, for example, on Ethernet inter‐
241 faces it is the 6-byte Ethernet address (MAC address (EUI-48 ad‐
242 dress)).
243 The tuples {addr,Addr}, {netmask,Netmask}, and possibly {broad‐
245 addr,Broadaddr} or {dstaddr,Dstaddr} are repeated in the list if
246 the interface has got multiple addresses. An interface may have
247 multiple {flag,_} tuples for example if it has different flags
248 for different address families. Multiple {hwaddr,Hwaddr} tuples
249 is hard to say anything definite about, though. The tuple
250 {flag,Flags} is mandatory, all others are optional.
251 Do not rely too much on the order of Flags atoms or the Ifopt
253 tuples. There are however some rules:
254 * A {flag,_} tuple applies to all other tuples that follow.
256 * Immediately after {addr,_} follows {netmask,_}.
258 * Immediately thereafter may {broadaddr,_} follow if broadcast
260 is member of Flags, or {dstaddr,_} if pointtopoint is member
261 of Flags. Both {dstaddr,_} and {broadaddr,_} does not occur
262 for the same {addr,_}.
263 * Any {netmask,_}, {broadaddr,_}, or {dstaddr,_} tuples that
265 follow an {addr,Addr} tuple concerns the address Addr.
266 The tuple {hwaddr,_} is not returned on Solaris, as the hardware
268 address historically belongs to the link layer and it is not re‐
269 turned by the Solaris API function getaddrinfo().
270 Warning:
272 On Windows, the data is fetched from different OS API functions,
273 so the Netmask and Broadaddr values may be calculated, just as
274 some Flags values.
275
278 close(Socket) -> ok
279 Types:
281 Socket = socket()
283 Closes a socket of any type.
285 cancel_monitor(MRef) -> boolean()
287 Types:
289 MRef = reference()
291 If MRef is a reference that the calling process obtained by
293 calling monitor/1, this monitor is turned off. If the monitoring
294 is already turned off, nothing happens.
295 The returned value is one of the following:
297 true:
299 The monitor was found and removed. In this case, no 'DOWN'
300 message corresponding to this monitor has been delivered and
301 will not be delivered.
302 false:
304 The monitor was not found and could not be removed. This
305 probably because a 'DOWN' message corresponding to this mon‐
306 itor has already been placed in the caller message queue.
307 Failure: It is an error if MRef refers to a monitor started by
309 another process.
310 format_error(Reason) -> string()
312 Types:
314 Reason = posix() | system_limit
316 Returns a diagnostic error string. For possible POSIX values and
318 corresponding strings, see section POSIX Error Codes.
319 get_rc() ->
321 [{Par :: atom(), Val :: any()} |
322 {Par :: atom(), Val1 :: any(), Val2 :: any()}]
323 Returns the state of the Inet configuration database in form of
325 a list of recorded configuration parameters. For more informa‐
326 tion, see ERTS User's Guide: Inet Configuration.
327 Only actual parameters with other than default values are re‐
329 turned, for example not directives that specify other sources
330 for configuration parameters nor directives that clear parame‐
331 ters.
332 getaddr(Host, Family) -> {ok, Address} | {error, posix()}
334 Types:
336 Host = ip_address() | hostname()
338 Family = address_family()
339 Address = ip_address()
340 Returns the IP address for Host as a tuple of integers. Host can
342 be an IP address, a single hostname, or a fully qualified host‐
343 name.
344 getaddrs(Host, Family) -> {ok, Addresses} | {error, posix()}
346 Types:
348 Host = ip_address() | hostname()
350 Family = address_family()
351 Addresses = [ip_address()]
352 Returns a list of all IP addresses for Host. Host can be an IP
354 address, a single hostname, or a fully qualified hostname.
355 gethostbyaddr(Address) -> {ok, Hostent} | {error, posix()}
357 Types:
359 Address = string() | ip_address()
361 Hostent = hostent()
362 Returns a hostent record for the host with the specified ad‐
364 dress.
365 gethostbyname(Hostname) -> {ok, Hostent} | {error, posix()}
367 Types:
369 Hostname = hostname()
371 Hostent = hostent()
372 Returns a hostent record for the host with the specified host‐
374 name.
375 If resolver option inet6 is true, an IPv6 address is looked up.
377 gethostbyname(Hostname, Family) ->
379 {ok, Hostent} | {error, posix()}
380 Types:
382 Hostname = hostname()
384 Family = address_family()
385 Hostent = hostent()
386 Returns a hostent record for the host with the specified name,
388 restricted to the specified address family.
389 gethostname() -> {ok, Hostname}
391 Types:
393 Hostname = string()
395 Returns the local hostname. Never fails.
397 getifaddrs() ->
399 {ok,
400 [{Ifname :: string(),
401 Ifopts :: getifaddrs_ifopts()}]} |
402 {error, posix()}
403 Returns a list of 2-tuples containing interface names and the
405 interfaces' addresses. Ifname is a Unicode string and Ifopts is
406 a list of interface address description tuples.
407 The interface address description tuples are documented under
409 the type of the Ifopts value.
410 getifaddrs(Opts) -> {ok, [{Ifname, Ifopts}]} | {error, Posix}
412 Types:
414 Opts = [{netns, Namespace}]
416 Namespace = file:filename_all()
417 Ifname = string()
418 Ifopts = getifaddrs_ifopts()
419 Posix = posix()
420 The same as getifaddrs/0 but the Option {netns, Namespace} sets
422 a network namespace for the OS call, on platforms that supports
423 that feature.
424 See the socket option {netns, Namespace} under setopts/2.
426 getopts(Socket, Options) -> {ok, OptionValues} | {error, posix()}
428 Types:
430 Socket = socket()
432 Options = [socket_getopt()]
433 OptionValues = [socket_optval()]
434 Gets one or more options for a socket. For a list of available
436 inet options, see setopts/2. See also the descriptions for the
437 protocol specific types referenced by socket_optval().
438 The number of elements in the returned OptionValues list does
440 not necessarily correspond to the number of options asked for.
441 If the operating system fails to support an option, it is left
442 out in the returned list. An error tuple is returned only when
443 getting options for the socket is impossible (that is, the
444 socket is closed or the buffer size in a raw request is too
445 large). This behavior is kept for backward compatibility rea‐
446 sons.
447 A raw option request RawOptReq = {raw, Protocol, OptionNum, Val‐
449 ueSpec} can be used to get information about socket options not
450 (explicitly) supported by the emulator. The use of raw socket
451 options makes the code non-portable, but allows the Erlang pro‐
452 grammer to take advantage of unusual features present on a par‐
453 ticular platform.
454 RawOptReq consists of tag raw followed by the protocol level,
456 the option number, and either a binary or the size, in bytes, of
457 the buffer in which the option value is to be stored. A binary
458 is to be used when the underlying getsockopt requires input in
459 the argument field. In this case, the binary size is to corre‐
460 spond to the required buffer size of the return value. The sup‐
461 plied values in a RawOptReq correspond to the second, third, and
462 fourth/fifth parameters to the getsockopt call in the C socket
463 API. The value stored in the buffer is returned as a binary Val‐
464 ueBin, where all values are coded in the native endianness.
465 Asking for and inspecting raw socket options require low-level
467 information about the current operating system and TCP stack.
468 Example:
470 Consider a Linux machine where option TCP_INFO can be used to
472 collect TCP statistics for a socket. Assume you are interested
473 in field tcpi_sacked of struct tcp_info filled in when asking
474 for TCP_INFO. To be able to access this information, you need to
475 know the following:
476 * The numeric value of protocol level IPPROTO_TCP
478 * The numeric value of option TCP_INFO
480 * The size of struct tcp_info
482 * The size and offset of the specific field
484 By inspecting the headers or writing a small C program, it is
486 found that IPPROTO_TCP is 6, TCP_INFO is 11, the structure size
487 is 92 (bytes), the offset of tcpi_sacked is 28 bytes, and the
488 value is a 32-bit integer. The following code can be used to re‐
489 trieve the value:
490 get_tcpi_sacked(Sock) ->
492 {ok,[{raw,_,_,Info}]} = inet:getopts(Sock,[{raw,6,11,92}]),
493 <<_:28/binary,TcpiSacked:32/native,_/binary>> = Info,
494 TcpiSacked.
495 Preferably, you would check the machine type, the operating sys‐
497 tem, and the Kernel version before executing anything similar to
498 this code.
499 getstat(Socket) -> {ok, OptionValues} | {error, posix()}
501 getstat(Socket, Options) -> {ok, OptionValues} | {error, posix()}
503 Types:
505 Socket = socket()
507 Options = [stat_option()]
508 OptionValues = [{stat_option(), integer()}]
509 stat_option() =
510 recv_cnt | recv_max | recv_avg | recv_oct | recv_dvi |
511 send_cnt | send_max | send_avg | send_oct | send_pend
512 Gets one or more statistic options for a socket.
514 getstat(Socket) is equivalent to getstat(Socket, [recv_avg,
516 recv_cnt, recv_dvi, recv_max, recv_oct, send_avg, send_cnt,
517 send_pend, send_max, send_oct]).
518 The following options are available:
520 recv_avg:
522 Average size of packets, in bytes, received by the socket.
523 recv_cnt:
525 Number of packets received by the socket.
526 recv_dvi:
528 Average packet size deviation, in bytes, received by the
529 socket.
530 recv_max:
532 Size of the largest packet, in bytes, received by the
533 socket.
534 recv_oct:
536 Number of bytes received by the socket.
537 send_avg:
539 Average size of packets, in bytes, sent from the socket.
540 send_cnt:
542 Number of packets sent from the socket.
543 send_pend:
545 Number of bytes waiting to be sent by the socket.
546 send_max:
548 Size of the largest packet, in bytes, sent from the socket.
549 send_oct:
551 Number of bytes sent from the socket.
552 i() -> ok
554 i(Proto :: socket_protocol()) -> ok
556 i(X1 :: socket_protocol(), Fs :: [atom()]) -> ok
558 Lists all TCP, UDP and SCTP sockets, including those that the
560 Erlang runtime system uses as well as those created by the ap‐
561 plication.
562 The following options are available:
564 port:
566 The internal index of the port.
567 module:
569 The callback module of the socket.
570 recv:
572 Number of bytes received by the socket.
573 sent:
575 Number of bytes sent from the socket.
576 owner:
578 The socket owner process.
579 local_address:
581 The local address of the socket.
582 foreign_address:
584 The address and port of the other end of the connection.
585 state:
587 The connection state.
588 type:
590 STREAM or DGRAM or SEQPACKET.
591 info(Socket) -> Info
593 Types:
595 Socket = socket()
597 Info = term()
598 Produces a term containing miscellaneous information about a
600 socket.
601 monitor(Socket) -> reference()
603 Types:
605 Socket = socket()
607 Start monitor the socket Socket.
609 If the monitored socket does not exist or when the monitor is
611 triggered, a 'DOWN' message is sent that has the following pat‐
612 tern:
613 {'DOWN', MonitorRef, Type, Object, Info}
615 MonitorRef:
618 The identity of the socket.
619 Type:
621 The type of socket, can be one of the following atoms: port
622 or socket.
623 Object:
625 The monitored entity, the socket, which triggered the event.
626 Info:
628 Either the termination reason of the socket or nosock
629 (socket Socket did not exist at the time of monitor cre‐
630 ation).
631 Making several calls to inet:monitor/1 for the same Socket is
633 not an error; it results in as many independent monitoring in‐
634 stances.
635 is_ip_address(IPAddress) -> boolean()
637 Types:
639 IPAddress = ip_address() | term()
641 Tests if IPAddress is an ip_address() and returns true if so,
643 otherwise false.
644 is_ipv4_address(IPv4Address) -> boolean()
646 Types:
648 IPv4Address = ip4_address() | term()
650 Tests if IPAddress is an ip4_address() and returns true if so,
652 otherwise false.
653 is_ipv6_address(IPv6Address) -> boolean()
655 Types:
657 IPv6Address = ip6_address() | term()
659 Tests if IPAddress is an ip6_address() and returns true if so,
661 otherwise false.
662 ntoa(IpAddress) -> Address | {error, einval}
664 Types:
666 Address = string()
668 IpAddress = ip_address()
669 Parses an ip_address() and returns an IPv4 or IPv6 address
671 string.
672 parse_address(Address) -> {ok, IPAddress} | {error, einval}
674 Types:
676 Address = string()
678 IPAddress = ip_address()
679 Parses an IPv4 or IPv6 address string and returns an ip4_ad‐
681 dress() or ip6_address(). Accepts a shortened IPv4 address
682 string.
683 parse_ipv4_address(Address) -> {ok, IPv4Address} | {error, einval}
685 Types:
687 Address = string()
689 IPv4Address = ip4_address()
690 Parses an IPv4 address string and returns an ip4_address(). Ac‐
692 cepts a shortened IPv4 address string.
693 parse_ipv4strict_address(Address) ->
695 {ok, IPv4Address} | {error, einval}
696 Types:
698 Address = string()
700 IPv4Address = ip4_address()
701 Parses an IPv4 address string containing four fields, that is,
703 not shortened, and returns an ip4_address().
704 parse_ipv6_address(Address) -> {ok, IPv6Address} | {error, einval}
706 Types:
708 Address = string()
710 IPv6Address = ip6_address()
711 Parses an IPv6 address string and returns an ip6_address(). If
713 an IPv4 address string is specified, an IPv4-mapped IPv6 address
714 is returned.
715 parse_ipv6strict_address(Address) ->
717 {ok, IPv6Address} | {error, einval}
718 Types:
720 Address = string()
722 IPv6Address = ip6_address()
723 Parses an IPv6 address string and returns an ip6_address(). Does
725 not accept IPv4 addresses.
726 ipv4_mapped_ipv6_address(X1 :: ip_address()) -> ip_address()
728 Convert an IPv4 address to an IPv4-mapped IPv6 address or the
730 reverse. When converting from an IPv6 address all but the 2 low
731 words are ignored so this function also works on some other
732 types of addresses than IPv4-mapped.
733 parse_strict_address(Address) -> {ok, IPAddress} | {error, einval}
735 Types:
737 Address = string()
739 IPAddress = ip_address()
740 Parses an IPv4 or IPv6 address string and returns an ip4_ad‐
742 dress() or ip6_address(). Does not accept a shortened IPv4 ad‐
743 dress string.
744 peername(Socket :: socket()) ->
746 {ok,
747 {ip_address(), port_number()} |
748 returned_non_ip_address()} |
749 {error, posix()}
750 Returns the address and port for the other end of a connection.
752 Notice that for SCTP sockets, this function returns only one of
754 the peer addresses of the socket. Function peernames/1,2 returns
755 all.
756 peernames(Socket :: socket()) ->
758 {ok,
759 [{ip_address(), port_number()} |
760 returned_non_ip_address()]} |
761 {error, posix()}
762 Equivalent to peernames(Socket, 0).
764 Notice that the behavior of this function for an SCTP one-to-
766 many style socket is not defined by the SCTP Sockets API Exten‐
767 sions.
768 peernames(Socket, Assoc) ->
770 {ok, [{Address, Port}]} | {error, posix()}
771 Types:
773 Socket = socket()
775 Assoc = #sctp_assoc_change{} | gen_sctp:assoc_id()
776 Address = ip_address()
777 Port = integer() >= 0
778 Returns a list of all address/port number pairs for the other
780 end of an association Assoc of a socket.
781 This function can return multiple addresses for multihomed sock‐
783 ets, such as SCTP sockets. For other sockets it returns a one-
784 element list.
785 Notice that parameter Assoc is by the SCTP Sockets API Exten‐
787 sions defined to be ignored for one-to-one style sockets. What
788 the special value 0 means, hence its behavior for one-to-many
789 style sockets, is unfortunately undefined.
790 port(Socket) -> {ok, Port} | {error, any()}
792 Types:
794 Socket = socket()
796 Port = port_number()
797 Returns the local port number for a socket.
799 setopts(Socket, Options) -> ok | {error, posix()}
801 Types:
803 Socket = socket()
805 Options = [socket_setopt()]
806 Sets one or more options for a socket.
808 The following options are available:
810 {active, true | false | once | N}:
812 If the value is true, which is the default, everything re‐
813 ceived from the socket is sent as messages to the receiving
814 process.
815 If the value is false (passive mode), the process must ex‐
817 plicitly receive incoming data by calling gen_tcp:recv/2,3,
818 gen_udp:recv/2,3, or gen_sctp:recv/1,2 (depending on the
819 type of socket).
820 If the value is once ({active, once}), one data message from
822 the socket is sent to the process. To receive one more mes‐
823 sage, setopts/2 must be called again with option {active,
824 once}.
825 If the value is an integer N in the range -32768 to 32767
827 (inclusive), the value is added to the socket's count of
828 data messages sent to the controlling process. A socket's
829 default message count is 0. If a negative value is speci‐
830 fied, and its magnitude is equal to or greater than the
831 socket's current message count, the socket's message count
832 is set to 0. Once the socket's message count reaches 0, ei‐
833 ther because of sending received data messages to the
834 process or by being explicitly set, the process is then no‐
835 tified by a special message, specific to the type of socket,
836 that the socket has entered passive mode. Once the socket
837 enters passive mode, to receive more messages setopts/2 must
838 be called again to set the socket back into an active mode.
839 When using {active, once} or {active, N}, the socket changes
841 behavior automatically when data is received. This can be
842 confusing in combination with connection-oriented sockets
843 (that is, gen_tcp), as a socket with {active, false} behav‐
844 ior reports closing differently than a socket with {active,
845 true} behavior. To simplify programming, a socket where the
846 peer closed, and this is detected while in {active, false}
847 mode, still generates message {tcp_closed,Socket} when set
848 to {active, once}, {active, true}, or {active, N} mode. It
849 is therefore safe to assume that message
850 {tcp_closed,Socket}, possibly followed by socket port termi‐
851 nation (depending on option exit_on_close) eventually ap‐
852 pears when a socket changes back and forth between {active,
853 true} and {active, false} mode. However, when peer closing
854 is detected it is all up to the underlying TCP/IP stack and
855 protocol.
856 Notice that {active, true} mode provides no flow control; a
858 fast sender can easily overflow the receiver with incoming
859 messages. The same is true for {active, N} mode, while the
860 message count is greater than zero.
861 Use active mode only if your high-level protocol provides
863 its own flow control (for example, acknowledging received
864 messages) or the amount of data exchanged is small. {active,
865 false} mode, use of the {active, once} mode, or {active, N}
866 mode with values of N appropriate for the application pro‐
867 vides flow control. The other side cannot send faster than
868 the receiver can read.
869 {broadcast, Boolean} (UDP sockets):
871 Enables/disables permission to send broadcasts.
872 {buffer, Size}:
874 The size of the user-level buffer used by the driver. Not to
875 be confused with options sndbuf and recbuf, which correspond
876 to the Kernel socket buffers. For TCP it is recommended to
877 have val(buffer) >= val(recbuf) to avoid performance issues
878 because of unnecessary copying. For UDP the same recommenda‐
879 tion applies, but the max should not be larger than the MTU
880 of the network path. val(buffer) is automatically set to the
881 above maximum when recbuf is set. However, as the size set
882 for recbuf usually become larger, you are encouraged to use
883 getopts/2 to analyze the behavior of your operating system.
884 Note that this is also the maximum amount of data that can
886 be received from a single recv call. If you are using higher
887 than normal MTU consider setting buffer higher.
888 {delay_send, Boolean}:
890 Normally, when an Erlang process sends to a socket, the
891 driver tries to send the data immediately. If that fails,
892 the driver uses any means available to queue up the message
893 to be sent whenever the operating system says it can handle
894 it. Setting {delay_send, true} makes all messages queue up.
895 The messages sent to the network are then larger but fewer.
896 The option affects the scheduling of send requests versus
897 Erlang processes instead of changing any real property of
898 the socket. The option is implementation-specific. Defaults
899 to false.
900 {deliver, port | term}:
902 When {active, true}, data is delivered on the form port :
903 {S, {data, [H1,..Hsz | Data]}} or term : {tcp, S, [H1..Hsz |
904 Data]}.
905 {dontroute, Boolean}:
907 Enables/disables routing bypass for outgoing messages.
908 {exit_on_close, Boolean}:
910 This option is set to true by default.
911 The only reason to set it to false is if you want to con‐
913 tinue sending data to the socket after a close is detected,
914 for example, if the peer uses gen_tcp:shutdown/2 to shut
915 down the write side.
916 {exclusiveaddruse, Boolean}:
918 Enables/disables exclusive address/port usage on Windows.
919 That is, by enabling this option you can prevent other sock‐
920 ets from binding to the same address/port. By default this
921 option is disabled. That is, other sockets may use the same
922 address/port by setting {reuseaddr, true} in combination
923 with {reuseport, true} unless {exclusiveaddruse, true} has
924 been set on Socket. On non-Windows systems this option is
925 silently ignored.
926 {header, Size}:
928 This option is only meaningful if option binary was speci‐
929 fied when the socket was created. If option header is speci‐
930 fied, the first Size number bytes of data received from the
931 socket are elements of a list, and the remaining data is a
932 binary specified as the tail of the same list. For example,
933 if Size == 2, the data received matches [Byte1,Byte2|Bi‐
934 nary].
935 {high_msgq_watermark, Size}:
937 The socket message queue is set to a busy state when the
938 amount of data on the message queue reaches this limit. No‐
939 tice that this limit only concerns data that has not yet
940 reached the ERTS internal socket implementation. Defaults to
941 8 kB.
942 Senders of data to the socket are suspended if either the
944 socket message queue is busy or the socket itself is busy.
945 For more information, see options low_msgq_watermark,
947 high_watermark, and low_watermark.
948 Notice that distribution sockets disable the use of
950 high_msgq_watermark and low_msgq_watermark. Instead use the
951 distribution buffer busy limit, which is a similar feature.
952 {high_watermark, Size} (TCP/IP sockets):
954 The socket is set to a busy state when the amount of data
955 queued internally by the ERTS socket implementation reaches
956 this limit. Defaults to 8 kB.
957 Senders of data to the socket are suspended if either the
959 socket message queue is busy or the socket itself is busy.
960 For more information, see options low_watermark,
962 high_msgq_watermark, and low_msqg_watermark.
963 {ipv6_v6only, Boolean}:
965 Restricts the socket to use only IPv6, prohibiting any IPv4
966 connections. This is only applicable for IPv6 sockets (op‐
967 tion inet6).
968 On most platforms this option must be set on the socket be‐
970 fore associating it to an address. It is therefore only rea‐
971 sonable to specify it when creating the socket and not to
972 use it when calling function (setopts/2) containing this de‐
973 scription.
974 The behavior of a socket with this option set to true is the
976 only portable one. The original idea when IPv6 was new of
977 using IPv6 for all traffic is now not recommended by FreeBSD
978 (you can use {ipv6_v6only,false} to override the recommended
979 system default value), forbidden by OpenBSD (the supported
980 GENERIC kernel), and impossible on Windows (which has sepa‐
981 rate IPv4 and IPv6 protocol stacks). Most Linux distros
982 still have a system default value of false. This policy
983 shift among operating systems to separate IPv6 from IPv4
984 traffic has evolved, as it gradually proved hard and compli‐
985 cated to get a dual stack implementation correct and secure.
986 On some platforms, the only allowed value for this option is
988 true, for example, OpenBSD and Windows. Trying to set this
989 option to false, when creating the socket, fails in this
990 case.
991 Setting this option on platforms where it does not exist is
993 ignored. Getting this option with getopts/2 returns no
994 value, that is, the returned list does not contain an
995 {ipv6_v6only,_} tuple. On Windows, the option does not ex‐
996 ist, but it is emulated as a read-only option with value
997 true.
998 Therefore, setting this option to true when creating a
1000 socket never fails, except possibly on a platform where you
1001 have customized the kernel to only allow false, which can be
1002 doable (but awkward) on, for example, OpenBSD.
1003 If you read back the option value using getopts/2 and get no
1005 value, the option does not exist in the host operating sys‐
1006 tem. The behavior of both an IPv6 and an IPv4 socket listen‐
1007 ing on the same port, and for an IPv6 socket getting IPv4
1008 traffic is then no longer predictable.
1009 {keepalive, Boolean}(TCP/IP sockets):
1011 Enables/disables periodic transmission on a connected socket
1012 when no other data is exchanged. If the other end does not
1013 respond, the connection is considered broken and an error
1014 message is sent to the controlling process. Defaults to
1015 false.
1016 {linger, {true|false, Seconds}}:
1018 Determines the time-out, in seconds, for flushing unsent
1019 data in the close/1 socket call.
1020 The first component is if linger is enabled, the second com‐
1022 ponent is the flushing time-out, in seconds. There are 3 al‐
1023 ternatives:
1024 {false, _}:
1026 close/1 or shutdown/2 returns immediately, not waiting for
1027 data to be flushed, with closing happening in the back‐
1028 ground.
1029 {true, 0}:
1031 Aborts the connection when it is closed. Discards any data
1032 still remaining in the send buffers and sends RST to the
1033 peer.
1034 This avoids TCP's TIME_WAIT state, but leaves open the
1036 possibility that another "incarnation" of this connection
1037 being created.
1038 {true, Time} when Time > 0:
1040 close/1 or shutdown/2 will not return until all queued
1041 messages for the socket have been successfully sent or the
1042 linger timeout (Time) has been reached.
1043 {low_msgq_watermark, Size}:
1045 If the socket message queue is in a busy state, the socket
1046 message queue is set in a not busy state when the amount of
1047 data queued in the message queue falls below this limit. No‐
1048 tice that this limit only concerns data that has not yet
1049 reached the ERTS internal socket implementation. Defaults to
1050 4 kB.
1051 Senders that are suspended because of either a busy message
1053 queue or a busy socket are resumed when the socket message
1054 queue and the socket are not busy.
1055 For more information, see options high_msgq_watermark,
1057 high_watermark, and low_watermark.
1058 Notice that distribution sockets disable the use of
1060 high_msgq_watermark and low_msgq_watermark. Instead they use
1061 the distribution buffer busy limit, which is a similar fea‐
1062 ture.
1063 {low_watermark, Size} (TCP/IP sockets):
1065 If the socket is in a busy state, the socket is set in a not
1066 busy state when the amount of data queued internally by the
1067 ERTS socket implementation falls below this limit. Defaults
1068 to 4 kB.
1069 Senders that are suspended because of a busy message queue
1071 or a busy socket are resumed when the socket message queue
1072 and the socket are not busy.
1073 For more information, see options high_watermark,
1075 high_msgq_watermark, and low_msgq_watermark.
1076 {mode, Mode :: binary | list}:
1078 Received Packet is delivered as defined by Mode.
1079 {netns, Namespace :: file:filename_all()}:
1081 Sets a network namespace for the socket. Parameter Namespace
1082 is a filename defining the namespace, for example,
1083 "/var/run/netns/example", typically created by command ip
1084 netns add example. This option must be used in a function
1085 call that creates a socket, that is, gen_tcp:connect/3,4,
1086 gen_tcp:listen/2, gen_udp:open/1,2 or gen_sctp:open/0,1,2,
1087 and also getifaddrs/1.
1088 This option uses the Linux-specific syscall setns(), such as
1090 in Linux kernel 3.0 or later, and therefore only exists when
1091 the runtime system is compiled for such an operating system.
1092 The virtual machine also needs elevated privileges, either
1094 running as superuser or (for Linux) having capability
1095 CAP_SYS_ADMIN according to the documentation for setns(2).
1096 However, during testing also CAP_SYS_PTRACE and
1097 CAP_DAC_READ_SEARCH have proven to be necessary.
1098 Example:
1100 setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp
1102 Notice that the filesystem containing the virtual machine
1104 executable (beam.smp in the example) must be local, mounted
1105 without flag nosetuid, support extended attributes, and the
1106 kernel must support file capabilities. All this runs out of
1107 the box on at least Ubuntu 12.04 LTS, except that SCTP sock‐
1108 ets appear to not support network namespaces.
1109 Namespace is a filename and is encoded and decoded as dis‐
1111 cussed in module file, with the following exceptions:
1112 * Emulator flag +fnu is ignored.
1114 * getopts/2 for this option returns a binary for the file‐
1116 name if the stored filename cannot be decoded. This is
1117 only to occur if you set the option using a binary that
1118 cannot be decoded with the emulator's filename encoding:
1119 file:native_name_encoding/0.
1120 {bind_to_device, Ifname :: binary()}:
1122 Binds a socket to a specific network interface. This option
1123 must be used in a function call that creates a socket, that
1124 is, gen_tcp:connect/3,4, gen_tcp:listen/2, gen_udp:open/1,2,
1125 or gen_sctp:open/0,1,2.
1126 Unlike getifaddrs/0, Ifname is encoded a binary. In the un‐
1128 likely case that a system is using non-7-bit-ASCII charac‐
1129 ters in network device names, special care has to be taken
1130 when encoding this argument.
1131 This option uses the Linux-specific socket option SO_BIND‐
1133 TODEVICE, such as in Linux kernel 2.0.30 or later, and
1134 therefore only exists when the runtime system is compiled
1135 for such an operating system.
1136 Before Linux 3.8, this socket option could be set, but could
1138 not retrieved with getopts/2. Since Linux 3.8, it is read‐
1139 able.
1140 The virtual machine also needs elevated privileges, either
1142 running as superuser or (for Linux) having capability
1143 CAP_NET_RAW.
1144 The primary use case for this option is to bind sockets into
1146 Linux VRF instances.
1147 list:
1149 Received Packet is delivered as a list.
1150 binary:
1152 Received Packet is delivered as a binary.
1153 {nodelay, Boolean}(TCP/IP sockets):
1155 If Boolean == true, option TCP_NODELAY is turned on for the
1156 socket, which means that also small amounts of data are sent
1157 immediately.
1158 This option is not supported for domain = local, but if
1160 inet_backend =/= socket this error will be ignored.
1161 {nopush, Boolean}(TCP/IP sockets):
1163 This translates to TCP_NOPUSH on BSD and to TCP_CORK on
1164 Linux.
1165 If Boolean == true, the corresponding option is turned on
1167 for the socket, which means that small amounts of data are
1168 accumulated until a full MSS-worth of data is available or
1169 this option is turned off.
1170 Note that while TCP_NOPUSH socket option is available on
1172 OSX, its semantics is very different (e.g., unsetting it
1173 does not cause immediate send of accumulated data). Hence,
1174 nopush option is intentionally ignored on OSX.
1175 {packet, PacketType}(TCP/IP sockets):
1177 Defines the type of packets to use for a socket. Possible
1178 values:
1179 raw | 0:
1181 No packaging is done.
1182 1 | 2 | 4:
1184 Packets consist of a header specifying the number of bytes
1185 in the packet, followed by that number of bytes. The
1186 header length can be one, two, or four bytes, and contain‐
1187 ing an unsigned integer in big-endian byte order. Each
1188 send operation generates the header, and the header is
1189 stripped off on each receive operation.
1190 The 4-byte header is limited to 2Gb.
1192 asn1 | cdr | sunrm | fcgi | tpkt | line:
1194 These packet types only have effect on receiving. When
1195 sending a packet, it is the responsibility of the applica‐
1196 tion to supply a correct header. On receiving, however,
1197 one message is sent to the controlling process for each
1198 complete packet received, and, similarly, each call to
1199 gen_tcp:recv/2,3 returns one complete packet. The header
1200 is not stripped off.
1201 The meanings of the packet types are as follows:
1203 * asn1 - ASN.1 BER
1205 * sunrm - Sun's RPC encoding
1207 * cdr - CORBA (GIOP 1.1)
1209 * fcgi - Fast CGI
1211 * tpkt - TPKT format [RFC1006]
1213 * line - Line mode, a packet is a line-terminated with
1215 newline, lines longer than the receive buffer are trun‐
1216 cated
1217 http | http_bin:
1219 The Hypertext Transfer Protocol. The packets are returned
1220 with the format according to HttpPacket described in er‐
1221 lang:decode_packet/3 in ERTS. A socket in passive mode re‐
1222 turns {ok, HttpPacket} from gen_tcp:recv while an active
1223 socket sends messages like {http, Socket, HttpPacket}.
1224 httph | httph_bin:
1226 These two types are often not needed, as the socket auto‐
1227 matically switches from http/http_bin to httph/httph_bin
1228 internally after the first line is read. However, there
1229 can be occasions when they are useful, such as parsing
1230 trailers from chunked encoding.
1231 {packet_size, Integer}(TCP/IP sockets):
1233 Sets the maximum allowed length of the packet body. If the
1234 packet header indicates that the length of the packet is
1235 longer than the maximum allowed length, the packet is con‐
1236 sidered invalid. The same occurs if the packet header is too
1237 large for the socket receive buffer.
1238 For line-oriented protocols (line, http*), option
1240 packet_size also guarantees that lines up to the indicated
1241 length are accepted and not considered invalid because of
1242 internal buffer limitations.
1243 {line_delimiter, Char}(TCP/IP sockets):
1245 Sets the line delimiting character for line-oriented proto‐
1246 cols (line). Defaults to $\n.
1247 {raw, Protocol, OptionNum, ValueBin}:
1249 See below.
1250 {read_packets, Integer}(UDP sockets):
1252 Sets the maximum number of UDP packets to read without in‐
1253 tervention from the socket when data is available. When this
1254 many packets have been read and delivered to the destination
1255 process, new packets are not read until a new notification
1256 of available data has arrived. Defaults to 5. If this param‐
1257 eter is set too high, the system can become unresponsive be‐
1258 cause of UDP packet flooding.
1259 {recbuf, Size}:
1261 The minimum size of the receive buffer to use for the
1262 socket. You are encouraged to use getopts/2 to retrieve the
1263 size set by your operating system.
1264 {recvtclass, Boolean}:
1266 If set to true activates returning the received TCLASS value
1267 on platforms that implements the protocol IPPROTO_IPV6 op‐
1268 tion IPV6_RECVTCLASS or IPV6_2292RECVTCLASS for the socket.
1269 The value is returned as a {tclass,TCLASS} tuple regardless
1270 of if the platform returns an IPV6_TCLASS or an IPV6_RECVT‐
1271 CLASS CMSG value.
1272 For packet oriented sockets that supports receiving ancil‐
1274 lary data with the payload data (gen_udp and gen_sctp), the
1275 TCLASS value is returned in an extended return tuple con‐
1276 tained in an ancillary data list. For stream oriented
1277 sockets (gen_tcp) the only way to get the TCLASS value is if
1278 the platform supports the pktoptions option.
1279 {recvtos, Boolean}:
1281 If set to true activates returning the received TOS value on
1282 platforms that implements the protocol IPPROTO_IP option
1283 IP_RECVTOS for the socket. The value is returned as a
1284 {tos,TOS} tuple regardless of if the platform returns an
1285 IP_TOS or an IP_RECVTOS CMSG value.
1286 For packet oriented sockets that supports receiving ancil‐
1288 lary data with the payload data (gen_udp and gen_sctp), the
1289 TOS value is returned in an extended return tuple contained
1290 in an ancillary data list. For stream oriented sockets
1291 (gen_tcp) the only way to get the TOS value is if the plat‐
1292 form supports the pktoptions option.
1293 {recvttl, Boolean}:
1295 If set to true activates returning the received TTL value on
1296 platforms that implements the protocol IPPROTO_IP option
1297 IP_RECVTTL for the socket. The value is returned as a
1298 {ttl,TTL} tuple regardless of if the platform returns an
1299 IP_TTL or an IP_RECVTTL CMSG value.
1300 For packet oriented sockets that supports receiving ancil‐
1302 lary data with the payload data (gen_udp and gen_sctp), the
1303 TTL value is returned in an extended return tuple contained
1304 in an ancillary data list. For stream oriented sockets
1305 (gen_tcp) the only way to get the TTL value is if the plat‐
1306 form supports the pktoptions option.
1307 {reuseaddr, Boolean}:
1309 Allows or disallows reuse of local address. By default, re‐
1310 use is disallowed.
1311 Note:
1313 On windows {reuseaddr, true} will have no effect unless also
1314 {reuseport, true} is set. If both are set, the SO_REUSEADDR
1315 Windows socket option will be enabled. This since setting
1316 SO_REUSEADDR on Windows more or less has the same behavior as
1317 setting both SO_REUSEADDR and SO_REUSEPORT on BSD. This behav‐
1318 ior was introduced as of OTP 26.0.
1319 Change:
1321 Previous behavior on Windows:
1322 *
1324 Prior to OTP 25.0, the {reuseaddr, true} option was
1325 silently ignored.
1326 *
1328 Between OTP 25.0 and up to the predecessor of OTP 25.2,
1329 the underlying SO_REUSEADDR socket option was set if
1330 {reuseaddr, true} was set.
1331 *
1333 Between OTP 25.2 and up to the predecessor of OTP 26.0,
1334 the underlying SO_REUSEADDR socket option was only set on
1335 UDP sockets if {reuseaddr, true} was set, and silently ig‐
1336 nored on other sockets.
1337 See also the exclusiveaddruse option.
1339 {reuseport, Boolean}:
1342 Allows or disallows reuse of local port which may or may not
1343 have load balancing depending on the underlying OS. By de‐
1344 fault, reuse is disallowed. See also reuseport_lb.
1345 Note:
1347 On windows {reuseport, true} will have no effect unless also
1348 {reuseaddr, true} is set. If both are set, the SO_REUSEADDR
1349 Windows socket option will be enabled. This since setting
1350 SO_REUSEADDR on Windows more or less has the same behavior as
1351 setting both SO_REUSEADDR and SO_REUSEPORT on BSD. The reuse‐
1352 port option was introduced as of OTP 26.0.
1353 See also the exclusiveaddruse option.
1355 Note:
1358 reuseport may or may not be the same underlying option as
1359 reuseport_lb depending on the underlying OS. They, for exam‐
1360 ple, are on Linux. When they are the same underlying option,
1361 operating on both may cause them to interact in surprising
1362 ways. For example, by enabling reuseport and then disabling
1363 reuseport_lb both will end up being disabled.
1364 {reuseport_lb, Boolean}:
1367 Allows or disallows reuse of local port with load balanc‐
1368 ing. By default, reuse is disallowed. See also reuseport.
1369 Note:
1371 reuseport_lb may or may not be the same underlying option as
1372 reuseport depending on the underlying OS. They, for example,
1373 are on Linux. When they are the same underlying option, oper‐
1374 ating on both may cause them to interact in surprising ways.
1375 For example, by enabling reuseport_lb and then disabling
1376 reuseport both will end up being disabled.
1377 {send_timeout, Integer}:
1380 Only allowed for connection-oriented sockets.
1381 Specifies a longest time to wait for a send operation to be
1383 accepted by the underlying TCP stack. When the limit is ex‐
1384 ceeded, the send operation returns {error,timeout}. How much
1385 of a packet that got sent is unknown; the socket is there‐
1386 fore to be closed whenever a time-out has occurred (see
1387 send_timeout_close below). Defaults to infinity.
1388 {send_timeout_close, Boolean}:
1390 Only allowed for connection-oriented sockets.
1391 Used together with send_timeout to specify whether the
1393 socket is to be automatically closed when the send operation
1394 returns {error,timeout}. The recommended setting is true,
1395 which automatically closes the socket. Defaults to false be‐
1396 cause of backward compatibility.
1397 {show_econnreset, Boolean} (TCP/IP sockets) :
1399 When this option is set to false, which is default, an RST
1400 received from the TCP peer is treated as a normal close (as
1401 though an FIN was sent). A caller to gen_tcp:recv/2 gets
1402 {error, closed}. In active mode, the controlling process re‐
1403 ceives a {tcp_closed, Socket} message, indicating that the
1404 peer has closed the connection.
1405 Setting this option to true allows you to distinguish be‐
1407 tween a connection that was closed normally, and one that
1408 was aborted (intentionally or unintentionally) by the TCP
1409 peer. A call to gen_tcp:recv/2 returns {error, econnreset}.
1410 In active mode, the controlling process receives a {tcp_er‐
1411 ror, Socket, econnreset} message before the usual
1412 {tcp_closed, Socket}, as is the case for any other socket
1413 error. Calls to gen_tcp:send/2 also returns {error, econnre‐
1414 set} when it is detected that a TCP peer has sent an RST.
1415 A connected socket returned from gen_tcp:accept/1 inherits
1417 the show_econnreset setting from the listening socket.
1418 {sndbuf, Size}:
1420 The minimum size of the send buffer to use for the socket.
1421 You are encouraged to use getopts/2, to retrieve the size
1422 set by your operating system.
1423 {priority, Integer}:
1425 Sets the SO_PRIORITY socket level option on platforms where
1426 this is implemented. The behavior and allowed range varies
1427 between different systems. The option is ignored on plat‐
1428 forms where it is not implemented. Use with caution.
1429 {tos, Integer}:
1431 Sets IP_TOS IP level options on platforms where this is im‐
1432 plemented. The behavior and allowed range varies between
1433 different systems. The option is ignored on platforms where
1434 it is not implemented. Use with caution.
1435 {tclass, Integer}:
1437 Sets IPV6_TCLASS IP level options on platforms where this is
1438 implemented. The behavior and allowed range varies between
1439 different systems. The option is ignored on platforms where
1440 it is not implemented. Use with caution.
1441 In addition to these options, raw option specifications can be
1443 used. The raw options are specified as a tuple of arity four,
1444 beginning with tag raw, followed by the protocol level, the op‐
1445 tion number, and the option value specified as a binary. This
1446 corresponds to the second, third, and fourth arguments to the
1447 setsockopt call in the C socket API. The option value must be
1448 coded in the native endianness of the platform and, if a struc‐
1449 ture is required, must follow the structure alignment conven‐
1450 tions on the specific platform.
1451 Using raw socket options requires detailed knowledge about the
1453 current operating system and TCP stack.
1454 Example:
1456 This example concerns the use of raw options. Consider a Linux
1458 system where you want to set option TCP_LINGER2 on protocol
1459 level IPPROTO_TCP in the stack. You know that on this particular
1460 system it defaults to 60 (seconds), but you want to lower it to
1461 30 for a particular socket. Option TCP_LINGER2 is not explicitly
1462 supported by inet, but you know that the protocol level trans‐
1463 lates to number 6, the option number to number 8, and the value
1464 is to be specified as a 32-bit integer. You can use this code
1465 line to set the option for the socket named Sock:
1466 inet:setopts(Sock,[{raw,6,8,<<30:32/native>>}]),
1468 As many options are silently discarded by the stack if they are
1470 specified out of range; it can be a good idea to check that a
1471 raw option is accepted. The following code places the value in
1472 variable TcpLinger2:
1473 {ok,[{raw,6,8,<<TcpLinger2:32/native>>}]}=inet:getopts(Sock,[{raw,6,8,4}]),
1475 Code such as these examples is inherently non-portable, even
1477 different versions of the same OS on the same platform can re‐
1478 spond differently to this kind of option manipulation. Use with
1479 care.
1480 Notice that the default options for TCP/IP sockets can be
1482 changed with the Kernel configuration parameters mentioned in
1483 the beginning of this manual page.
1484 sockname(Socket :: socket()) ->
1486 {ok,
1487 {ip_address(), port_number()} |
1488 returned_non_ip_address()} |
1489 {error, posix()}
1490 Returns the local address and port number for a socket.
1492 Notice that for SCTP sockets this function returns only one of
1494 the socket addresses. Function socknames/1,2 returns all.
1495 socknames(Socket :: socket()) ->
1497 {ok,
1498 [{ip_address(), port_number()} |
1499 returned_non_ip_address()]} |
1500 {error, posix()}
1501 Equivalent to socknames(Socket, 0).
1503 socknames(Socket, Assoc) ->
1505 {ok, [{Address, Port}]} | {error, posix()}
1506 Types:
1508 Socket = socket()
1510 Assoc = #sctp_assoc_change{} | gen_sctp:assoc_id()
1511 Address = ip_address()
1512 Port = integer() >= 0
1513 Returns a list of all local address/port number pairs for a
1515 socket for the specified association Assoc.
1516 This function can return multiple addresses for multihomed sock‐
1518 ets, such as SCTP sockets. For other sockets it returns a one-
1519 element list.
1520 Notice that parameter Assoc is by the SCTP Sockets API Exten‐
1522 sions defined to be ignored for one-to-one style sockets. For
1523 one-to-many style sockets, the special value 0 is defined to
1524 mean that the returned addresses must be without any particular
1525 association. How different SCTP implementations interpret this
1526 varies somewhat.
1527
1529 * e2big - Too long argument list
1530 * eacces - Permission denied
1532 * eaddrinuse - Address already in use
1534 * eaddrnotavail - Cannot assign requested address
1536 * eadv - Advertise error
1538 * eafnosupport - Address family not supported by protocol family
1540 * eagain - Resource temporarily unavailable
1542 * ealign - EALIGN
1544 * ealready - Operation already in progress
1546 * ebade - Bad exchange descriptor
1548 * ebadf - Bad file number
1550 * ebadfd - File descriptor in bad state
1552 * ebadmsg - Not a data message
1554 * ebadr - Bad request descriptor
1556 * ebadrpc - Bad RPC structure
1558 * ebadrqc - Bad request code
1560 * ebadslt - Invalid slot
1562 * ebfont - Bad font file format
1564 * ebusy - File busy
1566 * echild - No children
1568 * echrng - Channel number out of range
1570 * ecomm - Communication error on send
1572 * econnaborted - Software caused connection abort
1574 * econnrefused - Connection refused
1576 * econnreset - Connection reset by peer
1578 * edeadlk - Resource deadlock avoided
1580 * edeadlock - Resource deadlock avoided
1582 * edestaddrreq - Destination address required
1584 * edirty - Mounting a dirty fs without force
1586 * edom - Math argument out of range
1588 * edotdot - Cross mount point
1590 * edquot - Disk quota exceeded
1592 * eduppkg - Duplicate package name
1594 * eexist - File already exists
1596 * efault - Bad address in system call argument
1598 * efbig - File too large
1600 * ehostdown - Host is down
1602 * ehostunreach - Host is unreachable
1604 * eidrm - Identifier removed
1606 * einit - Initialization error
1608 * einprogress - Operation now in progress
1610 * eintr - Interrupted system call
1612 * einval - Invalid argument
1614 * eio - I/O error
1616 * eisconn - Socket is already connected
1618 * eisdir - Illegal operation on a directory
1620 * eisnam - Is a named file
1622 * el2hlt - Level 2 halted
1624 * el2nsync - Level 2 not synchronized
1626 * el3hlt - Level 3 halted
1628 * el3rst - Level 3 reset
1630 * elbin - ELBIN
1632 * elibacc - Cannot access a needed shared library
1634 * elibbad - Accessing a corrupted shared library
1636 * elibexec - Cannot exec a shared library directly
1638 * elibmax - Attempting to link in more shared libraries than system
1640 limit
1641 * elibscn - .lib section in a.out corrupted
1643 * elnrng - Link number out of range
1645 * eloop - Too many levels of symbolic links
1647 * emfile - Too many open files
1649 * emlink - Too many links
1651 * emsgsize - Message too long
1653 * emultihop - Multihop attempted
1655 * enametoolong - Filename too long
1657 * enavail - Unavailable
1659 * enet - ENET
1661 * enetdown - Network is down
1663 * enetreset - Network dropped connection on reset
1665 * enetunreach - Network is unreachable
1667 * enfile - File table overflow
1669 * enoano - Anode table overflow
1671 * enobufs - No buffer space available
1673 * enocsi - No CSI structure available
1675 * enodata - No data available
1677 * enodev - No such device
1679 * enoent - No such file or directory
1681 * enoexec - Exec format error
1683 * enolck - No locks available
1685 * enolink - Link has been severed
1687 * enomem - Not enough memory
1689 * enomsg - No message of desired type
1691 * enonet - Machine is not on the network
1693 * enopkg - Package not installed
1695 * enoprotoopt - Bad protocol option
1697 * enospc - No space left on device
1699 * enosr - Out of stream resources or not a stream device
1701 * enosym - Unresolved symbol name
1703 * enosys - Function not implemented
1705 * enotblk - Block device required
1707 * enotconn - Socket is not connected
1709 * enotdir - Not a directory
1711 * enotempty - Directory not empty
1713 * enotnam - Not a named file
1715 * enotsock - Socket operation on non-socket
1717 * enotsup - Operation not supported
1719 * enotty - Inappropriate device for ioctl
1721 * enotuniq - Name not unique on network
1723 * enxio - No such device or address
1725 * eopnotsupp - Operation not supported on socket
1727 * eperm - Not owner
1729 * epfnosupport - Protocol family not supported
1731 * epipe - Broken pipe
1733 * eproclim - Too many processes
1735 * eprocunavail - Bad procedure for program
1737 * eprogmismatch - Wrong program version
1739 * eprogunavail - RPC program unavailable
1741 * eproto - Protocol error
1743 * eprotonosupport - Protocol not supported
1745 * eprototype - Wrong protocol type for socket
1747 * erange - Math result unrepresentable
1749 * erefused - EREFUSED
1751 * eremchg - Remote address changed
1753 * eremdev - Remote device
1755 * eremote - Pathname hit remote filesystem
1757 * eremoteio - Remote I/O error
1759 * eremoterelease - EREMOTERELEASE
1761 * erofs - Read-only filesystem
1763 * erpcmismatch - Wrong RPC version
1765 * erremote - Object is remote
1767 * eshutdown - Cannot send after socket shutdown
1769 * esocktnosupport - Socket type not supported
1771 * espipe - Invalid seek
1773 * esrch - No such process
1775 * esrmnt - Srmount error
1777 * estale - Stale remote file handle
1779 * esuccess - Error 0
1781 * etime - Timer expired
1783 * etimedout - Connection timed out
1785 * etoomanyrefs - Too many references
1787 * etxtbsy - Text file or pseudo-device busy
1789 * euclean - Structure needs cleaning
1791 * eunatch - Protocol driver not attached
1793 * eusers - Too many users
1795 * eversion - Version mismatch
1797 * ewouldblock - Operation would block
1799 * exdev - Cross-device link
1801 * exfull - Message tables full
1803 * nxdomain - Hostname or domain name cannot be found
1805Ericsson AB kernel 9.1 inet(3)