1inet(3)                    Erlang Module Definition                    inet(3)
2
3
4

NAME

6       inet - Access to TCP/IP protocols.
7

DESCRIPTION

9       This module provides access to TCP/IP protocols.
10
11       See  also  ERTS  User's  Guide: Inet Configuration for more information
12       about how to configure an Erlang runtime system for IP communication.
13
14       The following two Kernel configuration parameters affect  the  behavior
15       of all sockets opened on an Erlang node:
16
17         * inet_default_connect_options  can contain a list of default options
18           used for all sockets returned when doing connect.
19
20         * inet_default_listen_options can contain a list of  default  options
21           used when issuing a listen call.
22
23       When  accept  is issued, the values of the listening socket options are
24       inherited. No such application variable is therefore needed for accept.
25
26       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
32       $ erl -sname test -kernel \
33       inet_default_connect_options '[{delay_send,true}]' \
34       inet_default_listen_options '[{delay_send,true}]'
35
36       Notice that default option {active, true} cannot be changed, for inter‐
37       nal reasons.
38
39       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
43       IPv4 address examples:
44
45       Address          ip_address()
46       -------          ------------
47       127.0.0.1        {127,0,0,1}
48       192.168.42.2     {192,168,42,2}
49
50       IPv6 address examples:
51
52       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
63       Function parse_address/1 can be useful:
64
65       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

DATA TYPES

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
79              The record is defined in the Kernel include file "inet.hrl".
80
81              Add the following directive to the module:
82
83              -include_lib("kernel/include/inet.hrl").
84
85       hostname() = atom() | string()
86
87       ip_address() = ip4_address() | ip6_address()
88
89       ip4_address() = {0..255, 0..255, 0..255, 0..255}
90
91       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
101       port_number() = 0..65535
102
103       family_address() =
104           inet_address() | inet6_address() | local_address()
105
106              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
111       local_address() = {local, File :: binary() | string()}
112
113              This address family only works on Unix-like systems.
114
115              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
119              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
123              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
127              In most API functions where you can use this address family  the
128              port number must be 0.
129
130       inet_backend() = {inet_backend, inet | socket}
131
132              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
137              This is a temporary option that will be ignored in a future  re‐
138              lease.
139
140       socket_address() =
141           ip_address() | any | loopback | local_address()
142
143       socket_getopt() =
144           gen_sctp:option_name() |
145           gen_tcp:option_name() |
146           gen_udp:option_name()
147
148       socket_setopt() =
149           gen_sctp:option() | gen_tcp:option() | gen_udp:option()
150
151       socket_optval() =
152           gen_sctp:option_value() |
153           gen_tcp:option() |
154           gen_udp:option() |
155           gen_tcp:pktoptions_value()
156
157       returned_non_ip_address() =
158           {local, binary()} | {unspec, <<>>} | {undefined, any()}
159
160              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
167       ancillary_data() =
168           [{tos, byte()} | {tclass, byte()} | {ttl, byte()}]
169
170              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
174              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
178       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
188              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
192       socket()
193
194              See gen_tcp:type-socket and gen_udp:type-socket.
195
196       address_family() = inet | inet6 | local
197
198       socket_protocol() = tcp | udp | sctp
199
200       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

DATA TYPES

205   Internal data types
206       inet_address() =
207           {inet, {ip4_address() | any | loopback, port_number()}}
208
209          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
214
215       inet6_address() =
216           {inet6, {ip6_address() | any | loopback, port_number()}}
217
218          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
223
224       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
236              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
240              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
244              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
252              Do not rely too much on the order of Flags atoms  or  the  Ifopt
253              tuples. There are however some rules:
254
255                * A {flag,_} tuple applies to all other tuples that follow.
256
257                * Immediately after {addr,_} follows {netmask,_}.
258
259                * 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
264                * Any {netmask,_}, {broadaddr,_}, or {dstaddr,_}  tuples  that
265                  follow an {addr,Addr} tuple concerns the address Addr.
266
267              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
271          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
276

EXPORTS

