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,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       hostent() =
72           #hostent{h_name = inet:hostname(),
73                    h_aliases = [inet:hostname()],
74                    h_addrtype = inet | inet6,
75                    h_length = integer() >= 0,
76                    h_addr_list = [inet:ip_address()]}
77
78              The record is defined in the Kernel include file "inet.hrl".
79
80              Add the following directive to the module:
81
82              -include_lib("kernel/include/inet.hrl").
83
84       hostname() = atom() | string()
85
86       ip_address() = ip4_address() | ip6_address()
87
88       ip4_address() = {0..255, 0..255, 0..255, 0..255}
89
90       ip6_address() =
91           {0..65535,
92            0..65535,
93            0..65535,
94            0..65535,
95            0..65535,
96            0..65535,
97            0..65535,
98            0..65535}
99
100       port_number() = 0..65535
101
102       local_address() = {local, File :: binary() | string()}
103
104              This address family only works on Unix-like systems.
105
106              File  is  normally  a file pathname in a local filesystem. It is
107              limited in length by the operating system, traditionally to  108
108              bytes.
109
110              A  binary()  is  passed  as  is  to  the operating system, but a
111              string() is encoded according to the  system  filename  encoding
112              mode.
113
114              Other  addresses  are  possible,  for  example  Linux implements
115              "Abstract Addresses". See  the  documentation  for  Unix  Domain
116              Sockets on your system, normally unix in manual section 7.
117
118              In  most API functions where you can use this address family the
119              port number must be 0.
120
121       socket_address() =
122           ip_address() | any | loopback | local_address()
123
124       socket_getopt() =
125           gen_sctp:option_name() |
126           gen_tcp:option_name() |
127           gen_udp:option_name()
128
129       socket_setopt() =
130           gen_sctp:option() | gen_tcp:option() | gen_udp:option()
131
132       returned_non_ip_address() =
133           {local, binary()} | {unspec, <<>>} | {undefined, any()}
134
135              Addresses besides  ip_address()  ones  that  are  returned  from
136              socket  API  functions.  See in particular local_address().  The
137              unspec family corresponds to AF_UNSPEC  and  can  occur  if  the
138              other  side has no socket address. The undefined family can only
139              occur in the unlikely event of an address  family  that  the  VM
140              does not recognize.
141
142       ancillary_data() =
143           [{tos, byte()} | {tclass, byte()} | {ttl, byte()}]
144
145              Ancillary  data  received  with the data packet or read with the
146              socket option pktoptions from a TCP socket.
147
148              The value(s) correspond to the currently active  socket  options
149              recvtos, recvtclass and recvttl.
150
151       getifaddrs_ifopts() =
152           [Ifopt ::
153                {flags,
154                 Flags ::
155                     [up |
156                      broadcast |
157                      loopback |
158                      pointtopoint |
159                      running |
160                      multicast]} |
161                {addr, Addr :: ip_address()} |
162                {netmask, Netmask :: ip_address()} |
163                {broadaddr, Broadaddr :: ip_address()} |
164                {dstaddr, Dstaddr :: ip_address()} |
165                {hwaddr, Hwaddr :: [byte()]}]
166
167              Interface  address description list returned from getifaddrs/0,1
168              for a named interface, translated from the returned data of  the
169              POSIX API function getaddrinfo().
170
171              Hwaddr  is  hardware  dependent, for example, on Ethernet inter‐
172              faces it is the 6-byte Ethernet  address  (MAC  address  (EUI-48
173              address)).
174
175              The  tuples {addr,Addr}, {netmask,Netmask}, and possibly {broad‐
176              addr,Broadaddr} or {dstaddr,Dstaddr} are repeated in the list if
177              the  interface has got multiple addresses. An interface may have
178              multiple {flag,_} tuples for example if it has  different  flags
179              for  different address families. Multiple {hwaddr,Hwaddr} tuples
180              is hard to  say  anything  definite  about,  though.  The  tuple
181              {flag,Flags} is mandatory, all others are optional.
182
183              Do  not  rely  too much on the order of Flags atoms or the Ifopt
184              tuples. There are however some rules:
185
186                * A {flag,_} tuple applies to all other tuples that follow.
187
188                * Immediately after {addr,_} follows {netmask,_}.
189
190                * Immediately thereafter may {broadaddr,_} follow if broadcast
191                  is member of Flags, or {dstaddr,_} if pointtopoint is member
192                  of Flags. Both {dstaddr,_} and {broadaddr,_} does not  occur
193                  for the same {addr,_}.
194
195                * Any  {netmask,_},  {broadaddr,_}, or {dstaddr,_} tuples that
196                  follow an {addr,Addr} tuple concerns the address Addr.
197
198              The tuple {hwaddr,_} is not returned on Solaris, as the hardware
199              address  historically  belongs  to  the link layer and it is not
200              returned by the Solaris API function getaddrinfo().
201
202          Warning:
203              On Windows, the data is fetched from different OS API functions,
204              so  the  Netmask and Broadaddr values may be calculated, just as
205              some Flags values.
206
207
208       posix() =
209           eaddrinuse |
210           eaddrnotavail |
211           eafnosupport |
212           ealready |
213           econnaborted |
214           econnrefused |
215           econnreset |
216           edestaddrreq |
217           ehostdown |
218           ehostunreach |
219           einprogress |
220           eisconn |
221           emsgsize |
222           enetdown |
223           enetunreach |
224           enopkg |
225           enoprotoopt |
226           enotconn |
227           enotty |
228           enotsock |
229           eproto |
230           eprotonosupport |
231           eprototype |
232           esocktnosupport |
233           etimedout |
234           ewouldblock |
235           exbadport |
236           exbadseq |
237           file:posix()
238
239              An atom that is named from the POSIX error codes used  in  Unix,
240              and  in  the  runtime libraries of most C compilers. See section
241              POSIX Error Codes.
242
243       socket()
244
245              See gen_tcp:type-socket and gen_udp:type-socket.
246
247       address_family() = inet | inet6 | local
248
249       socket_protocol() = tcp | udp | sctp
250
251       stat_option() =
252           recv_cnt |
253           recv_max |
254           recv_avg |
255           recv_oct |
256           recv_dvi |
257           send_cnt |
258           send_max |
259           send_avg |
260           send_oct |
261           send_pend
262

EXPORTS

