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

EXPORTS

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

POSIX ERROR CODES

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