278       close(Socket) -> ok
279
280              Types:
281
282                 Socket = socket()
283
284              Closes a socket of any type.
285
286       cancel_monitor(MRef) -> boolean()
287
288              Types:
289
290                 MRef = reference()
291
292              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
296              The returned value is one of the following:
297
298                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
303                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
308              Failure:  It  is an error if MRef refers to a monitor started by
309              another process.
310
311       format_error(Reason) -> string()
312
313              Types:
314
315                 Reason = posix() | system_limit
316
317              Returns a diagnostic error string. For possible POSIX values and
318              corresponding strings, see section POSIX Error Codes.
319
320       get_rc() ->
321                 [{Par :: atom(), Val :: any()} |
322                  {Par :: atom(), Val1 :: any(), Val2 :: any()}]
323
324              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
328              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
333       getaddr(Host, Family) -> {ok, Address} | {error, posix()}
334
335              Types:
336
337                 Host = ip_address() | hostname()
338                 Family = address_family()
339                 Address = ip_address()
340
341              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
345       getaddrs(Host, Family) -> {ok, Addresses} | {error, posix()}
346
347              Types:
348
349                 Host = ip_address() | hostname()
350                 Family = address_family()
351                 Addresses = [ip_address()]
352
353              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
356       gethostbyaddr(Address) -> {ok, Hostent} | {error, posix()}
357
358              Types:
359
360                 Address = string() | ip_address()
361                 Hostent = hostent()
362
363              Returns  a  hostent  record  for the host with the specified ad‐
364              dress.
365
366       gethostbyname(Hostname) -> {ok, Hostent} | {error, posix()}
367
368              Types:
369
370                 Hostname = hostname()
371                 Hostent = hostent()
372
373              Returns a hostent record for the host with the  specified  host‐
374              name.
375
376              If resolver option inet6 is true, an IPv6 address is looked up.
377
378       gethostbyname(Hostname, Family) ->
379                        {ok, Hostent} | {error, posix()}
380
381              Types:
382
383                 Hostname = hostname()
384                 Family = address_family()
385                 Hostent = hostent()
386
387              Returns  a  hostent record for the host with the specified name,
388              restricted to the specified address family.
389
390       gethostname() -> {ok, Hostname}
391
392              Types:
393
394                 Hostname = string()
395
396              Returns the local hostname. Never fails.
397
398       getifaddrs() ->
399                     {ok,
400                      [{Ifname :: string(),
401                        Ifopts :: getifaddrs_ifopts()}]} |
402                     {error, posix()}
403
404              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
408              The interface address description tuples  are  documented  under
409              the type of the Ifopts value.
410
411       getifaddrs(Opts) -> {ok, [{Ifname, Ifopts}]} | {error, Posix}
412
413              Types:
414
415                  Opts = [{netns, Namespace}]
416                  Namespace =  file:filename_all()
417                 Ifname = string()
418                  Ifopts =  getifaddrs_ifopts()
419                 Posix = posix()
420
421              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
425              See the socket option {netns, Namespace} under setopts/2.
426
427       getopts(Socket, Options) -> {ok, OptionValues} | {error, posix()}
428
429              Types:
430
431                 Socket = socket()
432                 Options = [socket_getopt()]
433                 OptionValues = [socket_optval()]
434
435              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
439              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
448              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
455              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
466              Asking for and inspecting raw socket options  require  low-level
467              information about the current operating system and TCP stack.
468
469              Example:
470
471              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
477                * The numeric value of protocol level IPPROTO_TCP
478
479                * The numeric value of option TCP_INFO
480
481                * The size of struct tcp_info
482
483                * The size and offset of the specific field
484
485              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
491              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
496              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
500       getstat(Socket) -> {ok, OptionValues} | {error, posix()}
501
502       getstat(Socket, Options) -> {ok, OptionValues} | {error, posix()}
503
504              Types:
505
506                 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
513              Gets one or more statistic options for a socket.
514
515              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
519              The following options are available:
520
521                recv_avg:
522                  Average size of packets, in bytes, received by the socket.
523
524                recv_cnt:
525                  Number of packets received by the socket.
526
527                recv_dvi:
528                  Average  packet  size  deviation,  in bytes, received by the
529                  socket.
530
531                recv_max:
532                  Size of the  largest  packet,  in  bytes,  received  by  the
533                  socket.
534
535                recv_oct:
536                  Number of bytes received by the socket.
537
538                send_avg:
539                  Average size of packets, in bytes, sent from the socket.
540
541                send_cnt:
542                  Number of packets sent from the socket.
543
544                send_pend:
545                  Number of bytes waiting to be sent by the socket.
546
547                send_max:
548                  Size of the largest packet, in bytes, sent from the socket.
549
550                send_oct:
551                  Number of bytes sent from the socket.
552
553       i() -> ok
554
555       i(Proto :: socket_protocol()) -> ok
556
557       i(X1 :: socket_protocol(), Fs :: [atom()]) -> ok
558
559              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
563              The following options are available:
564
565                port:
566                  The internal index of the port.
567
568                module:
569                  The callback module of the socket.
570
571                recv:
572                  Number of bytes received by the socket.
573
574                sent:
575                  Number of bytes sent from the socket.
576
577                owner:
578                  The socket owner process.
579
580                local_address:
581                  The local address of the socket.
582
583                foreign_address:
584                  The address and port of the other end of the connection.
585
586                state:
587                  The connection state.
588
589                type:
590                  STREAM or DGRAM or SEQPACKET.
591
592       info(Socket) -> Info
593
594              Types:
595
596                 Socket = socket()
597                 Info = term()
598
599              Produces  a  term  containing  miscellaneous information about a
600              socket.
601
602       monitor(Socket) -> reference()
603
604              Types:
605
606                 Socket = socket()
607
608              Start monitor the socket Socket.
609
610              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
614                       {'DOWN', MonitorRef, Type, Object, Info}
615
616
617                MonitorRef:
618                  The identity of the socket.
619
620                Type:
621                  The type of socket, can be one of the following atoms:  port
622                  or socket.
623
624                Object:
625                  The monitored entity, the socket, which triggered the event.
626
627                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
632              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
636       is_ip_address(IPAddress) -> boolean()
637
638              Types:
639
640                 IPAddress = ip_address() | term()
641
642              Tests  if  IPAddress  is an ip_address() and returns true if so,
643              otherwise false.
644
645       is_ipv4_address(IPv4Address) -> boolean()
646
647              Types:
648
649                 IPv4Address = ip4_address() | term()
650
651              Tests if IPAddress is an ip4_address() and returns true  if  so,
652              otherwise false.
653
654       is_ipv6_address(IPv6Address) -> boolean()
655
656              Types:
657
658                 IPv6Address = ip6_address() | term()
659
660              Tests  if  IPAddress is an ip6_address() and returns true if so,
661              otherwise false.
662
663       ntoa(IpAddress) -> Address | {error, einval}
664
665              Types:
666
667                 Address = string()
668                 IpAddress = ip_address()
669
670              Parses an ip_address() and  returns  an  IPv4  or  IPv6  address
671              string.
672
673       parse_address(Address) -> {ok, IPAddress} | {error, einval}
674
675              Types:
676
677                 Address = string()
678                 IPAddress = ip_address()
679
680              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
684       parse_ipv4_address(Address) -> {ok, IPv4Address} | {error, einval}
685
686              Types:
687
688                 Address = string()
689                 IPv4Address = ip4_address()
690
691              Parses  an IPv4 address string and returns an ip4_address(). Ac‐
692              cepts a shortened IPv4 address string.
693
694       parse_ipv4strict_address(Address) ->
695                                   {ok, IPv4Address} | {error, einval}
696
697              Types:
698
699                 Address = string()
700                 IPv4Address = ip4_address()
701
702              Parses an IPv4 address string containing four fields,  that  is,
703              not shortened, and returns an ip4_address().
704
705       parse_ipv6_address(Address) -> {ok, IPv6Address} | {error, einval}
706
707              Types:
708
709                 Address = string()
710                 IPv6Address = ip6_address()
711
712              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
716       parse_ipv6strict_address(Address) ->
717                                   {ok, IPv6Address} | {error, einval}
718
719              Types:
720
721                 Address = string()
722                 IPv6Address = ip6_address()
723
724              Parses an IPv6 address string and returns an ip6_address(). Does
725              not accept IPv4 addresses.
726
727       ipv4_mapped_ipv6_address(X1 :: ip_address()) -> ip_address()
728
729              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
734       parse_strict_address(Address) -> {ok, IPAddress} | {error, einval}
735
736              Types:
737
738                 Address = string()
739                 IPAddress = ip_address()
740
741              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
745       peername(Socket :: socket()) ->
746                   {ok,
747                    {ip_address(), port_number()} |
748                    returned_non_ip_address()} |
749                   {error, posix()}
750
751              Returns the address and port for the other end of a connection.
752
753              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
757       peernames(Socket :: socket()) ->
758                    {ok,
759                     [{ip_address(), port_number()} |
760                      returned_non_ip_address()]} |
761                    {error, posix()}
762
763              Equivalent to peernames(Socket, 0).
764
765              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
769       peernames(Socket, Assoc) ->
770                    {ok, [{Address, Port}]} | {error, posix()}
771
772              Types:
773
774                 Socket = socket()
775                 Assoc = #sctp_assoc_change{} | gen_sctp:assoc_id()
776                 Address = ip_address()
777                 Port = integer() >= 0
778
779              Returns  a  list  of all address/port number pairs for the other
780              end of an association Assoc of a socket.
781
782              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
786              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
791       port(Socket) -> {ok, Port} | {error, any()}
792
793              Types:
794
795                 Socket = socket()
796                 Port = port_number()
797
798              Returns the local port number for a socket.
799
800       setopts(Socket, Options) -> ok | {error, posix()}
801
802              Types:
803
804                 Socket = socket()
805                 Options = [socket_setopt()]
806
807              Sets one or more options for a socket.
808
809              The following options are available:
810
811                {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
816                  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
821                  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
826                  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
840                  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
857                  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
862                  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
870                {broadcast, Boolean} (UDP sockets):
871                  Enables/disables permission to send broadcasts.
872
873                {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
885                  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
889                {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
901                {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
906                {dontroute, Boolean}:
907                  Enables/disables routing bypass for outgoing messages.
908
909                {exit_on_close, Boolean}:
910                  This option is set to true by default.
911
912                  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
917                {header, Size}:
918                  This option is only meaningful if option binary  was  speci‐
919                  fied when the socket was created. If option header is speci‐
920                  fied, the first Size number bytes of data received from  the
921                  socket  are  elements of a list, and the remaining data is a
922                  binary specified as the tail of the same list. For  example,
923                  if  Size  ==  2,  the data received matches [Byte1,Byte2|Bi‐
924                  nary].
925
926                {high_msgq_watermark, Size}:
927                  The socket message queue is set to a  busy  state  when  the
928                  amount  of data on the message queue reaches this limit. No‐
929                  tice that this limit only concerns data  that  has  not  yet
930                  reached the ERTS internal socket implementation. Defaults to
931                  8 kB.
932
933                  Senders of data to the socket are suspended  if  either  the
934                  socket message queue is busy or the socket itself is busy.
935
936                  For   more   information,  see  options  low_msgq_watermark,
937                  high_watermark, and low_watermark.
938
939                  Notice  that  distribution  sockets  disable  the   use   of
940                  high_msgq_watermark  and low_msgq_watermark. Instead use the
941                  distribution buffer busy limit, which is a similar feature.
942
943                {high_watermark, Size} (TCP/IP sockets):
944                  The socket is set to a busy state when the  amount  of  data
945                  queued  internally by the ERTS socket implementation reaches
946                  this limit. Defaults to 8 kB.
947
948                  Senders of data to the socket are suspended  if  either  the
949                  socket message queue is busy or the socket itself is busy.
950
951                  For    more    information,   see   options   low_watermark,
952                  high_msgq_watermark, and low_msqg_watermark.
953
954                {ipv6_v6only, Boolean}:
955                  Restricts the socket to use only IPv6, prohibiting any  IPv4
956                  connections.  This  is only applicable for IPv6 sockets (op‐
957                  tion inet6).
958
959                  On most platforms this option must be set on the socket  be‐
960                  fore associating it to an address. It is therefore only rea‐
961                  sonable to specify it when creating the socket  and  not  to
962                  use it when calling function (setopts/2) containing this de‐
963                  scription.
964
965                  The behavior of a socket with this option set to true is the
966                  only  portable  one.  The original idea when IPv6 was new of
967                  using IPv6 for all traffic is now not recommended by FreeBSD
968                  (you can use {ipv6_v6only,false} to override the recommended
969                  system default value), forbidden by OpenBSD  (the  supported
970                  GENERIC  kernel), and impossible on Windows (which has sepa‐
971                  rate IPv4 and IPv6  protocol  stacks).  Most  Linux  distros
972                  still  have  a  system  default  value of false. This policy
973                  shift among operating systems to  separate  IPv6  from  IPv4
974                  traffic has evolved, as it gradually proved hard and compli‐
975                  cated to get a dual stack implementation correct and secure.
976
977                  On some platforms, the only allowed value for this option is
978                  true,  for  example, OpenBSD and Windows. Trying to set this
979                  option to false, when creating the  socket,  fails  in  this
980                  case.
981
982                  Setting  this option on platforms where it does not exist is
983                  ignored. Getting  this  option  with  getopts/2  returns  no
984                  value,  that  is,  the  returned  list  does  not contain an
985                  {ipv6_v6only,_} tuple. On Windows, the option does  not  ex‐
986                  ist,  but  it  is  emulated as a read-only option with value
987                  true.
988
989                  Therefore, setting this  option  to  true  when  creating  a
990                  socket  never fails, except possibly on a platform where you
991                  have customized the kernel to only allow false, which can be
992                  doable (but awkward) on, for example, OpenBSD.
993
994                  If you read back the option value using getopts/2 and get no
995                  value, the option does not exist in the host operating  sys‐
996                  tem. The behavior of both an IPv6 and an IPv4 socket listen‐
997                  ing on the same port, and for an IPv6  socket  getting  IPv4
998                  traffic is then no longer predictable.
999
1000                {keepalive, Boolean}(TCP/IP sockets):
1001                  Enables/disables periodic transmission on a connected socket
1002                  when no other data is exchanged. If the other end  does  not
1003                  respond,  the  connection  is considered broken and an error
1004                  message is sent to  the  controlling  process.  Defaults  to
1005                  false.
1006
1007                {linger, {true|false, Seconds}}:
1008                  Determines  the  time-out,  in  seconds, for flushing unsent
1009                  data in the close/1 socket call.
1010
1011                  The first component is if linger is enabled, the second com‐
1012                  ponent is the flushing time-out, in seconds. There are 3 al‐
1013                  ternatives:
1014
1015                  {false, _}:
1016                    close/1 or shutdown/2 returns immediately, not waiting for
1017                    data  to  be  flushed, with closing happening in the back‐
1018                    ground.
1019
1020                  {true, 0}:
1021                    Aborts the connection when it is closed. Discards any data
1022                    still  remaining  in the send buffers and sends RST to the
1023                    peer.
1024
1025                    This avoids TCP's TIME_WAIT state,  but  leaves  open  the
1026                    possibility  that another "incarnation" of this connection
1027                    being created.
1028
1029                  {true, Time} when Time > 0:
1030                    close/1 or shutdown/2 will not  return  until  all  queued
1031                    messages for the socket have been successfully sent or the
1032                    linger timeout (Time) has been reached.
1033
1034                {low_msgq_watermark, Size}:
1035                  If the socket message queue is in a busy state,  the  socket
1036                  message  queue is set in a not busy state when the amount of
1037                  data queued in the message queue falls below this limit. No‐
1038                  tice  that  this  limit  only concerns data that has not yet
1039                  reached the ERTS internal socket implementation. Defaults to
1040                  4 kB.
1041
1042                  Senders  that are suspended because of either a busy message
1043                  queue or a busy socket are resumed when the  socket  message
1044                  queue and the socket are not busy.
1045
1046                  For   more  information,  see  options  high_msgq_watermark,
1047                  high_watermark, and low_watermark.
1048
1049                  Notice  that  distribution  sockets  disable  the   use   of
1050                  high_msgq_watermark and low_msgq_watermark. Instead they use
1051                  the distribution buffer busy limit, which is a similar  fea‐
1052                  ture.
1053
1054                {low_watermark, Size} (TCP/IP sockets):
1055                  If the socket is in a busy state, the socket is set in a not
1056                  busy state when the amount of data queued internally by  the
1057                  ERTS  socket implementation falls below this limit. Defaults
1058                  to 4 kB.
1059
1060                  Senders that are suspended because of a busy  message  queue
1061                  or  a  busy socket are resumed when the socket message queue
1062                  and the socket are not busy.
1063
1064                  For   more   information,   see   options    high_watermark,
1065                  high_msgq_watermark, and low_msgq_watermark.
1066
1067                {mode, Mode :: binary | list}:
1068                  Received Packet is delivered as defined by Mode.
1069
1070                {netns, Namespace :: file:filename_all()}:
1071                  Sets a network namespace for the socket. Parameter Namespace
1072                  is  a  filename  defining  the   namespace,   for   example,
1073                  "/var/run/netns/example",  typically  created  by command ip
1074                  netns add example. This option must be used  in  a  function
1075                  call  that  creates  a socket, that is, gen_tcp:connect/3,4,
1076                  gen_tcp:listen/2, gen_udp:open/1,2  or  gen_sctp:open/0,1,2,
1077                  and also getifaddrs/1.
1078
1079                  This option uses the Linux-specific syscall setns(), such as
1080                  in Linux kernel 3.0 or later, and therefore only exists when
1081                  the runtime system is compiled for such an operating system.
1082
1083                  The  virtual  machine also needs elevated privileges, either
1084                  running  as  superuser  or  (for  Linux)  having  capability
1085                  CAP_SYS_ADMIN  according  to the documentation for setns(2).
1086                  However,   during   testing    also    CAP_SYS_PTRACE    and
1087                  CAP_DAC_READ_SEARCH have proven to be necessary.
1088
1089                  Example:
1090
1091                setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp
1092
1093                  Notice  that  the  filesystem containing the virtual machine
1094                  executable (beam.smp in the example) must be local,  mounted
1095                  without  flag nosetuid, support extended attributes, and the
1096                  kernel must support file capabilities. All this runs out  of
1097                  the box on at least Ubuntu 12.04 LTS, except that SCTP sock‐
1098                  ets appear to not support network namespaces.
1099
1100                  Namespace is a filename and is encoded and decoded  as  dis‐
1101                  cussed in module file, with the following exceptions:
1102
1103                  * Emulator flag +fnu is ignored.
1104
1105                  * getopts/2  for  this option returns a binary for the file‐
1106                    name if the stored filename cannot  be  decoded.  This  is
1107                    only  to  occur  if you set the option using a binary that
1108                    cannot be decoded with the emulator's  filename  encoding:
1109                    file:native_name_encoding/0.
1110
1111                {bind_to_device, Ifname :: binary()}:
1112                  Binds  a socket to a specific network interface. This option
1113                  must be used in a function call that creates a socket,  that
1114                  is, gen_tcp:connect/3,4, gen_tcp:listen/2, gen_udp:open/1,2,
1115                  or gen_sctp:open/0,1,2.
1116
1117                  Unlike getifaddrs/0, Ifname is encoded a binary. In the  un‐
1118                  likely  case  that a system is using non-7-bit-ASCII charac‐
1119                  ters in network device names, special care has to  be  taken
1120                  when encoding this argument.
1121
1122                  This  option  uses the Linux-specific socket option SO_BIND‐
1123                  TODEVICE, such as in  Linux  kernel  2.0.30  or  later,  and
1124                  therefore  only  exists  when the runtime system is compiled
1125                  for such an operating system.
1126
1127                  Before Linux 3.8, this socket option could be set, but could
1128                  not  retrieved  with getopts/2. Since Linux 3.8, it is read‐
1129                  able.
1130
1131                  The virtual machine also needs elevated  privileges,  either
1132                  running  as  superuser  or  (for  Linux)  having  capability
1133                  CAP_NET_RAW.
1134
1135                  The primary use case for this option is to bind sockets into
1136                  Linux VRF instances.
1137
1138                list:
1139                  Received Packet is delivered as a list.
1140
1141                binary:
1142                  Received Packet is delivered as a binary.
1143
1144                {nodelay, Boolean}(TCP/IP sockets):
1145                  If  Boolean == true, option TCP_NODELAY is turned on for the
1146                  socket, which means that also small amounts of data are sent
1147                  immediately.
1148
1149                  This  option  is  not  supported  for domain = local, but if
1150                  inet_backend =/= socket this error will be ignored.
1151
1152                {nopush, Boolean}(TCP/IP sockets):
1153                  This translates to TCP_NOPUSH on  BSD  and  to  TCP_CORK  on
1154                  Linux.
1155
1156                  If  Boolean  ==  true, the corresponding option is turned on
1157                  for the socket, which means that small amounts of  data  are
1158                  accumulated  until  a full MSS-worth of data is available or
1159                  this option is turned off.
1160
1161                  Note that while TCP_NOPUSH socket  option  is  available  on
1162                  OSX,  its  semantics  is  very different (e.g., unsetting it
1163                  does not cause immediate send of accumulated  data).  Hence,
1164                  nopush option is intentionally ignored on OSX.
1165
1166                {packet, PacketType}(TCP/IP sockets):
1167                  Defines  the  type  of packets to use for a socket. Possible
1168                  values:
1169
1170                  raw | 0:
1171                    No packaging is done.
1172
1173                  1 | 2 | 4:
1174                    Packets consist of a header specifying the number of bytes
1175                    in  the  packet,  followed  by  that  number of bytes. The
1176                    header length can be one, two, or four bytes, and contain‐
1177                    ing  an  unsigned  integer  in big-endian byte order. Each
1178                    send operation generates the header,  and  the  header  is
1179                    stripped off on each receive operation.
1180
1181                    The 4-byte header is limited to 2Gb.
1182
1183                  asn1 | cdr | sunrm | fcgi | tpkt | line:
1184                    These  packet  types  only  have effect on receiving. When
1185                    sending a packet, it is the responsibility of the applica‐
1186                    tion  to  supply  a correct header. On receiving, however,
1187                    one message is sent to the controlling  process  for  each
1188                    complete  packet  received,  and,  similarly, each call to
1189                    gen_tcp:recv/2,3 returns one complete packet.  The  header
1190                    is not stripped off.
1191
1192                    The meanings of the packet types are as follows:
1193
1194                    * asn1 - ASN.1 BER
1195
1196                    * sunrm - Sun's RPC encoding
1197
1198                    * cdr - CORBA (GIOP 1.1)
1199
1200                    * fcgi - Fast CGI
1201
1202                    * tpkt - TPKT format [RFC1006]
1203
1204                    * line  -  Line  mode,  a packet is a line-terminated with
1205                      newline, lines longer than the receive buffer are  trun‐
1206                      cated
1207
1208                  http | http_bin:
1209                    The  Hypertext Transfer Protocol. The packets are returned
1210                    with the format according to HttpPacket described  in  er‐
1211                    lang:decode_packet/3 in ERTS. A socket in passive mode re‐
1212                    turns {ok, HttpPacket} from gen_tcp:recv while  an  active
1213                    socket sends messages like {http, Socket, HttpPacket}.
1214
1215                  httph | httph_bin:
1216                    These  two types are often not needed, as the socket auto‐
1217                    matically switches from http/http_bin  to  httph/httph_bin
1218                    internally  after  the  first line is read. However, there
1219                    can be occasions when they are  useful,  such  as  parsing
1220                    trailers from chunked encoding.
1221
1222                {packet_size, Integer}(TCP/IP sockets):
1223                  Sets  the  maximum allowed length of the packet body. If the
1224                  packet header indicates that the length  of  the  packet  is
1225                  longer  than  the maximum allowed length, the packet is con‐
1226                  sidered invalid. The same occurs if the packet header is too
1227                  large for the socket receive buffer.
1228
1229                  For    line-oriented   protocols   (line,   http*),   option
1230                  packet_size also guarantees that lines up to  the  indicated
1231                  length  are  accepted  and not considered invalid because of
1232                  internal buffer limitations.
1233
1234                {line_delimiter, Char}(TCP/IP sockets):
1235                  Sets the line delimiting character for line-oriented  proto‐
1236                  cols (line). Defaults to $\n.
1237
1238                {raw, Protocol, OptionNum, ValueBin}:
1239                  See below.
1240
1241                {read_packets, Integer}(UDP sockets):
1242                  Sets  the  maximum number of UDP packets to read without in‐
1243                  tervention from the socket when data is available. When this
1244                  many packets have been read and delivered to the destination
1245                  process, new packets are not read until a  new  notification
1246                  of available data has arrived. Defaults to 5. If this param‐
1247                  eter is set too high, the system can become unresponsive be‐
1248                  cause of UDP packet flooding.
1249
1250                {recbuf, Size}:
1251                  The  minimum  size  of  the  receive  buffer  to use for the
1252                  socket. You are encouraged to use getopts/2 to retrieve  the
1253                  size set by your operating system.
1254
1255                {recvtclass, Boolean}:
1256                  If set to true activates returning the received TCLASS value
1257                  on platforms that implements the protocol  IPPROTO_IPV6  op‐
1258                  tion  IPV6_RECVTCLASS or IPV6_2292RECVTCLASS for the socket.
1259                  The value is returned as a {tclass,TCLASS} tuple  regardless
1260                  of  if the platform returns an IPV6_TCLASS or an IPV6_RECVT‐
1261                  CLASS CMSG value.
1262
1263                  For packet oriented sockets that supports  receiving  ancil‐
1264                  lary  data with the payload data (gen_udp and gen_sctp), the
1265                  TCLASS value is returned in an extended  return  tuple  con‐
1266                  tained  in  an   ancillary  data   list. For stream oriented
1267                  sockets (gen_tcp) the only way to get the TCLASS value is if
1268                  the platform supports the pktoptions option.
1269
1270                {recvtos, Boolean}:
1271                  If set to true activates returning the received TOS value on
1272                  platforms that implements  the  protocol  IPPROTO_IP  option
1273                  IP_RECVTOS  for  the  socket.  The  value  is  returned as a
1274                  {tos,TOS} tuple regardless of if  the  platform  returns  an
1275                  IP_TOS or an IP_RECVTOS CMSG value.
1276
1277                  For  packet  oriented sockets that supports receiving ancil‐
1278                  lary data with the payload data (gen_udp and gen_sctp),  the
1279                  TOS  value is returned in an extended return tuple contained
1280                  in an  ancillary data  list.  For  stream  oriented  sockets
1281                  (gen_tcp)  the only way to get the TOS value is if the plat‐
1282                  form supports the pktoptions option.
1283
1284                {recvttl, Boolean}:
1285                  If set to true activates returning the received TTL value on
1286                  platforms  that  implements  the  protocol IPPROTO_IP option
1287                  IP_RECVTTL for the  socket.  The  value  is  returned  as  a
1288                  {ttl,TTL}  tuple  regardless  of  if the platform returns an
1289                  IP_TTL or an IP_RECVTTL CMSG value.
1290
1291                  For packet oriented sockets that supports  receiving  ancil‐
1292                  lary  data with the payload data (gen_udp and gen_sctp), the
1293                  TTL value is returned in an extended return tuple  contained
1294                  in  an   ancillary  data   list. For stream oriented sockets
1295                  (gen_tcp) the only way to get the TTL value is if the  plat‐
1296                  form supports the pktoptions option.
1297
1298                {reuseaddr, Boolean}:
1299                  Allows  or disallows local reuse of address. By default, re‐
1300                  use is disallowed.
1301
1302            Note:
1303                On Windows this option will be ignored unless Socket is an UDP
1304                socket. This since the behavior of reuseaddr is very different
1305                on Windows compared to other system.
1306
1307
1308                {send_timeout, Integer}:
1309                  Only allowed for connection-oriented sockets.
1310
1311                  Specifies a longest time to wait for a send operation to  be
1312                  accepted  by the underlying TCP stack. When the limit is ex‐
1313                  ceeded, the send operation returns {error,timeout}. How much
1314                  of  a  packet that got sent is unknown; the socket is there‐
1315                  fore to be closed whenever  a  time-out  has  occurred  (see
1316                  send_timeout_close below). Defaults to infinity.
1317
1318                {send_timeout_close, Boolean}:
1319                  Only allowed for connection-oriented sockets.
1320
1321                  Used  together  with  send_timeout  to  specify  whether the
1322                  socket is to be automatically closed when the send operation
1323                  returns  {error,timeout}.  The  recommended setting is true,
1324                  which automatically closes the socket. Defaults to false be‐
1325                  cause of backward compatibility.
1326
1327                {show_econnreset, Boolean} (TCP/IP sockets) :
1328                  When  this  option is set to false, which is default, an RST
1329                  received from the TCP peer is treated as a normal close  (as
1330                  though  an  FIN  was  sent). A caller to gen_tcp:recv/2 gets
1331                  {error, closed}. In active mode, the controlling process re‐
1332                  ceives  a  {tcp_closed, Socket} message, indicating that the
1333                  peer has closed the connection.
1334
1335                  Setting this option to true allows you  to  distinguish  be‐
1336                  tween  a  connection  that was closed normally, and one that
1337                  was aborted (intentionally or unintentionally)  by  the  TCP
1338                  peer.  A call to gen_tcp:recv/2 returns {error, econnreset}.
1339                  In active mode, the controlling process receives a  {tcp_er‐
1340                  ror,   Socket,   econnreset}   message   before   the  usual
1341                  {tcp_closed, Socket}, as is the case for  any  other  socket
1342                  error. Calls to gen_tcp:send/2 also returns {error, econnre‐
1343                  set} when it is detected that a TCP peer has sent an RST.
1344
1345                  A connected socket returned from  gen_tcp:accept/1  inherits
1346                  the show_econnreset setting from the listening socket.
1347
1348                {sndbuf, Size}:
1349                  The  minimum  size of the send buffer to use for the socket.
1350                  You are encouraged to use getopts/2, to  retrieve  the  size
1351                  set by your operating system.
1352
1353                {priority, Integer}:
1354                  Sets  the SO_PRIORITY socket level option on platforms where
1355                  this is implemented. The behavior and allowed  range  varies
1356                  between  different  systems.  The option is ignored on plat‐
1357                  forms where it is not implemented. Use with caution.
1358
1359                {tos, Integer}:
1360                  Sets IP_TOS IP level options on platforms where this is  im‐
1361                  plemented.  The  behavior  and  allowed range varies between
1362                  different systems. The option is ignored on platforms  where
1363                  it is not implemented. Use with caution.
1364
1365                {tclass, Integer}:
1366                  Sets IPV6_TCLASS IP level options on platforms where this is
1367                  implemented. The behavior and allowed range  varies  between
1368                  different  systems. The option is ignored on platforms where
1369                  it is not implemented. Use with caution.
1370
1371              In addition to these options, raw option specifications  can  be
1372              used.  The  raw  options are specified as a tuple of arity four,
1373              beginning with tag raw, followed by the protocol level, the  op‐
1374              tion  number,  and  the option value specified as a binary. This
1375              corresponds to the second, third, and fourth  arguments  to  the
1376              setsockopt  call  in  the C socket API. The option value must be
1377              coded in the native endianness of the platform and, if a  struc‐
1378              ture  is  required,  must follow the structure alignment conven‐
1379              tions on the specific platform.
1380
1381              Using raw socket options requires detailed knowledge  about  the
1382              current operating system and TCP stack.
1383
1384              Example:
1385
1386              This  example  concerns the use of raw options. Consider a Linux
1387              system where you want to  set  option  TCP_LINGER2  on  protocol
1388              level IPPROTO_TCP in the stack. You know that on this particular
1389              system it defaults to 60 (seconds), but you want to lower it  to
1390              30 for a particular socket. Option TCP_LINGER2 is not explicitly
1391              supported by inet, but you know that the protocol  level  trans‐
1392              lates  to number 6, the option number to number 8, and the value
1393              is to be specified as a 32-bit integer. You can  use  this  code
1394              line to set the option for the socket named Sock:
1395
1396              inet:setopts(Sock,[{raw,6,8,<<30:32/native>>}]),
1397
1398              As  many options are silently discarded by the stack if they are
1399              specified out of range; it can be a good idea to  check  that  a
1400              raw  option  is accepted. The following code places the value in
1401              variable TcpLinger2:
1402
1403              {ok,[{raw,6,8,<<TcpLinger2:32/native>>}]}=inet:getopts(Sock,[{raw,6,8,4}]),
1404
1405              Code such as these examples  is  inherently  non-portable,  even
1406              different  versions  of the same OS on the same platform can re‐
1407              spond differently to this kind of option manipulation. Use  with
1408              care.
1409
1410              Notice  that  the  default  options  for  TCP/IP  sockets can be
1411              changed with the Kernel configuration  parameters  mentioned  in
1412              the beginning of this manual page.
1413
1414       sockname(Socket :: socket()) ->
1415                   {ok,
1416                    {ip_address(), port_number()} |
1417                    returned_non_ip_address()} |
1418                   {error, posix()}
1419
1420              Returns the local address and port number for a socket.
1421
1422              Notice  that  for SCTP sockets this function returns only one of
1423              the socket addresses. Function socknames/1,2 returns all.
1424
1425       socknames(Socket :: socket()) ->
1426                    {ok,
1427                     [{ip_address(), port_number()} |
1428                      returned_non_ip_address()]} |
1429                    {error, posix()}
1430
1431              Equivalent to socknames(Socket, 0).
1432
1433       socknames(Socket, Assoc) ->
1434                    {ok, [{Address, Port}]} | {error, posix()}
1435
1436              Types:
1437
1438                 Socket = socket()
1439                 Assoc = #sctp_assoc_change{} | gen_sctp:assoc_id()
1440                 Address = ip_address()
1441                 Port = integer() >= 0
1442
1443              Returns a list of all local  address/port  number  pairs  for  a
1444              socket for the specified association Assoc.
1445
1446              This function can return multiple addresses for multihomed sock‐
1447              ets, such as SCTP sockets. For other sockets it returns  a  one-
1448              element list.
1449
1450              Notice  that  parameter  Assoc is by the SCTP Sockets API Exten‐
1451              sions defined to be ignored for one-to-one  style  sockets.  For
1452              one-to-many  style  sockets,  the  special value 0 is defined to
1453              mean that the returned addresses must be without any  particular
1454              association.  How  different SCTP implementations interpret this
1455              varies somewhat.
1456

POSIX ERROR CODES

1458         * e2big - Too long argument list
1459
1460         * eacces - Permission denied
1461
1462         * eaddrinuse - Address already in use
1463
1464         * eaddrnotavail - Cannot assign requested address
1465
1466         * eadv - Advertise error
1467
1468         * eafnosupport - Address family not supported by protocol family
1469
1470         * eagain - Resource temporarily unavailable
1471
1472         * ealign - EALIGN
1473
1474         * ealready - Operation already in progress
1475
1476         * ebade - Bad exchange descriptor
1477
1478         * ebadf - Bad file number
1479
1480         * ebadfd - File descriptor in bad state
1481
1482         * ebadmsg - Not a data message
1483
1484         * ebadr - Bad request descriptor
1485
1486         * ebadrpc - Bad RPC structure
1487
1488         * ebadrqc - Bad request code
1489
1490         * ebadslt - Invalid slot
1491
1492         * ebfont - Bad font file format
1493
1494         * ebusy - File busy
1495
1496         * echild - No children
1497
1498         * echrng - Channel number out of range
1499
1500         * ecomm - Communication error on send
1501
1502         * econnaborted - Software caused connection abort
1503
1504         * econnrefused - Connection refused
1505
1506         * econnreset - Connection reset by peer
1507
1508         * edeadlk - Resource deadlock avoided
1509
1510         * edeadlock - Resource deadlock avoided
1511
1512         * edestaddrreq - Destination address required
1513
1514         * edirty - Mounting a dirty fs without force
1515
1516         * edom - Math argument out of range
1517
1518         * edotdot - Cross mount point
1519
1520         * edquot - Disk quota exceeded
1521
1522         * eduppkg - Duplicate package name
1523
1524         * eexist - File already exists
1525
1526         * efault - Bad address in system call argument
1527
1528         * efbig - File too large
1529
1530         * ehostdown - Host is down
1531
1532         * ehostunreach - Host is unreachable
1533
1534         * eidrm - Identifier removed
1535
1536         * einit - Initialization error
1537
1538         * einprogress - Operation now in progress
1539
1540         * eintr - Interrupted system call
1541
1542         * einval - Invalid argument
1543
1544         * eio - I/O error
1545
1546         * eisconn - Socket is already connected
1547
1548         * eisdir - Illegal operation on a directory
1549
1550         * eisnam - Is a named file
1551
1552         * el2hlt - Level 2 halted
1553
1554         * el2nsync - Level 2 not synchronized
1555
1556         * el3hlt - Level 3 halted
1557
1558         * el3rst - Level 3 reset
1559
1560         * elbin - ELBIN
1561
1562         * elibacc - Cannot access a needed shared library
1563
1564         * elibbad - Accessing a corrupted shared library
1565
1566         * elibexec - Cannot exec a shared library directly
1567
1568         * elibmax - Attempting to link in more shared libraries  than  system
1569           limit
1570
1571         * elibscn - .lib section in a.out corrupted
1572
1573         * elnrng - Link number out of range
1574
1575         * eloop - Too many levels of symbolic links
1576
1577         * emfile - Too many open files
1578
1579         * emlink - Too many links
1580
1581         * emsgsize - Message too long
1582
1583         * emultihop - Multihop attempted
1584
1585         * enametoolong - Filename too long
1586
1587         * enavail - Unavailable
1588
1589         * enet - ENET
1590
1591         * enetdown - Network is down
1592
1593         * enetreset - Network dropped connection on reset
1594
1595         * enetunreach - Network is unreachable
1596
1597         * enfile - File table overflow
1598
1599         * enoano - Anode table overflow
1600
1601         * enobufs - No buffer space available
1602
1603         * enocsi - No CSI structure available
1604
1605         * enodata - No data available
1606
1607         * enodev - No such device
1608
1609         * enoent - No such file or directory
1610
1611         * enoexec - Exec format error
1612
1613         * enolck - No locks available
1614
1615         * enolink - Link has been severed
1616
1617         * enomem - Not enough memory
1618
1619         * enomsg - No message of desired type
1620
1621         * enonet - Machine is not on the network
1622
1623         * enopkg - Package not installed
1624
1625         * enoprotoopt - Bad protocol option
1626
1627         * enospc - No space left on device
1628
1629         * enosr - Out of stream resources or not a stream device
1630
1631         * enosym - Unresolved symbol name
1632
1633         * enosys - Function not implemented
1634
1635         * enotblk - Block device required
1636
1637         * enotconn - Socket is not connected
1638
1639         * enotdir - Not a directory
1640
1641         * enotempty - Directory not empty
1642
1643         * enotnam - Not a named file
1644
1645         * enotsock - Socket operation on non-socket
1646
1647         * enotsup - Operation not supported
1648
1649         * enotty - Inappropriate device for ioctl
1650
1651         * enotuniq - Name not unique on network
1652
1653         * enxio - No such device or address
1654
1655         * eopnotsupp - Operation not supported on socket
1656
1657         * eperm - Not owner
1658
1659         * epfnosupport - Protocol family not supported
1660
1661         * epipe - Broken pipe
1662
1663         * eproclim - Too many processes
1664
1665         * eprocunavail - Bad procedure for program
1666
1667         * eprogmismatch - Wrong program version
1668
1669         * eprogunavail - RPC program unavailable
1670
1671         * eproto - Protocol error
1672
1673         * eprotonosupport - Protocol not supported
1674
1675         * eprototype - Wrong protocol type for socket
1676
1677         * erange - Math result unrepresentable
1678
1679         * erefused - EREFUSED
1680
1681         * eremchg - Remote address changed
1682
1683         * eremdev - Remote device
1684
1685         * eremote - Pathname hit remote filesystem
1686
1687         * eremoteio - Remote I/O error
1688
1689         * eremoterelease - EREMOTERELEASE
1690
1691         * erofs - Read-only filesystem
1692
1693         * erpcmismatch - Wrong RPC version
1694
1695         * erremote - Object is remote
1696
1697         * eshutdown - Cannot send after socket shutdown
1698
1699         * esocktnosupport - Socket type not supported
1700
1701         * espipe - Invalid seek
1702
1703         * esrch - No such process
1704
1705         * esrmnt - Srmount error
1706
1707         * estale - Stale remote file handle
1708
1709         * esuccess - Error 0
1710
1711         * etime - Timer expired
1712
1713         * etimedout - Connection timed out
1714
1715         * etoomanyrefs - Too many references
1716
1717         * etxtbsy - Text file or pseudo-device busy
1718
1719         * euclean - Structure needs cleaning
1720
1721         * eunatch - Protocol driver not attached
1722
1723         * eusers - Too many users
1724
1725         * eversion - Version mismatch
1726
1727         * ewouldblock - Operation would block
1728
1729         * exdev - Cross-domain link
1730
1731         * exfull - Message tables full
1732
1733         * nxdomain - Hostname or domain name cannot be found
1734
1735Ericsson AB                     kernel 8.5.4.2                         inet(3)
Impressum