264       close(Socket) -> ok
265
266              Types:
267
268                 Socket = socket()
269
270              Closes a socket of any type.
271
272       format_error(Reason) -> string()
273
274              Types:
275
276                 Reason = posix() | system_limit
277
278              Returns a diagnostic error string. For possible POSIX values and
279              corresponding strings, see section POSIX Error Codes.
280
281       get_rc() ->
282                 [{Par :: atom(), Val :: any()} |
283                  {Par :: atom(), Val1 :: any(), Val2 :: any()}]
284
285              Returns  the state of the Inet configuration database in form of
286              a list of recorded configuration parameters. For  more  informa‐
287              tion, see ERTS User's Guide: Inet Configuration.
288
289              Only  actual  parameters  with  other  than  default  values are
290              returned, for example not directives that specify other  sources
291              for  configuration  parameters nor directives that clear parame‐
292              ters.
293
294       getaddr(Host, Family) -> {ok, Address} | {error, posix()}
295
296              Types:
297
298                 Host = ip_address() | hostname()
299                 Family = address_family()
300                 Address = ip_address()
301
302              Returns the IP address for Host as a tuple of integers. Host can
303              be  an IP address, a single hostname, or a fully qualified host‐
304              name.
305
306       getaddrs(Host, Family) -> {ok, Addresses} | {error, posix()}
307
308              Types:
309
310                 Host = ip_address() | hostname()
311                 Family = address_family()
312                 Addresses = [ip_address()]
313
314              Returns a list of all IP addresses for Host. Host can be  an  IP
315              address, a single hostname, or a fully qualified hostname.
316
317       gethostbyaddr(Address) -> {ok, Hostent} | {error, posix()}
318
319              Types:
320
321                 Address = string() | ip_address()
322                 Hostent = hostent()
323
324              Returns  a  hostent  record  for  the  host  with  the specified
325              address.
326
327       gethostbyname(Hostname) -> {ok, Hostent} | {error, posix()}
328
329              Types:
330
331                 Hostname = hostname()
332                 Hostent = hostent()
333
334              Returns a hostent record for the host with the  specified  host‐
335              name.
336
337              If resolver option inet6 is true, an IPv6 address is looked up.
338
339       gethostbyname(Hostname, Family) ->
340                        {ok, Hostent} | {error, posix()}
341
342              Types:
343
344                 Hostname = hostname()
345                 Family = address_family()
346                 Hostent = hostent()
347
348              Returns  a  hostent record for the host with the specified name,
349              restricted to the specified address family.
350
351       gethostname() -> {ok, Hostname}
352
353              Types:
354
355                 Hostname = string()
356
357              Returns the local hostname. Never fails.
358
359       getifaddrs() ->
360                     {ok,
361                      [{Ifname :: string(),
362                        Ifopts :: getifaddrs_ifopts()}]} |
363                     {error, posix()}
364
365              Returns a list of 2-tuples containing interface  names  and  the
366              interfaces'  addresses. Ifname is a Unicode string and Ifopts is
367              a list of interface address description tuples.
368
369              The interface address description tuples  are  documented  under
370              the type of the Ifopts value.
371
372       getifaddrs(Opts) -> {ok, [{Ifname, Ifopts}]} | {error, Posix}
373
374              Types:
375
376                  Opts = [{netns, Namespace}]
377                  Namespace =  file:filename_all()
378                 Ifname = string()
379                  Ifopts =  getifaddrs_ifopts()
380                 Posix = posix()
381
382              The  same as getifaddrs/0 but the Option {netns, Namespace} sets
383              a network namespace for the OS call, on platforms that  supports
384              that feature.
385
386              See the socket option {netns, Namespace} under setopts/2.
387
388       getopts(Socket, Options) -> {ok, OptionValues} | {error, posix()}
389
390              Types:
391
392                 Socket = socket()
393                 Options = [socket_getopt()]
394                 OptionValues = [socket_setopt() | gen_tcp:pktoptions_value()]
395
396              Gets  one  or more options for a socket. For a list of available
397              options, see setopts/2. See also the description  for  the  type
398              gen_tcp:pktoptions_value().
399
400              The  number  of  elements in the returned OptionValues list does
401              not necessarily correspond to the number of options  asked  for.
402              If  the  operating system fails to support an option, it is left
403              out in the returned list. An error tuple is returned  only  when
404              getting  options  for  the  socket  is  impossible (that is, the
405              socket is closed or the buffer size in  a  raw  request  is  too
406              large).  This  behavior  is kept for backward compatibility rea‐
407              sons.
408
409              A raw option request RawOptReq = {raw, Protocol, OptionNum, Val‐
410              ueSpec}  can be used to get information about socket options not
411              (explicitly) supported by the emulator. The use  of  raw  socket
412              options  makes the code non-portable, but allows the Erlang pro‐
413              grammer to take advantage of unusual features present on a  par‐
414              ticular platform.
415
416              RawOptReq  consists  of  tag raw followed by the protocol level,
417              the option number, and either a binary or the size, in bytes, of
418              the  buffer  in which the option value is to be stored. A binary
419              is to be used when the underlying getsockopt requires  input  in
420              the  argument  field. In this case, the binary size is to corre‐
421              spond to the required buffer size of the return value. The  sup‐
422              plied values in a RawOptReq correspond to the second, third, and
423              fourth/fifth parameters to the getsockopt call in the  C  socket
424              API. The value stored in the buffer is returned as a binary Val‐
425              ueBin, where all values are coded in the native endianess.
426
427              Asking for and inspecting raw socket options  require  low-level
428              information about the current operating system and TCP stack.
429
430              Example:
431
432              Consider  a  Linux  machine where option TCP_INFO can be used to
433              collect TCP statistics for a socket. Assume you  are  interested
434              in  field  tcpi_sacked  of struct tcp_info filled in when asking
435              for TCP_INFO. To be able to access this information, you need to
436              know the following:
437
438                * The numeric value of protocol level IPPROTO_TCP
439
440                * The numeric value of option TCP_INFO
441
442                * The size of struct tcp_info
443
444                * The size and offset of the specific field
445
446              By  inspecting  the  headers or writing a small C program, it is
447              found that IPPROTO_TCP is 6, TCP_INFO is 11, the structure  size
448              is  92  (bytes),  the offset of tcpi_sacked is 28 bytes, and the
449              value is a 32-bit integer. The following code  can  be  used  to
450              retrieve the value:
451
452              get_tcpi_sacked(Sock) ->
453                  {ok,[{raw,_,_,Info}]} = inet:getopts(Sock,[{raw,6,11,92}]),
454                  <<_:28/binary,TcpiSacked:32/native,_/binary>> = Info,
455                  TcpiSacked.
456
457              Preferably, you would check the machine type, the operating sys‐
458              tem, and the Kernel version before executing anything similar to
459              this code.
460
461       getstat(Socket) -> {ok, OptionValues} | {error, posix()}
462
463       getstat(Socket, Options) -> {ok, OptionValues} | {error, posix()}
464
465              Types:
466
467                 Socket = socket()
468                 Options = [stat_option()]
469                 OptionValues = [{stat_option(), integer()}]
470                 stat_option() =
471                     recv_cnt |
472                     recv_max |
473                     recv_avg |
474                     recv_oct |
475                     recv_dvi |
476                     send_cnt |
477                     send_max |
478                     send_avg |
479                     send_oct |
480                     send_pend
481
482              Gets one or more statistic options for a socket.
483
484              getstat(Socket)  is  equivalent  to  getstat(Socket,  [recv_avg,
485              recv_cnt,  recv_dvi,  recv_max,  recv_oct,  send_avg,  send_cnt,
486              send_dvi, send_max, send_oct]).
487
488              The following options are available:
489
490                recv_avg:
491                  Average size of packets, in bytes, received by the socket.
492
493                recv_cnt:
494                  Number of packets received by the socket.
495
496                recv_dvi:
497                  Average  packet  size  deviation,  in bytes, received by the
498                  socket.
499
500                recv_max:
501                  Size of the  largest  packet,  in  bytes,  received  by  the
502                  socket.
503
504                recv_oct:
505                  Number of bytes received by the socket.
506
507                send_avg:
508                  Average size of packets, in bytes, sent from the socket.
509
510                send_cnt:
511                  Number of packets sent from the socket.
512
513                send_dvi:
514                  Average  packet  size  deviation,  in  bytes,  sent from the
515                  socket.
516
517                send_max:
518                  Size of the largest packet, in bytes, sent from the socket.
519
520                send_oct:
521                  Number of bytes sent from the socket.
522
523       i() -> ok
524
525       i(Proto :: socket_protocol()) -> ok
526
527       i(X1 :: socket_protocol(), Fs :: [atom()]) -> ok
528
529              Lists all TCP, UDP and SCTP sockets, including  those  that  the
530              Erlang  runtime  system  uses  as  well  as those created by the
531              application.
532
533              The following options are available:
534
535                port:
536                  The internal index of the port.
537
538                module:
539                  The callback module of the socket.
540
541                recv:
542                  Number of bytes received by the socket.
543
544                sent:
545                  Number of bytes sent from the socket.
546
547                owner:
548                  The socket owner process.
549
550                local_address:
551                  The local address of the socket.
552
553                foreign_address:
554                  The address and port of the other end of the connection.
555
556                state:
557                  The connection state.
558
559                type:
560                  STREAM or DGRAM or SEQPACKET.
561
562       ntoa(IpAddress) -> Address | {error, einval}
563
564              Types:
565
566                 Address = string()
567                 IpAddress = ip_address()
568
569              Parses an ip_address() and  returns  an  IPv4  or  IPv6  address
570              string.
571
572       parse_address(Address) -> {ok, IPAddress} | {error, einval}
573
574              Types:
575
576                 Address = string()
577                 IPAddress = ip_address()
578
579              Parses   an   IPv4   or  IPv6  address  string  and  returns  an
580              ip4_address() or ip6_address(). Accepts a shortened IPv4 address
581              string.
582
583       parse_ipv4_address(Address) -> {ok, IPv4Address} | {error, einval}
584
585              Types:
586
587                 Address = string()
588                 IPv4Address = ip_address()
589
590              Parses  an  IPv4  address  string  and returns an ip4_address().
591              Accepts a shortened IPv4 address string.
592
593       parse_ipv4strict_address(Address) ->
594                                   {ok, IPv4Address} | {error, einval}
595
596              Types:
597
598                 Address = string()
599                 IPv4Address = ip_address()
600
601              Parses an IPv4 address string containing four fields,  that  is,
602              not shortened, and returns an ip4_address().
603
604       parse_ipv6_address(Address) -> {ok, IPv6Address} | {error, einval}
605
606              Types:
607
608                 Address = string()
609                 IPv6Address = ip_address()
610
611              Parses  an  IPv6 address string and returns an ip6_address(). If
612              an IPv4 address string is specified, an IPv4-mapped IPv6 address
613              is returned.
614
615       parse_ipv6strict_address(Address) ->
616                                   {ok, IPv6Address} | {error, einval}
617
618              Types:
619
620                 Address = string()
621                 IPv6Address = ip_address()
622
623              Parses an IPv6 address string and returns an ip6_address(). Does
624              not accept IPv4 addresses.
625
626       ipv4_mapped_ipv6_address(X1 :: ip_address()) -> ip_address()
627
628              Convert an IPv4 address to an IPv4-mapped IPv6  address  or  the
629              reverse.  When converting from an IPv6 address all but the 2 low
630              words are ignored so this function  also  works  on  some  other
631              types of addresses than IPv4-mapped.
632
633       parse_strict_address(Address) -> {ok, IPAddress} | {error, einval}
634
635              Types:
636
637                 Address = string()
638                 IPAddress = ip_address()
639
640              Parses   an   IPv4   or  IPv6  address  string  and  returns  an
641              ip4_address() or ip6_address(). Does not accept a shortened IPv4
642              address string.
643
644       peername(Socket :: socket()) ->
645                   {ok,
646                    {ip_address(), port_number()} |
647                    returned_non_ip_address()} |
648                   {error, posix()}
649
650              Returns the address and port for the other end of a connection.
651
652              Notice  that for SCTP sockets, this function returns only one of
653              the peer addresses of the socket. Function peernames/1,2 returns
654              all.
655
656       peernames(Socket :: socket()) ->
657                    {ok,
658                     [{ip_address(), port_number()} |
659                      returned_non_ip_address()]} |
660                    {error, posix()}
661
662              Equivalent to peernames(Socket, 0).
663
664              Notice  that  the  behavior of this function for an SCTP one-to-
665              many style socket is not defined by the SCTP Sockets API  Exten‐
666              sions.
667
668       peernames(Socket, Assoc) ->
669                    {ok, [{Address, Port}]} | {error, posix()}
670
671              Types:
672
673                 Socket = socket()
674                 Assoc = #sctp_assoc_change{} | gen_sctp:assoc_id()
675                 Address = ip_address()
676                 Port = integer() >= 0
677
678              Returns  a  list  of all address/port number pairs for the other
679              end of an association Assoc of a socket.
680
681              This function can return multiple addresses for multihomed sock‐
682              ets,  such  as SCTP sockets. For other sockets it returns a one-
683              element list.
684
685              Notice that parameter Assoc is by the SCTP  Sockets  API  Exten‐
686              sions  defined  to be ignored for one-to-one style sockets. What
687              the special value 0 means, hence its  behavior  for  one-to-many
688              style sockets, is unfortunately undefined.
689
690       port(Socket) -> {ok, Port} | {error, any()}
691
692              Types:
693
694                 Socket = socket()
695                 Port = port_number()
696
697              Returns the local port number for a socket.
698
699       setopts(Socket, Options) -> ok | {error, posix()}
700
701              Types:
702
703                 Socket = socket()
704                 Options = [socket_setopt()]
705
706              Sets one or more options for a socket.
707
708              The following options are available:
709
710                {active, true | false | once | N}:
711                  If  the  value  is  true,  which  is the default, everything
712                  received from the socket is sent as messages to the  receiv‐
713                  ing process.
714
715                  If  the  value  is  false  (passive  mode), the process must
716                  explicitly    receive    incoming    data     by     calling
717                  gen_tcp:recv/2,3,   gen_udp:recv/2,3,  or  gen_sctp:recv/1,2
718                  (depending on the type of socket).
719
720                  If the value is once ({active, once}), one data message from
721                  the  socket is sent to the process. To receive one more mes‐
722                  sage, setopts/2 must be called again  with  option  {active,
723                  once}.
724
725                  If  the  value  is an integer N in the range -32768 to 32767
726                  (inclusive), the value is added to  the  socket's  count  of
727                  data  messages  sent  to the controlling process. A socket's
728                  default message count is 0. If a negative  value  is  speci‐
729                  fied,  and  its  magnitude  is  equal to or greater than the
730                  socket's current message count, the socket's  message  count
731                  is  set  to  0.  Once  the socket's message count reaches 0,
732                  either because of sending  received  data  messages  to  the
733                  process  or  by  being  explicitly  set, the process is then
734                  notified by a special  message,  specific  to  the  type  of
735                  socket,  that  the socket has entered passive mode. Once the
736                  socket  enters  passive  mode,  to  receive  more   messages
737                  setopts/2  must  be called again to set the socket back into
738                  an active mode.
739
740                  When using {active, once} or {active, N}, the socket changes
741                  behavior  automatically  when  data is received. This can be
742                  confusing in combination  with  connection-oriented  sockets
743                  (that  is, gen_tcp), as a socket with {active, false} behav‐
744                  ior reports closing differently than a socket with  {active,
745                  true}  behavior. To simplify programming, a socket where the
746                  peer closed, and this is detected while in  {active,  false}
747                  mode,  still  generates message {tcp_closed,Socket} when set
748                  to {active, once}, {active, true}, or {active, N}  mode.  It
749                  is     therefore     safe    to    assume    that    message
750                  {tcp_closed,Socket}, possibly followed by socket port termi‐
751                  nation   (depending   on  option  exit_on_close)  eventually
752                  appears  when  a  socket  changes  back  and  forth  between
753                  {active,  true} and {active, false} mode. However, when peer
754                  closing is detected it is all up to  the  underlying  TCP/IP
755                  stack and protocol.
756
757                  Notice  that {active, true} mode provides no flow control; a
758                  fast sender can easily overflow the receiver  with  incoming
759                  messages.  The  same is true for {active, N} mode, while the
760                  message count is greater than zero.
761
762                  Use active mode only if your  high-level  protocol  provides
763                  its  own  flow  control (for example, acknowledging received
764                  messages) or the amount of data exchanged is small. {active,
765                  false}  mode, use of the {active, once} mode, or {active, N}
766                  mode with values of N appropriate for the  application  pro‐
767                  vides  flow  control. The other side cannot send faster than
768                  the receiver can read.
769
770                {broadcast, Boolean} (UDP sockets):
771                  Enables/disables permission to send broadcasts.
772
773                {buffer, Size}:
774                  The size of the user-level buffer used by the driver. Not to
775                  be confused with options sndbuf and recbuf, which correspond
776                  to the Kernel socket buffers. For TCP it is  recommended  to
777                  have  val(buffer) >= val(recbuf) to avoid performance issues
778                  because of unnecessary copying. For UDP the same recommenda‐
779                  tion  applies, but the max should not be larger than the MTU
780                  of the network path. val(buffer) is automatically set to the
781                  above  maximum  when recbuf is set. However, as the size set
782                  for recbuf usually become larger, you are encouraged to  use
783                  getopts/2 to analyze the behavior of your operating system.
784
785                  Note  that  this is also the maximum amount of data that can
786                  be received from a single recv call. If you are using higher
787                  than normal MTU consider setting buffer higher.
788
789                {delay_send, Boolean}:
790                  Normally,  when  an  Erlang  process  sends to a socket, the
791                  driver tries to send the data immediately.  If  that  fails,
792                  the  driver uses any means available to queue up the message
793                  to be sent whenever the operating system says it can  handle
794                  it.  Setting {delay_send, true} makes all messages queue up.
795                  The messages sent to the network are then larger but  fewer.
796                  The  option  affects  the scheduling of send requests versus
797                  Erlang processes instead of changing any  real  property  of
798                  the  socket. The option is implementation-specific. Defaults
799                  to false.
800
801                {deliver, port | term}:
802                  When {active, true}, data is delivered on the  form  port  :
803                  {S, {data, [H1,..Hsz | Data]}} or term : {tcp, S, [H1..Hsz |
804                  Data]}.
805
806                {dontroute, Boolean}:
807                  Enables/disables routing bypass for outgoing messages.
808
809                {exit_on_close, Boolean}:
810                  This option is set to true by default.
811
812                  The only reason to set it to false is if you  want  to  con‐
813                  tinue  sending data to the socket after a close is detected,
814                  for example, if the peer  uses  gen_tcp:shutdown/2  to  shut
815                  down the write side.
816
817                {header, Size}:
818                  This  option  is only meaningful if option binary was speci‐
819                  fied when the socket was created. If option header is speci‐
820                  fied,  the first Size number bytes of data received from the
821                  socket are elements of a list, and the remaining data  is  a
822                  binary  specified as the tail of the same list. For example,
823                  if    Size    ==    2,    the    data    received    matches
824                  [Byte1,Byte2|Binary].
825
826                {high_msgq_watermark, Size}:
827                  The  socket  message  queue  is set to a busy state when the
828                  amount of data on the  message  queue  reaches  this  limit.
829                  Notice  that  this limit only concerns data that has not yet
830                  reached the ERTS internal socket implementation. Defaults to
831                  8 kB.
832
833                  Senders  of  data  to the socket are suspended if either the
834                  socket message queue is busy or the socket itself is busy.
835
836                  For  more  information,  see   options   low_msgq_watermark,
837                  high_watermark, and low_watermark.
838
839                  Notice   that   distribution  sockets  disable  the  use  of
840                  high_msgq_watermark and low_msgq_watermark. Instead use  the
841                  distribution buffer busy limit, which is a similar feature.
842
843                {high_watermark, Size} (TCP/IP sockets):
844                  The  socket  is  set to a busy state when the amount of data
845                  queued internally by the ERTS socket implementation  reaches
846                  this limit. Defaults to 8 kB.
847
848                  Senders  of  data  to the socket are suspended if either the
849                  socket message queue is busy or the socket itself is busy.
850
851                  For   more   information,   see    options    low_watermark,
852                  high_msgq_watermark, and low_msqg_watermark.
853
854                {ipv6_v6only, Boolean}:
855                  Restricts  the socket to use only IPv6, prohibiting any IPv4
856                  connections.  This  is  only  applicable  for  IPv6  sockets
857                  (option inet6).
858
859                  On  most  platforms  this  option  must be set on the socket
860                  before associating it to an address. It  is  therefore  only
861                  reasonable to specify it when creating the socket and not to
862                  use it when calling  function  (setopts/2)  containing  this
863                  description.
864
865                  The behavior of a socket with this option set to true is the
866                  only portable one. The original idea when IPv6  was  new  of
867                  using IPv6 for all traffic is now not recommended by FreeBSD
868                  (you can use {ipv6_v6only,false} to override the recommended
869                  system  default  value), forbidden by OpenBSD (the supported
870                  GENERIC kernel), and impossible on Windows (which has  sepa‐
871                  rate  IPv4  and  IPv6  protocol  stacks). Most Linux distros
872                  still have a system default  value  of  false.  This  policy
873                  shift  among  operating  systems  to separate IPv6 from IPv4
874                  traffic has evolved, as it gradually proved hard and compli‐
875                  cated to get a dual stack implementation correct and secure.
876
877                  On some platforms, the only allowed value for this option is
878                  true, for example, OpenBSD and Windows. Trying to  set  this
879                  option  to  false,  when  creating the socket, fails in this
880                  case.
881
882                  Setting this option on platforms where it does not exist  is
883                  ignored.  Getting  this  option  with  getopts/2  returns no
884                  value, that is,  the  returned  list  does  not  contain  an
885                  {ipv6_v6only,_}  tuple.  On  Windows,  the  option  does not
886                  exist, but it is emulated as a read-only option  with  value
887                  true.
888
889                  Therefore,  setting  this  option  to  true  when creating a
890                  socket never fails, except possibly on a platform where  you
891                  have customized the kernel to only allow false, which can be
892                  doable (but awkward) on, for example, OpenBSD.
893
894                  If you read back the option value using getopts/2 and get no
895                  value,  the option does not exist in the host operating sys‐
896                  tem. The behavior of both an IPv6 and an IPv4 socket listen‐
897                  ing  on  the  same port, and for an IPv6 socket getting IPv4
898                  traffic is then no longer predictable.
899
900                {keepalive, Boolean}(TCP/IP sockets):
901                  Enables/disables periodic transmission on a connected socket
902                  when  no  other data is exchanged. If the other end does not
903                  respond, the connection is considered broken  and  an  error
904                  message is sent to the controlling process. Defaults to dis‐
905                  abled.
906
907                {linger, {true|false, Seconds}}:
908                  Determines the time-out, in  seconds,  for  flushing  unsent
909                  data  in  the close/1 socket call. If the first component of
910                  the value tuple is false, the second is ignored. This  means
911                  that close/1 returns immediately, not waiting for data to be
912                  flushed. Otherwise, the second  component  is  the  flushing
913                  time-out, in seconds.
914
915                {low_msgq_watermark, Size}:
916                  If  the  socket message queue is in a busy state, the socket
917                  message queue is set in a not busy state when the amount  of
918                  data  queued  in  the  message queue falls below this limit.
919                  Notice that this limit only concerns data that has  not  yet
920                  reached the ERTS internal socket implementation. Defaults to
921                  4 kB.
922
923                  Senders that are suspended because of either a busy  message
924                  queue  or  a busy socket are resumed when the socket message
925                  queue and the socket are not busy.
926
927                  For  more  information,  see  options   high_msgq_watermark,
928                  high_watermark, and low_watermark.
929
930                  Notice   that   distribution  sockets  disable  the  use  of
931                  high_msgq_watermark and low_msgq_watermark. Instead they use
932                  the  distribution buffer busy limit, which is a similar fea‐
933                  ture.
934
935                {low_watermark, Size} (TCP/IP sockets):
936                  If the socket is in a busy state, the socket is set in a not
937                  busy  state when the amount of data queued internally by the
938                  ERTS socket implementation falls below this limit.  Defaults
939                  to 4 kB.
940
941                  Senders  that  are suspended because of a busy message queue
942                  or a busy socket are resumed when the socket  message  queue
943                  and the socket are not busy.
944
945                  For    more   information,   see   options   high_watermark,
946                  high_msgq_watermark, and low_msgq_watermark.
947
948                {mode, Mode :: binary | list}:
949                  Received Packet is delivered as defined by Mode.
950
951                {netns, Namespace :: file:filename_all()}:
952                  Sets a network namespace for the socket. Parameter Namespace
953                  is   a   filename   defining  the  namespace,  for  example,
954                  "/var/run/netns/example", typically created  by  command  ip
955                  netns  add  example.  This option must be used in a function
956                  call that creates a socket,  that  is,  gen_tcp:connect/3,4,
957                  gen_tcp:listen/2,  gen_udp:open/1,2  or gen_sctp:open/0,1,2,
958                  and also getifaddrs/1.
959
960                  This option uses the Linux-specific syscall setns(), such as
961                  in Linux kernel 3.0 or later, and therefore only exists when
962                  the runtime system is compiled for such an operating system.
963
964                  The virtual machine also needs elevated  privileges,  either
965                  running  as  superuser  or  (for  Linux)  having  capability
966                  CAP_SYS_ADMIN according to the documentation  for  setns(2).
967                  However,    during    testing    also   CAP_SYS_PTRACE   and
968                  CAP_DAC_READ_SEARCH have proven to be necessary.
969
970                  Example:
971
972                setcap cap_sys_admin,cap_sys_ptrace,cap_dac_read_search+epi beam.smp
973
974                  Notice that the filesystem containing  the  virtual  machine
975                  executable  (beam.smp in the example) must be local, mounted
976                  without flag nosetuid, support extended attributes, and  the
977                  kernel  must support file capabilities. All this runs out of
978                  the box on at least Ubuntu 12.04 LTS, except that SCTP sock‐
979                  ets appear to not support network namespaces.
980
981                  Namespace  is  a filename and is encoded and decoded as dis‐
982                  cussed in module file, with the following exceptions:
983
984                  * Emulator flag +fnu is ignored.
985
986                  * getopts/2 for this option returns a binary for  the  file‐
987                    name  if  the  stored  filename cannot be decoded. This is
988                    only to occur if you set the option using  a  binary  that
989                    cannot  be  decoded with the emulator's filename encoding:
990                    file:native_name_encoding/0.
991
992                {bind_to_device, Ifname :: binary()}:
993                  Binds a socket to a specific network interface. This  option
994                  must  be used in a function call that creates a socket, that
995                  is, gen_tcp:connect/3,4, gen_tcp:listen/2, gen_udp:open/1,2,
996                  or gen_sctp:open/0,1,2.
997
998                  Unlike  getifaddrs/0,  Ifname  is  encoded  a binary. In the
999                  unlikely case that a system is using non-7-bit-ASCII charac‐
1000                  ters  in  network device names, special care has to be taken
1001                  when encoding this argument.
1002
1003                  This option uses the Linux-specific socket  option  SO_BIND‐
1004                  TODEVICE,  such  as  in  Linux  kernel  2.0.30 or later, and
1005                  therefore only exists when the runtime  system  is  compiled
1006                  for such an operating system.
1007
1008                  Before Linux 3.8, this socket option could be set, but could
1009                  not retrieved with getopts/2. Since Linux 3.8, it  is  read‐
1010                  able.
1011
1012                  The  virtual  machine also needs elevated privileges, either
1013                  running  as  superuser  or  (for  Linux)  having  capability
1014                  CAP_NET_RAW.
1015
1016                  The primary use case for this option is to bind sockets into
1017                  Linux VRF instances.
1018
1019                list:
1020                  Received Packet is delivered as a list.
1021
1022                binary:
1023                  Received Packet is delivered as a binary.
1024
1025                {nodelay, Boolean}(TCP/IP sockets):
1026                  If Boolean == true, option TCP_NODELAY is turned on for  the
1027                  socket, which means that also small amounts of data are sent
1028                  immediately.
1029
1030                {nopush, Boolean}(TCP/IP sockets):
1031                  This translates to TCP_NOPUSH on  BSD  and  to  TCP_CORK  on
1032                  Linux.
1033
1034                  If  Boolean  ==  true, the corresponding option is turned on
1035                  for the socket, which means that small amounts of  data  are
1036                  accumulated  until  a full MSS-worth of data is available or
1037                  this option is turned off.
1038
1039                  Note that while TCP_NOPUSH socket  option  is  available  on
1040                  OSX,  its  semantics  is  very different (e.g., unsetting it
1041                  does not cause immediate send of accumulated  data).  Hence,
1042                  nopush option is intentionally ignored on OSX.
1043
1044                {packet, PacketType}(TCP/IP sockets):
1045                  Defines  the  type  of packets to use for a socket. Possible
1046                  values:
1047
1048                  raw | 0:
1049                    No packaging is done.
1050
1051                  1 | 2 | 4:
1052                    Packets consist of a header specifying the number of bytes
1053                    in  the  packet,  followed  by  that  number of bytes. The
1054                    header length can be one, two, or four bytes, and contain‐
1055                    ing  an  unsigned  integer  in big-endian byte order. Each
1056                    send operation generates the header,  and  the  header  is
1057                    stripped off on each receive operation.
1058
1059                    The 4-byte header is limited to 2Gb.
1060
1061                  asn1 | cdr | sunrm | fcgi | tpkt | line:
1062                    These  packet  types  only  have effect on receiving. When
1063                    sending a packet, it is the responsibility of the applica‐
1064                    tion  to  supply  a correct header. On receiving, however,
1065                    one message is sent to the controlling  process  for  each
1066                    complete  packet  received,  and,  similarly, each call to
1067                    gen_tcp:recv/2,3 returns one complete packet.  The  header
1068                    is not stripped off.
1069
1070                    The meanings of the packet types are as follows:
1071
1072                    * asn1 - ASN.1 BER
1073
1074                    * sunrm - Sun's RPC encoding
1075
1076                    * cdr - CORBA (GIOP 1.1)
1077
1078                    * fcgi - Fast CGI
1079
1080                    * tpkt - TPKT format [RFC1006]
1081
1082                    * line  -  Line  mode,  a packet is a line-terminated with
1083                      newline, lines longer than the receive buffer are  trun‐
1084                      cated
1085
1086                  http | http_bin:
1087                    The  Hypertext Transfer Protocol. The packets are returned
1088                    with the  format  according  to  HttpPacket  described  in
1089                    erlang:decode_packet/3  in  ERTS. A socket in passive mode
1090                    returns {ok, HttpPacket} from gen_tcp:recv while an active
1091                    socket sends messages like {http, Socket, HttpPacket}.
1092
1093                  httph | httph_bin:
1094                    These  two types are often not needed, as the socket auto‐
1095                    matically switches from http/http_bin  to  httph/httph_bin
1096                    internally  after  the  first line is read. However, there
1097                    can be occasions when they are  useful,  such  as  parsing
1098                    trailers from chunked encoding.
1099
1100                {packet_size, Integer}(TCP/IP sockets):
1101                  Sets  the  maximum allowed length of the packet body. If the
1102                  packet header indicates that the length  of  the  packet  is
1103                  longer  than  the maximum allowed length, the packet is con‐
1104                  sidered invalid. The same occurs if the packet header is too
1105                  large for the socket receive buffer.
1106
1107                  For    line-oriented   protocols   (line,   http*),   option
1108                  packet_size also guarantees that lines up to  the  indicated
1109                  length  are  accepted  and not considered invalid because of
1110                  internal buffer limitations.
1111
1112                {line_delimiter, Char}(TCP/IP sockets):
1113                  Sets the line delimiting character for line-oriented  proto‐
1114                  cols (line). Defaults to $\n.
1115
1116                {raw, Protocol, OptionNum, ValueBin}:
1117                  See below.
1118
1119                {read_packets, Integer}(UDP sockets):
1120                  Sets  the  maximum  number  of  UDP  packets to read without
1121                  intervention from the socket when data  is  available.  When
1122                  this many packets have been read and delivered to the desti‐
1123                  nation process, new packets are not read until a new notifi‐
1124                  cation of available data has arrived. Defaults to 5. If this
1125                  parameter is set too high, the system can  become  unrespon‐
1126                  sive because of UDP packet flooding.
1127
1128                {recbuf, Size}:
1129                  The  minimum  size  of  the  receive  buffer  to use for the
1130                  socket. You are encouraged to use getopts/2 to retrieve  the
1131                  size set by your operating system.
1132
1133                {recvtclass, Boolean}:
1134                  If set to true activates returning the received TCLASS value
1135                  on  platforms  that  implements  the  protocol  IPPROTO_IPV6
1136                  option   IPV6_RECVTCLASS   or  IPV6_2292RECVTCLASS  for  the
1137                  socket. The value is returned  as  a  {tclass,TCLASS}  tuple
1138                  regardless  of  if the platform returns an IPV6_TCLASS or an
1139                  IPV6_RECVTCLASS CMSG value.
1140
1141                  For packet oriented sockets that supports  receiving  ancil‐
1142                  lary  data with the payload data (gen_udp and gen_sctp), the
1143                  TCLASS value is returned in an extended  return  tuple  con‐
1144                  tained  in  an   ancillary  data   list. For stream oriented
1145                  sockets (gen_tcp) the only way to get the TCLASS value is if
1146                  the platform supports the pktoptions option.
1147
1148                {recvtos, Boolean}:
1149                  If set to true activates returning the received TOS value on
1150                  platforms that implements  the  protocol  IPPROTO_IP  option
1151                  IP_RECVTOS  for  the  socket.  The  value  is  returned as a
1152                  {tos,TOS} tuple regardless of if  the  platform  returns  an
1153                  IP_TOS or an IP_RECVTOS CMSG value.
1154
1155                  For  packet  oriented sockets that supports receiving ancil‐
1156                  lary data with the payload data (gen_udp and gen_sctp),  the
1157                  TOS  value is returned in an extended return tuple contained
1158                  in an  ancillary data  list.  For  stream  oriented  sockets
1159                  (gen_tcp)  the only way to get the TOS value is if the plat‐
1160                  form supports the pktoptions option.
1161
1162                {recvttl, Boolean}:
1163                  If set to true activates returning the received TTL value on
1164                  platforms  that  implements  the  protocol IPPROTO_IP option
1165                  IP_RECVTTL for the  socket.  The  value  is  returned  as  a
1166                  {ttl,TTL}  tuple  regardless  of  if the platform returns an
1167                  IP_TTL or an IP_RECVTTL CMSG value.
1168
1169                  For packet oriented sockets that supports  receiving  ancil‐
1170                  lary  data with the payload data (gen_udp and gen_sctp), the
1171                  TTL value is returned in an extended return tuple  contained
1172                  in  an   ancillary  data   list. For stream oriented sockets
1173                  (gen_tcp) the only way to get the TTL value is if the  plat‐
1174                  form supports the pktoptions option.
1175
1176                {reuseaddr, Boolean}:
1177                  Allows or disallows local reuse of port numbers. By default,
1178                  reuse is disallowed.
1179
1180                {send_timeout, Integer}:
1181                  Only allowed for connection-oriented sockets.
1182
1183                  Specifies a longest time to wait for a send operation to  be
1184                  accepted  by  the  underlying  TCP  stack. When the limit is
1185                  exceeded, the send operation  returns  {error,timeout}.  How
1186                  much  of  a  packet  that got sent is unknown; the socket is
1187                  therefore to be closed whenever a time-out has occurred (see
1188                  send_timeout_close below). Defaults to infinity.
1189
1190                {send_timeout_close, Boolean}:
1191                  Only allowed for connection-oriented sockets.
1192
1193                  Used  together  with  send_timeout  to  specify  whether the
1194                  socket is to be automatically closed when the send operation
1195                  returns  {error,timeout}.  The  recommended setting is true,
1196                  which automatically closes the  socket.  Defaults  to  false
1197                  because of backward compatibility.
1198
1199                {show_econnreset, Boolean}(TCP/IP sockets):
1200                  When  this  option is set to false, which is default, an RST
1201                  received from the TCP peer is treated as a normal close  (as
1202                  though  an  FIN  was  sent). A caller to gen_tcp:recv/2 gets
1203                  {error, closed}. In active  mode,  the  controlling  process
1204                  receives a {tcp_closed, Socket} message, indicating that the
1205                  peer has closed the connection.
1206
1207                  Setting this  option  to  true  allows  you  to  distinguish
1208                  between  a connection that was closed normally, and one that
1209                  was aborted (intentionally or unintentionally)  by  the  TCP
1210                  peer.  A call to gen_tcp:recv/2 returns {error, econnreset}.
1211                  In  active  mode,  the  controlling   process   receives   a
1212                  {tcp_error,  Socket,  econnreset}  message  before the usual
1213                  {tcp_closed, Socket}, as is the case for  any  other  socket
1214                  error. Calls to gen_tcp:send/2 also returns {error, econnre‐
1215                  set} when it is detected that a TCP peer has sent an RST.
1216
1217                  A connected socket returned from  gen_tcp:accept/1  inherits
1218                  the show_econnreset setting from the listening socket.
1219
1220                {sndbuf, Size}:
1221                  The  minimum  size of the send buffer to use for the socket.
1222                  You are encouraged to use getopts/2, to  retrieve  the  size
1223                  set by your operating system.
1224
1225                {priority, Integer}:
1226                  Sets  the SO_PRIORITY socket level option on platforms where
1227                  this is implemented. The behavior and allowed  range  varies
1228                  between  different  systems.  The option is ignored on plat‐
1229                  forms where it is not implemented. Use with caution.
1230
1231                {tos, Integer}:
1232                  Sets IP_TOS IP level options  on  platforms  where  this  is
1233                  implemented.  The  behavior and allowed range varies between
1234                  different systems. The option is ignored on platforms  where
1235                  it is not implemented. Use with caution.
1236
1237                {tclass, Integer}:
1238                  Sets IPV6_TCLASS IP level options on platforms where this is
1239                  implemented. The behavior and allowed range  varies  between
1240                  different  systems. The option is ignored on platforms where
1241                  it is not implemented. Use with caution.
1242
1243              In addition to these options, raw option specifications  can  be
1244              used.  The  raw  options are specified as a tuple of arity four,
1245              beginning with tag raw, followed  by  the  protocol  level,  the
1246              option  number, and the option value specified as a binary. This
1247              corresponds to the second, third, and fourth  arguments  to  the
1248              setsockopt  call  in  the C socket API. The option value must be
1249              coded in the native endianess of the platform and, if  a  struc‐
1250              ture  is  required,  must follow the structure alignment conven‐
1251              tions on the specific platform.
1252
1253              Using raw socket options requires detailed knowledge  about  the
1254              current operating system and TCP stack.
1255
1256              Example:
1257
1258              This  example  concerns the use of raw options. Consider a Linux
1259              system where you want to  set  option  TCP_LINGER2  on  protocol
1260              level IPPROTO_TCP in the stack. You know that on this particular
1261              system it defaults to 60 (seconds), but you want to lower it  to
1262              30 for a particular socket. Option TCP_LINGER2 is not explicitly
1263              supported by inet, but you know that the protocol  level  trans‐
1264              lates  to number 6, the option number to number 8, and the value
1265              is to be specified as a 32-bit integer. You can  use  this  code
1266              line to set the option for the socket named Sock:
1267
1268              inet:setopts(Sock,[{raw,6,8,<<30:32/native>>}]),
1269
1270              As  many options are silently discarded by the stack if they are
1271              specified out of range; it can be a good idea to  check  that  a
1272              raw  option  is accepted. The following code places the value in
1273              variable TcpLinger2:
1274
1275              {ok,[{raw,6,8,<<TcpLinger2:32/native>>}]}=inet:getopts(Sock,[{raw,6,8,4}]),
1276
1277              Code such as these examples  is  inherently  non-portable,  even
1278              different  versions  of  the  same  OS  on the same platform can
1279              respond differently to this kind  of  option  manipulation.  Use
1280              with care.
1281
1282              Notice  that  the  default  options  for  TCP/IP  sockets can be
1283              changed with the Kernel configuration  parameters  mentioned  in
1284              the beginning of this manual page.
1285
1286       sockname(Socket :: socket()) ->
1287                   {ok,
1288                    {ip_address(), port_number()} |
1289                    returned_non_ip_address()} |
1290                   {error, posix()}
1291
1292              Returns the local address and port number for a socket.
1293
1294              Notice  that  for SCTP sockets this function returns only one of
1295              the socket addresses. Function socknames/1,2 returns all.
1296
1297       socknames(Socket :: socket()) ->
1298                    {ok,
1299                     [{ip_address(), port_number()} |
1300                      returned_non_ip_address()]} |
1301                    {error, posix()}
1302
1303              Equivalent to socknames(Socket, 0).
1304
1305       socknames(Socket, Assoc) ->
1306                    {ok, [{Address, Port}]} | {error, posix()}
1307
1308              Types:
1309
1310                 Socket = socket()
1311                 Assoc = #sctp_assoc_change{} | gen_sctp:assoc_id()
1312                 Address = ip_address()
1313                 Port = integer() >= 0
1314
1315              Returns a list of all local  address/port  number  pairs  for  a
1316              socket for the specified association Assoc.
1317
1318              This function can return multiple addresses for multihomed sock‐
1319              ets, such as SCTP sockets. For other sockets it returns  a  one-
1320              element list.
1321
1322              Notice  that  parameter  Assoc is by the SCTP Sockets API Exten‐
1323              sions defined to be ignored for one-to-one  style  sockets.  For
1324              one-to-many  style  sockets,  the  special value 0 is defined to
1325              mean that the returned addresses must be without any  particular
1326              association.  How  different SCTP implementations interpret this
1327              varies somewhat.
1328

