Search documentation of kernel

# net_adm (kernel v11.0.3)

Copy Markdown View Source

Various Erlang net administration routines.

This module contains various network utility functions.

## Files

File `.hosts.erlang` consists of a number of host names written as Erlang terms. It is looked for in the current work directory, the user's home directory, and `$OTPROOT` (the root directory of Erlang/OTP), in that order.

The format of file `.hosts.erlang` must be one host name per line. The host names must be within quotes.

Example:

    'super.eua.ericsson.se'.
    'renat.eua.ericsson.se'.
    'grouse.eua.ericsson.se'.
    'gauffin1.eua.ericsson.se'.
    ^ (new line)

## Summary

### Types

verbosity()

### Functions

dns_hostname(Host)

Returns the official name of `Host`, or `{error, Host}` if no such name is found. See also `inet`.

host_file()

Reads file `.hosts.erlang`, see section Files. Returns the hosts in this file as a list. Returns `{error, Reason}` if the file cannot be read or the Erlang terms on the file cannot be interpreted.

localhost()

Returns the name of the local host. If Erlang was started with command-line flag `-name`, `Name` is the fully qualified name.

names()

Equivalent to `names(net_adm:localhost())`.

names(Host)

Returns the names and associated port numbers of the Erlang nodes that `epmd` registered at the specified host.

ping(Node)

Sets up a connection to `Node`. Returns `pong` if it is successful, otherwise `pang`.

world()

Equivalent to `world(silent)`.

world(Arg)

Calls `names(Host)` for all hosts that are specified in the Erlang host file `.hosts.erlang`, collects the replies, and then evaluates `ping(Node)` on all those nodes. Returns the list of all nodes that are successfully pinged.

world_list(Hosts)

Equivalent to `world_list(Hosts, silent)`.

world_list(Hosts, Arg)

Same as `world/0,1`, but the hosts are specified as argument instead of being read from `.hosts.erlang`.

## Types

# verbosity()

(not exported)

    -type verbosity() :: silent | verbose.

## Functions

# dns_hostname(Host)

    -spec dns_hostname(Host) -> {ok, Name} | {error, Host} when Host :: atom() | string(), Name :: string().

Returns the official name of `Host`, or `{error, Host}` if no such name is found. See also `inet`.

# host_file()

    -spec host_file() -> Hosts | {error, Reason}
                       when
                           Hosts :: [Host :: atom()],
                           Reason ::
                               file:posix() |
                               badarg | terminated | system_limit |
                               {Line :: integer(), Mod :: module(), Term :: term()}.

Reads file `.hosts.erlang`, see section Files. Returns the hosts in this file as a list. Returns `{error, Reason}` if the file cannot be read or the Erlang terms on the file cannot be interpreted.

# localhost()

    -spec localhost() -> Name when Name :: string().

Returns the name of the local host. If Erlang was started with command-line flag `-name`, `Name` is the fully qualified name.

# names()

    -spec names() -> {ok, [{Name, Port}]} | {error, Reason}
                   when Name :: string(), Port :: non_neg_integer(), Reason :: address | file:posix().

Equivalent to `names(net_adm:localhost())`.

# names(Host)

    -spec names(Host) -> {ok, [{Name, Port}]} | {error, Reason}
                   when
                       Host :: atom() | string() | inet:ip_address(),
                       Name :: string(),
                       Port :: non_neg_integer(),
                       Reason :: address | file:posix().

Returns the names and associated port numbers of the Erlang nodes that `epmd` registered at the specified host.

Similar to `epmd -names`, see `erts:epmd`.

Returns `{error, address}` if `epmd` is not operational.

Example:

    (arne@dunn)1> net_adm:names().
    {ok,[{"arne",40262}]}

# ping(Node)

    -spec ping(Node) -> pong | pang when Node :: atom().

Sets up a connection to `Node`. Returns `pong` if it is successful, otherwise `pang`.

# world()

    -spec world() -> [node()].

Equivalent to `world(silent)`.

# world(Arg)

    -spec world(Arg) -> [node()] when Arg :: verbosity().

Calls `names(Host)` for all hosts that are specified in the Erlang host file `.hosts.erlang`, collects the replies, and then evaluates `ping(Node)` on all those nodes. Returns the list of all nodes that are successfully pinged.

If `Arg == verbose`, the function writes information about which nodes it is pinging to `stdout`.

This function can be useful when a node is started, and the names of the other network nodes are not initially known.

Returns `{error, Reason}` if `host_file/0` returns `{error, Reason}`.

# world_list(Hosts)

    -spec world_list(Hosts) -> [node()] when Hosts :: [atom()].

Equivalent to `world_list(Hosts, silent)`.

# world_list(Hosts, Arg)

    -spec world_list(Hosts, Arg) -> [node()] when Hosts :: [atom()], Arg :: verbosity().

Same as `world/0,1`, but the hosts are specified as argument instead of being read from `.hosts.erlang`.