Search documentation of kernel

# net (kernel v10.4.1)

View Source

Network interface.

This module provides an API for the network interface.

# Summary

## Types

address_info()
ifaddrs()

Interface addresses and flags.

ifaddrs_filter()

Interface address filtering selector.

ifaddrs_filter_fun()

Interface address filtering selector `function/0`.

ifaddrs_filter_map()

Interface address filtering selector map.

ifaddrs_flag()
ifaddrs_flags()
name_info()
name_info_flag()
name_info_flag_ext()
name_info_flags()
network_interface_index()
network_interface_name()

## Functions

getaddrinfo(Host)

Equivalent to `getaddrinfo(Host, undefined)`.

getaddrinfo(Host, Service)

Network address and service translation.

gethostname()

Return the name of the current host.

getifaddrs()

Equivalent to `getifaddrs(default)`.

getifaddrs/1

Get interface addresses.

getifaddrs(Filter, Namespace)

Get interface addresses in a namespace.

getnameinfo(SockAddr)

Equivalent to `getnameinfo(SockAddr, undefined)`.

getnameinfo(SockAddr, Flags)

Address-to-name translation in a protocol-independant manner.

getservbyname(Name)

Equivalent to `getservbyname(Name, any)`.

getservbyname(Name, Protocol)

Get service by name.

getservbyport(PortNumber)

Equivalent to `getservbyport(PortNumber, any)`.

getservbyport(PortNumber, Protocol)

Get service by name.

if_index2name(Idx)

Mappings between network interface index and names.

if_name2index(Name)

Mappings between network interface names and indexes.

if_names()

Get network interface names and indexes.

# Types

# address_info()

(since OTP 22.0)

    -type address_info() ::
              #{family := socket:domain(),
                socktype := any | socket:type() | integer(),
                protocol := socket:protocol(),
                address := socket:sockaddr()}.

# ifaddrs()

(since OTP 22.0)

    -type ifaddrs() ::
              #{name := string(),
                flags := ifaddrs_flags(),
                addr => socket:sockaddr(),
                netmask => socket:sockaddr(),
                broadaddr => socket:sockaddr(),
                dstaddr => socket:sockaddr()}.

Interface addresses and flags.

This type defines addresses and flags for an interface.

#### Note

Not all fields of this map has to be present. The flags field can be used to test for some of the fields. For example `broadaddr` will only be present if the `broadcast` flag is present in flags.

# ifaddrs_filter()

(not exported) (since OTP 22.0)

    -type ifaddrs_filter() ::
              all | default | inet | inet6 | packet | link | hwaddr |
              ifaddrs_filter_map() |
              ifaddrs_filter_fun().

Interface address filtering selector.

- all - All interfaces

- default - Interfaces with address family `inet` or `inet6`

- inet | inet6 | packet | link - Interfaces with only the specified address family

- hwaddr - Interfaces with address family `packet` or `link`

# ifaddrs_filter_fun()

(not exported) (since OTP 22.0)

    -type ifaddrs_filter_fun() :: fun((ifaddrs()) -> boolean()).

Interface address filtering selector `function/0`.

For each `ifaddrs` entry, return either `true` to keep the entry or `false` to discard the entry.

For example, to get an interface list which only contains non-`loopback` `inet` interfaces:

    net:getifaddrs(
        fun (#{ addr  := #{family := inet},
                flags := Flags}) ->
              not lists:member(loopback, Flags);
            (_) ->
              false
        end).

# ifaddrs_filter_map()

(not exported) (since OTP 22.0)

    -type ifaddrs_filter_map() ::
              #{family :=
                    all | default | local | inet | inet6 | packet | link |
                    [local | inet | inet6 | packet | link],
                flags := any | [ifaddrs_flag()]}.

Interface address filtering selector map.

The `family` field can only have the (above) specified values (and not all the values of socket:domain()). It can also be a list of values, to cover the situation when any of the specified families are accepted. For example, family can be set to `[inet,inet6]` if either `inet` or `inet6` is accepted.

The use of the `flags` field is that any flag provided must exist for the interface.

For example, if `family` is set to `inet` and `flags` to `[broadcast, multicast]` only interfaces with address family `inet` and the flags `broadcast` and `multicast` will be listed.

# ifaddrs_flag()

(since OTP 22.0)

    -type ifaddrs_flag() ::
              up | broadcast | debug | loopback | pointopoint | notrailers | running | noarp | promisc |
              master | slave | multicast | portsel | automedia | dynamic.

# ifaddrs_flags()

(since OTP 22.0)

    -type ifaddrs_flags() :: [ifaddrs_flag()].

# name_info()

(since OTP 22.0)

    -type name_info() :: #{host := string(), service := string()}.

# name_info_flag()

(since OTP 22.0)

    -type name_info_flag() :: namereqd | dgram | nofqdn | numerichost | numericserv.

# name_info_flag_ext()

(since OTP 22.0)

    -type name_info_flag_ext() :: idn.

# name_info_flags()

(since OTP 22.0)

    -type name_info_flags() :: [name_info_flag() | name_info_flag_ext()].

# network_interface_index()

(since OTP 22.0)

    -type network_interface_index() :: non_neg_integer().

# network_interface_name()

(since OTP 22.0)

    -type network_interface_name() :: string().

# Functions

# getaddrinfo(Host)

(since OTP 22.0)

    -spec getaddrinfo(Host) -> {ok, Info} | {error, Reason}
                         when Host :: string(), Info :: [address_info()], Reason :: term().