POSIX ERROR CODES

1330         * e2big - Too long argument list
1331
1332         * eacces - Permission denied
1333
1334         * eaddrinuse - Address already in use
1335
1336         * eaddrnotavail - Cannot assign requested address
1337
1338         * eadv - Advertise error
1339
1340         * eafnosupport - Address family not supported by protocol family
1341
1342         * eagain - Resource temporarily unavailable
1343
1344         * ealign - EALIGN
1345
1346         * ealready - Operation already in progress
1347
1348         * ebade - Bad exchange descriptor
1349
1350         * ebadf - Bad file number
1351
1352         * ebadfd - File descriptor in bad state
1353
1354         * ebadmsg - Not a data message
1355
1356         * ebadr - Bad request descriptor
1357
1358         * ebadrpc - Bad RPC structure
1359
1360         * ebadrqc - Bad request code
1361
1362         * ebadslt - Invalid slot
1363
1364         * ebfont - Bad font file format
1365
1366         * ebusy - File busy
1367
1368         * echild - No children
1369
1370         * echrng - Channel number out of range
1371
1372         * ecomm - Communication error on send
1373
1374         * econnaborted - Software caused connection abort
1375
1376         * econnrefused - Connection refused
1377
1378         * econnreset - Connection reset by peer
1379
1380         * edeadlk - Resource deadlock avoided
1381
1382         * edeadlock - Resource deadlock avoided
1383
1384         * edestaddrreq - Destination address required
1385
1386         * edirty - Mounting a dirty fs without force
1387
1388         * edom - Math argument out of range
1389
1390         * edotdot - Cross mount point
1391
1392         * edquot - Disk quota exceeded
1393
1394         * eduppkg - Duplicate package name
1395
1396         * eexist - File already exists
1397
1398         * efault - Bad address in system call argument
1399
1400         * efbig - File too large
1401
1402         * ehostdown - Host is down
1403
1404         * ehostunreach - Host is unreachable
1405
1406         * eidrm - Identifier removed
1407
1408         * einit - Initialization error
1409
1410         * einprogress - Operation now in progress
1411
1412         * eintr - Interrupted system call
1413
1414         * einval - Invalid argument
1415
1416         * eio - I/O error
1417
1418         * eisconn - Socket is already connected
1419
1420         * eisdir - Illegal operation on a directory
1421
1422         * eisnam - Is a named file
1423
1424         * el2hlt - Level 2 halted
1425
1426         * el2nsync - Level 2 not synchronized
1427
1428         * el3hlt - Level 3 halted
1429
1430         * el3rst - Level 3 reset
1431
1432         * elbin - ELBIN
1433
1434         * elibacc - Cannot access a needed shared library
1435
1436         * elibbad - Accessing a corrupted shared library
1437
1438         * elibexec - Cannot exec a shared library directly
1439
1440         * elibmax - Attempting to link in more shared libraries  than  system
1441           limit
1442
1443         * elibscn - .lib section in a.out corrupted
1444
1445         * elnrng - Link number out of range
1446
1447         * eloop - Too many levels of symbolic links
1448
1449         * emfile - Too many open files
1450
1451         * emlink - Too many links
1452
1453         * emsgsize - Message too long
1454
1455         * emultihop - Multihop attempted
1456
1457         * enametoolong - Filename too long
1458
1459         * enavail - Unavailable
1460
1461         * enet - ENET
1462
1463         * enetdown - Network is down
1464
1465         * enetreset - Network dropped connection on reset
1466
1467         * enetunreach - Network is unreachable
1468
1469         * enfile - File table overflow
1470
1471         * enoano - Anode table overflow
1472
1473         * enobufs - No buffer space available
1474
1475         * enocsi - No CSI structure available
1476
1477         * enodata - No data available
1478
1479         * enodev - No such device
1480
1481         * enoent - No such file or directory
1482
1483         * enoexec - Exec format error
1484
1485         * enolck - No locks available
1486
1487         * enolink - Link has been severed
1488
1489         * enomem - Not enough memory
1490
1491         * enomsg - No message of desired type
1492
1493         * enonet - Machine is not on the network
1494
1495         * enopkg - Package not installed
1496
1497         * enoprotoopt - Bad protocol option
1498
1499         * enospc - No space left on device
1500
1501         * enosr - Out of stream resources or not a stream device
1502
1503         * enosym - Unresolved symbol name
1504
1505         * enosys - Function not implemented
1506
1507         * enotblk - Block device required
1508
1509         * enotconn - Socket is not connected
1510
1511         * enotdir - Not a directory
1512
1513         * enotempty - Directory not empty
1514
1515         * enotnam - Not a named file
1516
1517         * enotsock - Socket operation on non-socket
1518
1519         * enotsup - Operation not supported
1520
1521         * enotty - Inappropriate device for ioctl
1522
1523         * enotuniq - Name not unique on network
1524
1525         * enxio - No such device or address
1526
1527         * eopnotsupp - Operation not supported on socket
1528
1529         * eperm - Not owner
1530
1531         * epfnosupport - Protocol family not supported
1532
1533         * epipe - Broken pipe
1534
1535         * eproclim - Too many processes
1536
1537         * eprocunavail - Bad procedure for program
1538
1539         * eprogmismatch - Wrong program version
1540
1541         * eprogunavail - RPC program unavailable
1542
1543         * eproto - Protocol error
1544
1545         * eprotonosupport - Protocol not supported
1546
1547         * eprototype - Wrong protocol type for socket
1548
1549         * erange - Math result unrepresentable
1550
1551         * erefused - EREFUSED
1552
1553         * eremchg - Remote address changed
1554
1555         * eremdev - Remote device
1556
1557         * eremote - Pathname hit remote filesystem
1558
1559         * eremoteio - Remote I/O error
1560
1561         * eremoterelease - EREMOTERELEASE
1562
1563         * erofs - Read-only filesystem
1564
1565         * erpcmismatch - Wrong RPC version
1566
1567         * erremote - Object is remote
1568
1569         * eshutdown - Cannot send after socket shutdown
1570
1571         * esocktnosupport - Socket type not supported
1572
1573         * espipe - Invalid seek
1574
1575         * esrch - No such process
1576
1577         * esrmnt - Srmount error
1578
1579         * estale - Stale remote file handle
1580
1581         * esuccess - Error 0
1582
1583         * etime - Timer expired
1584
1585         * etimedout - Connection timed out
1586
1587         * etoomanyrefs - Too many references
1588
1589         * etxtbsy - Text file or pseudo-device busy
1590
1591         * euclean - Structure needs cleaning
1592
1593         * eunatch - Protocol driver not attached
1594
1595         * eusers - Too many users
1596
1597         * eversion - Version mismatch
1598
1599         * ewouldblock - Operation would block
1600
1601         * exdev - Cross-domain link
1602
1603         * exfull - Message tables full
1604
1605         * nxdomain - Hostname or domain name cannot be found
1606
1607Ericsson AB                     kernel 6.3.1.1                         inet(3)
Impressum