A RetroSearch Logo

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Search Query:

Showing content from http://www.erlang.org/doc/apps/kernel/inet below:

inet — kernel v10.3.1

Access to Network protocols.

This module, together with gen_tcp, gen_udp and gen_sctp provides access to the Network protocols TCP, SCTP and UDP over IP, as well as stream and datagram protocols over the local (unix) address domain / protocol domain.

See also ERTS User's Guide: Inet Configuration or more information about how to configure an Erlang runtime system for IP communication.

The following four Kernel configuration parameters affect the behavior of all gen_tcp, gen_udp and gen_sctp sockets opened on an Erlang node:

For the gen_tcp:accept/1,2 call, the values of the listening socket options are inherited. Therefore there is no corresponding application variable for accept.

Using the Kernel configuration parameters above, one can set default options for all TCP sockets on a node, but use this with care. Options such as {delay_send,true} can be specified in this way. The following is an example of starting an Erlang node with all sockets using delayed send:

$ erl -sname test -kernel \
inet_default_connect_options '[{delay_send,true}]' \
inet_default_listen_options '[{delay_send,true}]'

Please note that the default option {active, true} cannot be changed, for internal implementation reasons.

Addresses as inputs to functions can be either a string or a tuple. For example, the IP address 150.236.20.73 can be passed to gethostbyaddr/1, either as a string "150.236.20.73" or as a tuple {150, 236, 20, 73}.

IPv4 address examples:

Address          ip_address()
-------          ------------
127.0.0.1        {127,0,0,1}
192.168.42.2     {192,168,42,2}

IPv6 address examples:

Address          ip_address()
-------          ------------
::1             {0,0,0,0,0,0,0,1}
::192.168.42.2  {0,0,0,0,0,0,(192 bsl 8) bor 168,(42 bsl 8) bor 2}
::FFFF:192.168.42.2
                {0,0,0,0,0,16#FFFF,(192 bsl 8) bor 168,(42 bsl 8) bor 2}
3ffe:b80:1f8d:2:204:acff:fe17:bf38
                {16#3ffe,16#b80,16#1f8d,16#2,16#204,16#acff,16#fe17,16#bf38}
fe80::204:acff:fe17:bf38
                {16#fe80,0,0,0,16#204,16#acff,16#fe17,16#bf38}

Function parse_address/1 can be useful:

1> inet:parse_address("192.168.42.2").
{ok,{192,168,42,2}}
2> inet:parse_address("::FFFF:192.168.42.2").
{ok,{0,0,0,0,0,65535,49320,10754}}
POSIX Error Codes Summary Types: Exported data types

Ancillary data / control messages.

A general network address.

A record describing a host; name and address.

Implementation backend selector for socket/0.

A network address for the local family (AF_LOCAL | AF_UNIX)

a non-IP network address.

A socket recognized by this module and its siblings.

Types: Internal data types

Interface address description list.

A network address for the inet6 family (AF_INET6, IPv6)

A network address for the inet family (AF_INET, IPv4)

Types

Options for selecting statistics items.

Functions

Close a socket of any type.

Get the inet configuration.

Resolve a host to an address, in a specific addresss family.

Resolve a host to a list of addresses, in a specific address family.

Resolve (reverse) an address to a #hostent{} record.

Resolve a hostname to a #hostent{} record, in a specific address family.

Get interface names and addresses.

Get interface names and addresses, in a specific namespace.

Get one or more options for a socket.

Get one or more statistics options for a socket.

Equivalent to i/1 for the protocols tcp, udp, and sctp

Get information about a socket.

Convert between an IPv4 address and an IPv4-mapped IPv6 address.

Test for an IPv4 address.

Test for an IPv6 address.

Return the address of the socket's remote end.

Return the addresses of all remote ends of a socket.

Return the local port number for a socket.

Set one or more options for a socket.

Return the local address and port number for a socket.

Return all localaddresses for a socket.

Types: Exported data types 
-type address_family() :: inet | inet6 | local.
-type ancillary_data() :: [{tos, byte()} | {tclass, byte()} | {ttl, byte()}].

Ancillary data / control messages.

Ancillary data received with a data packet, read with the socket option pktoptions from a TCP socket, or to set in a call to gen_udp:send/4 or gen_udp:send/5.

The value(s) correspond to the currently active socket options recvtos, recvtclass and recvttl, or for a single send operation the option(s) to override the currently active socket option(s).

A general network address.

A general network address format of the form {Family, Destination} where Family is an atom such as local and the format of Destination depends on Family. Destination is a complete address (for example an IP address with port number).

A record describing a host; name and address.

Corresponds to the C: struct hostent as returned by for example gethostbyname(3).

The record is defined in the Kernel include file "inet.hrl".

Add the following directive to the module:

-include_lib("kernel/include/inet.hrl").
-type inet_backend() :: {inet_backend, inet | socket}.

Implementation backend selector for socket/0.

Selects the implementation backend for sockets. The current default is inet which uses inet_drv.c to call the platform's socket API. The value socket instead uses the socket module and its NIF implementation.

This is a temporary option that will be ignored in a future release.

-type ip4_address() :: {0..255, 0..255, 0..255, 0..255}.
-type ip6_address() :: {0..65535, 0..65535, 0..65535, 0..65535, 0..65535, 0..65535, 0..65535, 0..65535}.
-type local_address() :: {local, File :: binary() | string()}.

A network address for the local family (AF_LOCAL | AF_UNIX)

This address family, also known as "Unix domain sockets" only works on Unix-like systems.

File is normally a file pathname in a local filesystem. It is limited in length by the operating system, traditionally to 108 bytes.

A binary/0 is passed as is to the operating system, but a string/0 is encoded according to the system filename encoding mode.

Other addresses are possible, for example Linux implements "Abstract Addresses". See the documentation for Unix Domain Sockets on your system, normally unix in manual section 7.

In most API functions where you can use this address family the port number must be 0.

-type port_number() :: 0..65535.
-type posix() ::
          eaddrinuse | eaddrnotavail | eafnosupport | ealready | econnaborted | econnrefused |
          econnreset | edestaddrreq | ehostdown | ehostunreach | einprogress | eisconn | emsgsize |
          enetdown | enetunreach | enopkg | enoprotoopt | enotconn | enotty | enotsock | eproto |
          eprotonosupport | eprototype | esocktnosupport | etimedout | ewouldblock | exbadport |
          exbadseq |
          file:posix().

POSIX Error Code atom/0.

An atom that is named from the POSIX error codes used in Unix, and in the runtime libraries of most C compilers. See section POSIX Error Codes.

-type returned_non_ip_address() :: {local, binary()} | {unspec, <<>>} | {undefined, any()}.

a non-IP network address.

Addresses besides ip_address/0 ones that are returned from socket API functions. See in particular local_address/0. The unspec family corresponds to AF_UNSPEC and can occur if the other side has no socket address. The undefined family can only occur in the unlikely event of an address family that the VM doesn't recognize.

A socket recognized by this module and its siblings.

See gen_tcp:socket/0 and gen_udp:socket/0.

-type socket_protocol() :: tcp | udp | sctp.
-type stat_option() ::
          recv_cnt | recv_max | recv_avg | recv_oct | recv_dvi | send_cnt | send_max | send_avg |
          send_oct | send_pend.
Types: Internal data types 
-type getifaddrs_ifopts() ::
          [Ifopt ::
               {flags, Flags :: [up | broadcast | loopback | pointtopoint | running | multicast]} |
               {addr, Addr :: ip_address()} |
               {netmask, Netmask :: ip_address()} |
               {broadaddr, Broadaddr :: ip_address()} |
               {dstaddr, Dstaddr :: ip_address()} |
               {hwaddr, Hwaddr :: [byte()]}].

Interface address description list.

A list returned from getifaddrs/0,1 for a named interface, translated from the returned data of the POSIX API function getaddrinfo().

Hwaddr is hardware dependent, for example, on Ethernet interfaces it is the 6-byte Ethernet address (MAC address (EUI-48 address)).

The tuples {addr,Addr}, {netmask,Netmask}, and possibly {broadaddr,Broadaddr} or {dstaddr,Dstaddr} are repeated in the list if the interface has got multiple addresses. An interface may have multiple {flag,_} tuples for example if it has different flags for different address families.

Multiple {hwaddr,Hwaddr} tuples is hard to say anything definite about, though. The tuple {flag,Flags} is mandatory, all others are optional.

Do not rely too much on the order of Flags atoms or the Ifopt tuples. There are however some rules:

The tuple {hwaddr,_} is not returned on Solaris, as the hardware address historically belongs to the link layer and it is not returned by the Solaris API function getaddrinfo().

Warning

On Windows, the data is fetched from different OS API functions, so the Netmask and Broadaddr values may be calculated, just as some Flags values.

A network address for the inet6 family (AF_INET6, IPv6)

Warning

This address format is currently experimental and for completeness to make all address families have a {Family, Destination} representation.

A network address for the inet family (AF_INET, IPv4)

Warning

This address format is currently experimental and for completeness to make all address families have a {Family, Destination} representation.

Types 
-type ether_address() :: [0..255].
-type i_option() ::
          port | module | recv | sent | owner | local_address |
          {local_address, ShowPorts :: boolean()} |
          foreign_address |
          {foreign_address, ShowPorts :: boolean()} |
          state | type.

Options for selecting statistics items.

Regarding ShowPorts, see show_ports as described in the i/2 function, defaults to false.

-type module_socket() :: {'$inet', Handler :: module(), Handle :: term()}.
Functions

Cancel a socket monitor.

If MRef is a reference that the calling process obtained by calling monitor/1, this monitor is removed. If the monitoring is already removed, nothing happens.

The returned value is one of the following:

-spec close(Socket) -> ok when Socket :: socket().

Close a socket of any type.

-spec format_error(Reason) -> string() when Reason :: posix() | system_limit.

Format an error code into a string/0.

Returns a diagnostic error string. For possible POSIX values and corresponding strings, see section POSIX Error Codes.

-spec get_rc() -> [{Par :: atom(), Val :: any()} | {Par :: atom(), Val1 :: any(), Val2 :: any()}].

Get the inet configuration.

Returns the state of the inet configuration database in form of a list of recorded configuration parameters. For more information, see ERTS User's Guide: Inet Configuration.

Only actual parameters with other than default values are returned, for example not directives that specify other sources for configuration parameters nor directives that clear parameters.

Resolve a host to an address, in a specific addresss family.

Returns the IP address for Host as a tuple of integers. Host can be an IP address, a single hostname/0, or a fully qualified hostname/0.

Resolve a host to a list of addresses, in a specific address family.

Returns a list of all IP addresses for Host. Host can be an IP address, a single hostname/0, or a fully qualified hostname/0.

Resolve (reverse) an address to a #hostent{} record.

Returns a #hostent{} record for the host with the specified address.

-spec gethostbyname(Hostname) -> {ok, Hostent} | {error, posix()}
                       when Hostname :: hostname(), Hostent :: hostent().

Resolve a hostname to a #hostent{} record.

Returns a #hostent{} record for the host with the specified Hostname.

This function uses the resolver, which is often the native (OS) resolver.

If resolver option inet6 is true, an IPv6 address is looked up.

See ERTS User's Guide: Inet Configuration for information about the resolver configuration.

A quirk of many resolvers is that an integer string is interpreted as an IP address. For instance, the integer string "3232235521" and the string "192.168.0.1" are both translated to the IP address {192,168,0,1}.

Resolve a hostname to a #hostent{} record, in a specific address family.

Returns a #hostent{} record for the host with the specified Hostname, restricted to the specified address Family.

See also gethostbyname/1.

-spec gethostname() -> {ok, Hostname} when Hostname :: string().

Get the local hostname.

Returns the local hostname. Never fails.

Get interface names and addresses.

Returns a list of 2-tuples containing interface names and the interfaces' addresses. Ifname is a Unicode string and Ifopts is a list of interface address description tuples.

The interface address description tuples are documented under the type of the Ifopts value.

Get interface names and addresses, in a specific namespace.

Equivalent to getifaddrs/0, but accepts an Option {netns, Namespace} that, on platforms that support the feature (Linux), sets a network namespace for the OS call. Also, If the option 'inet_backend' is first in the options list, the specified backend will be used (for 'inet', inet and for 'socket' the equivalent net functions will be used).

See the socket option {netns, Namespace} under setopts/2.

Get one or more options for a socket.

Gets all options in the list Options from Socket. See setopts/2 for a list of available options. See also the descriptions of protocol specific types referenced by socket_optval() .

The number of elements in the returned OptionValues list does not necessarily correspond to the number of options asked for. If the operating system fails to support an option, it is left out in the returned list. An error tuple is returned only when getting options for the socket is impossible (that is, the socket is closed or the buffer size in a raw request is too large). This behavior is kept for backward compatibility reasons.

A raw option request RawOptReq = {raw, Protocol, OptionNum, ValueSpec} can be used to get information about socket options not (explicitly) supported by the emulator. The use of raw socket options makes the code non-portable, but allows the Erlang programmer to take advantage of unusual features present on a particular platform.

RawOptReq consists of tag raw followed by the protocol level, the option number, and either a binary or the size, in bytes, of the buffer in which the option value is to be stored. A binary is to be used when the underlying getsockopt requires input in the argument field. In this case, the binary size shall correspond to the required buffer size of the return value. The supplied values in a RawOptReq correspond to the second, third, and fourth/fifth parameters to the getsockopt call in the C socket API. The value stored in the buffer is returned as a binary ValueBin, where all values are coded in native endianness.

Asking for and inspecting raw socket options require low-level information about the current operating system and TCP stack.

Example:

Consider a Linux machine where option TCP_INFO can be used to collect TCP statistics for a socket. Assume you are interested in field tcpi_sacked of struct tcp_info filled in when asking for TCP_INFO. To be able to access this information, you need to know the following:

By inspecting the headers or writing a small C program, it is found that IPPROTO_TCP is 6, TCP_INFO is 11, the structure size is 92 (bytes), the offset of tcpi_sacked is 28 bytes, and the value is a 32-bit integer. The following code can be used to retrieve the value:

get_tcpi_sacked(Sock) ->
    {ok,[{raw,_,_,Info}]} = inet:getopts(Sock,[{raw,6,11,92}]),
    <<_:28/binary,TcpiSacked:32/native,_/binary>> = Info,
    TcpiSacked.

Preferably, you would check the machine type, the operating system, and the Kernel version before executing anything similar to this code.

Equivalent to getstat/2.

Get one or more statistics options for a socket.

getstat(Socket) is equivalent to getstat(Socket, [recv_avg, recv_cnt, recv_dvi, recv_max, recv_oct, send_avg, send_cnt, send_pend, send_max, send_oct]).

The following options are available:

Equivalent to i/1 for the protocols tcp, udp, and sctp

List network sockets.

With argument Proto equivalent to i(Proto, Options) where Options is a list of all atom/0s in i_option/0.

With argument Options, equivalent to `i(Proto, Options) for Proto: tcp, udp, and sctp. With argument show_ports (since OTP 27.0) equivalent to `i(Proto, Options) where Option is a list of all options in i_option/0 with ShowPorts = true.

List network sockets.

Lists all TCP, UDP and SCTP sockets on the terminal, those created by the Erlang runtime system as well as by the application.

The following options are available:

The Options argument may also be (since OTP 27.0):

-spec info(Socket) -> Info when Socket :: socket(), Info :: term().

Get information about a socket.

Returns a term containing miscellaneous information about a socket.

Convert between an IPv4 address and an IPv4-mapped IPv6 address.

Convert an IPv4 address to an IPv4-mapped IPv6 address or the reverse. When converting from an IPv6 address all but the 2 low words are ignored so this function also works on some other types of IPv6 addresses than IPv4-mapped.

Test for an IP address.

Tests if the argument IPAddress is an ip_address/0 and if so returns true, otherwise false.

Test for an IPv4 address.

Tests if the argument IPv4Address is an ip4_address/0 and if so returns true, otherwise false.

Test for an IPv6 address.

Tests if the argument IPv6Address is an ip6_address/0 and if so returns true, otherwise false.

Start a socket monitor.

If the Socket to monitor doesn't exist or when the monitor is triggered, a 'DOWN' message is sent that has the following pattern:

	    {'DOWN', MonitorRef, Type, Object, Info}

Making several calls to inet:monitor/1 for the same Socket is not an error; one monitor is created per call.

The monitor is triggered when the socket is closed in any way such as an API call, remote end close, closed by signal when owner exits, ...

-spec ntoa(IpAddress) -> Address | {error, einval} when Address :: string(), IpAddress :: ip_address().

Parse an ip_address/0 to an IPv4 or IPv6 address string.

-spec parse_address(Address) -> {ok, IPAddress} | {error, einval}
                       when Address :: string(), IPAddress :: ip_address().

Parse an IP address string to an ip_address/0.

Returns an ip4_address/0 or an ip6_address/0 depending on which parsing that succeeds.

Accepts a short form IPv4 address string like parse_ipv4_address/1.

-spec parse_ipv4_address(Address) -> {ok, IPv4Address} | {error, einval}
                            when Address :: string(), IPv4Address :: ip4_address().

Parse (relaxed) an IPv4 address string to an ip4_address/0.

Accepts a short form IPv4 address string (less than 4 fields) such as "127.1" or "0x7f000001".

-spec parse_ipv4strict_address(Address) -> {ok, IPv4Address} | {error, einval}
                                  when Address :: string(), IPv4Address :: ip4_address().

Parse an IPv4 address string to an ip4_address/0.

Requires an IPv4 address string containing four fields, that is; not a short form address string.

-spec parse_ipv6_address(Address) -> {ok, IPv6Address} | {error, einval}
                            when Address :: string(), IPv6Address :: ip6_address().

Parse (relaxed) an IPv6 address string to an ip6_address/0.

Also accepts a (relaxed) IPv4 address string like parse_ipv4_address/1 and returns an IPv4-mapped IPv6 address.

-spec parse_ipv6strict_address(Address) -> {ok, IPv6Address} | {error, einval}
                                  when Address :: string(), IPv6Address :: ip6_address().

Parse an IPv6 address string to an ip6_address/0.

Doesn't accept an IPv4 address string. An IPv6 address string, though, allows an IPv4 tail like this: "::127.0.0.1" (which is the same as "::7f00:0001").

-spec parse_strict_address(Address) -> {ok, IPAddress} | {error, einval}
                              when Address :: string(), IPAddress :: ip_address().

Parse an IP address string to an ip_address/0.

Like parse_address/1 but doesn't accept a short form IPv4 address string.

Return the address of the socket's remote end.

Returns the address and port for the other end of a connection.

Notice that for SCTP sockets, this function returns only one of the peer addresses of the socket. Function peernames/1,2 returns all.

Equivalent to peernames(Socket, 0).

Notice that the behavior of this function for an SCTP one-to-many style socket is not defined by the SCTP Sockets API Extensions.

-spec peernames(Socket, Assoc) -> {ok, [{Address, Port}]} | {error, posix()}
                   when
                       Socket :: socket(),
                       Assoc ::
                           #sctp_assoc_change{state :: term(),
                                              error :: term(),
                                              outbound_streams :: term(),
                                              inbound_streams :: term(),
                                              assoc_id :: term()} |
                           gen_sctp:assoc_id(),
                       Address :: ip_address(),
                       Port :: non_neg_integer().

Return the addresses of all remote ends of a socket.

Returns a list of all address/port number pairs for the remote end of an association Assoc of a socket.

This function can return multiple addresses for multihomed sockets, such as SCTP sockets. For other sockets it returns a one-element list.

Notice that parameter Assoc is by the SCTP Sockets API Extensions defined to be ignored for one-to-one style sockets. What the special value 0 means, is unfortunately undefined, and hence the behavior for one-to-many style sockets.

Return the local port number for a socket.

Set one or more options for a socket.

Sets the list of Options on Socket.

The following options are available:

In addition to these options, raw option specifications can be used. The raw options are specified as a tuple of arity four, beginning with tag raw, followed by the protocol level, the option number, and the option value specified as a binary. This corresponds to the second, third, and fourth arguments to the setsockopt call in the C socket API. The option value must be coded in the native endianness of the platform and, if a structure is required, must follow the structure alignment conventions on the specific platform.

Using raw socket options requires detailed knowledge about the current operating system and TCP stack.

Example:

This example concerns the use of raw options. Consider a Linux system where you want to set option TCP_LINGER2 on protocol level IPPROTO_TCP in the stack. You know that on this particular system it defaults to 60 (seconds), but you want to lower it to 30 for a particular socket. Option TCP_LINGER2 is not explicitly supported by inet, but you know that the protocol level translates to number 6, the option number to number 8, and the value is to be specified as a 32-bit integer. You can use this code line to set the option for the socket named Sock:

inet:setopts(Sock, [{raw,6,8,<<30:32/native>>}]),

As many options are silently discarded by the stack if they are specified out of range; it can be a good idea to check that a raw option is accepted. The following code places the value in variable TcpLinger2:

{ok,[{raw,6,8,<<TcpLinger2:32/native>>}]}=inet:getopts(Sock,[{raw,6,8,4}]),

Code such as these examples is inherently non-portable, even different versions of the same OS on the same platform can respond differently to this kind of option manipulation. Use with care.

Notice that the default options for TCP/IP sockets can be changed with the Kernel configuration parameters mentioned in the beginning of this manual page.

Return the local address and port number for a socket.

Notice that for SCTP sockets this function returns only one of the socket addresses. Function socknames/1,2 returns all.

Equivalent to socknames(Socket, 0).

-spec socknames(Socket, Assoc) -> {ok, [{Address, Port}]} | {error, posix()}
                   when
                       Socket :: socket(),
                       Assoc ::
                           #sctp_assoc_change{state :: term(),
                                              error :: term(),
                                              outbound_streams :: term(),
                                              inbound_streams :: term(),
                                              assoc_id :: term()} |
                           gen_sctp:assoc_id(),
                       Address :: ip_address(),
                       Port :: non_neg_integer().

Return all localaddresses for a socket.

Returns a list of all local address/port number pairs for a socket, for the specified association Assoc.

This function can return multiple addresses for multihomed sockets, such as SCTP sockets. For other sockets it returns a one-element list.

Notice that parameter Assoc is by the SCTP Sockets API Extensions defined to be ignored for one-to-one style sockets. For one-to-many style sockets, the special value 0 is defined to mean that the returned addresses must be without any particular association. How different SCTP implementations interpret this varies somewhat.

RetroSearch is an open source project built by @garambo | Open a GitHub Issue

Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo

HTML: 3.2 | Encoding: UTF-8 | Version: 0.7.4