Equivalent to `getaddrinfo(Host, undefined)`.

# getaddrinfo(Host, Service)

(since OTP 22.0)

    -spec getaddrinfo(Host, undefined) -> {ok, Info} | {error, Reason}
                         when Host :: string(), Info :: [address_info()], Reason :: term();
                     (undefined, Service) -> {ok, Info} | {error, Reason}
                         when Service :: string(), Info :: [address_info()], Reason :: term();
                     (Host, Service) -> {ok, Info} | {error, Reason}
                         when
                             Host :: string(),
                             Service :: string(),
                             Info :: [address_info()],
                             Reason :: term().

Network address and service translation.

This function is the inverse of `getnameinfo`. It converts host and service to a corresponding socket address.

One of the `Host` and `Service` may be `undefined` but not both.

# gethostname()

(since OTP 22.0)

    -spec gethostname() -> {ok, HostName} | {error, Reason} when HostName :: string(), Reason :: term().

Return the name of the current host.

# getifaddrs()

(since OTP 22.3)

    -spec getifaddrs() -> {ok, IfAddrs} | {error, Reason} when IfAddrs :: [ifaddrs()], Reason :: term().

Equivalent to `getifaddrs(default)`.

# getifaddrs/1

(since OTP 22.3)

    -spec getifaddrs(Filter) -> {ok, IfAddrs} | {error, Reason}
                        when Filter :: ifaddrs_filter(), IfAddrs :: [ifaddrs()], Reason :: term();
                    (Namespace) -> {ok, IfAddrs} | {error, Reason}
                        when Namespace :: file:filename_all(), IfAddrs :: [ifaddrs()], Reason :: term().

Get interface addresses.

With argument 'Filter: get the machines interface addresses, filtered according to `Filter`.

With argument `Namespace`: equivalent to `getifaddrs(default, Namespace)`.

# getifaddrs(Filter, Namespace)

(since OTP 22.3)

    -spec getifaddrs(Filter, Namespace) -> {ok, IfAddrs} | {error, Reason}
                        when
                            Filter :: ifaddrs_filter(),
                            Namespace :: file:filename_all(),
                            IfAddrs :: [ifaddrs()],
                            Reason :: term().

Get interface addresses in a namespace.

The same as `getifaddrs(Filter)` but in the specified `Namespace`.

# getnameinfo(SockAddr)

(since OTP 22.0)

    -spec getnameinfo(SockAddr) -> {ok, Info} | {error, Reason}
                         when SockAddr :: socket:sockaddr(), Info :: name_info(), Reason :: term().

Equivalent to `getnameinfo(SockAddr, undefined)`.

# getnameinfo(SockAddr, Flags)

(since OTP 22.0)

    -spec getnameinfo(SockAddr, Flags) -> {ok, Info} | {error, Reason}
                         when
                             SockAddr :: socket:sockaddr(),
                             Flags :: name_info_flags() | undefined,
                             Info :: name_info(),
                             Reason :: term().

Address-to-name translation in a protocol-independant manner.

This function is the inverse of `getaddrinfo`. It converts a socket address to a corresponding host and service.

# getservbyname(Name)

(since OTP 27.1)

    -spec getservbyname(Name) -> {ok, PortNumber} | {error, Reason}
                           when
                               Name :: atom() | string(),
                               PortNumber :: socket:port_number(),
                               Reason :: term().

Equivalent to `getservbyname(Name, any)`.

# getservbyname(Name, Protocol)

(since OTP 27.1)

    -spec getservbyname(Name, Protocol) -> {ok, PortNumber} | {error, Reason}
                           when
                               Name :: atom() | string(),
                               PortNumber :: socket:port_number(),
                               Protocol :: any | socket:protocol(),
                               Reason :: term().

Get service by name.

This function is used to get the port number of the specified protocol for the named service.

# getservbyport(PortNumber)

(since OTP 27.1)

    -spec getservbyport(PortNumber) -> {ok, Name} | {error, Reason}
                           when
                               PortNumber :: socket:port_number(),
                               Name :: atom() | string(),
                               Reason :: term().

Equivalent to `getservbyport(PortNumber, any)`.

# getservbyport(PortNumber, Protocol)

(since OTP 27.1)

    -spec getservbyport(PortNumber, Protocol) -> {ok, Name} | {error, Reason}
                           when
                               PortNumber :: socket:port_number(),
                               Protocol :: any | socket:protocol(),
                               Name :: atom() | string(),
                               Reason :: term().

Get service by name.

This function is used to get the service name of the specified protocol for the given port number.

# if_index2name(Idx)

(since OTP 22.0)

    -spec if_index2name(Idx) -> {ok, Name} | {error, Reason}
                           when
                               Idx :: network_interface_index(),
                               Name :: network_interface_name(),
                               Reason :: term().

Mappings between network interface index and names.

# if_name2index(Name)

(since OTP 22.0)

    -spec if_name2index(Name) -> {ok, Idx} | {error, Reason}
                           when
                               Name :: network_interface_name(),
                               Idx :: network_interface_index(),
                               Reason :: term().

Mappings between network interface names and indexes.

# if_names()

(since OTP 22.0)

    -spec if_names() -> {ok, Names} | {error, Reason}
                      when
                          Names :: [{Idx, If}],
                          Idx :: network_interface_index(),
                          If :: network_interface_name(),
                          Reason :: term().

Get network interface names and indexes.