init - Coordination of System Startup

init is pre-loaded and coordinates the start-up of the system. The first function evaluated at start-up is boot(Bootargs), where Bootargs is a list of command line arguments supplied to the Erlang runtime system from the local operating system.

init reads the boot script which contains instructions on how to initiate the system. See also System Principles, Boot Scripts.

init also contains functions to restart, reboot, and stop the system.

The init module interprets the following flags:

-eval Expr ... Expr: Scans, parses and evaluates an arbitrary expression Expr during system initialization. If any of these steps fail (syntax error, parse error or crash during evaluation), the Erlang runtime system stops with an error message. Here is an example that seeds the random number generator:

$erl -eval '{X,Y,Z} = now(), random:seed(X, Y, Z).'

This example uses Erlang as a hexadecimal calculator:

$erl -noshell -eval 'R = 16#1F+16#A0, io:format("~.16B~n", [R])' -s erlang halt

BF

If multiple -eval expressions are specified, they will be evaluated sequentially in the order specified. -eval expressions are evaluated sequentially with -s and -run function calls (this also in the order specified). As with -s and -run, an evaluation that does not terminate, blocks the system initialization process.

-init_debug: The init process writes some debug information while interpreting the boot script.

-run Module [Function [Args]]: Evaluate the specified function during system initialization. Function defaults to start and Args to []. If the function call ends abnormally, the Erlang runtime system stops with an error message.

The arguments after -run are used as arguments to Erlang functions. All arguments are passed as strings. For example:

$erl -run foo -run foo bar -run foo bar baz 1 2

This starts the Erlang runtime system and then evaluates the following Erlang functions:

foo:start()
foo:bar()
foo:bar(["baz", "1", "2"]).

The functions are executed sequentially in the initialization process, which then terminates normally and passes control to the user. This means that a -run call which does not terminate will block further processing; to avoid this, use some variant of spawn in such cases.

-s Module [Function [Args]]: Evaluate the specified function during system initialization. Function defaults to start and Args to []. If the function call ends abnormally, the Erlang runtime system stops with an error message.

The arguments after -s are used as arguments to Erlang functions. All arguments are passed as atoms. For example:

$erl -s foo -s foo bar -s foo bar baz 1 2

This starts the Erlang runtime system and then evaluates the following Erlang functions:

foo:start()
foo:bar()
foo:bar([baz, '1', '2']).

The functions are executed sequentially in the initialization process, which then terminates normally and passes control to the user. This means that a -s call which does not terminate will block further processing; to avoid this, use some variant of spawn in such cases.

Due to the limited length of atoms, it is recommended that -run be used instead.

-shutdown_time Time: Specifies how long time (in ms) the init process is allowed to spend shutting down the system. If Time milliseconds has elapsed, all processes still existing are killed.

If -shutdown_time is not specified, the default value is infinity.

$erl -- a b -children thomas claire -ages 7 3 -- x y

...

1>init:get_plain_arguments().

["a", "b", "x", "y"] 2>init:get_argument(children).

{ok, [["thomas", "claire"]]} 3>init:get_argument(ages).

{ok, [["7", "3"]]} 4>init:get_argument(silly).

error

boot(BootArgs) -> void()

Types

BootArgs = [binary()]

Erlang (an Erlang runtime system) is started with the command:

$erl <script-flags> <user-flags>

erl is the name of the Erlang start-up script. <script-flags>, described in erl(1), are read by the script. <user-flags> are put into a list and passed as BootArgs to this function.

The function interprets a number of command line flags, see COMMAND LINE FLAGS below.

If the function finds other arguments starting with the character -, that argument is interpreted as a flag with zero or more values. It ends the previous argument. Example:

$erl -run foo bar -charles peterson

This starts the Erlang runtime system, evaluates foo:bar(), and sets the flag -charles, which has the associated value peterson.

Other arguments which are passed to the boot function, and do not fit into the above description, are passed to the init loop as plain arguments.

The special flag -- can be used to separate plain arguments from a preceding flag argument.

The special flag -extra causes all following arguments to become plain arguments, and not be subjected to any interpretation by Erlang.

get_args() -> [Arg]

Types

Arg = atom()

Returns the additional plain arguments as a list of atoms (possibly empty). It is recommended that get_plain_arguments/1 be used instead, because of the limited length of atoms.

get_argument(Flag) -> {ok, Arg} | error

Types

Flag = atom()

Arg = [Values]

 Values = [string()]

Returns all values associated with the command line flag Flag. If Flag is provided several times, each Values is returned in preserved order.

$erl -sname kalle -a b c -a d

...

1>init:get_argument(a).

{ok,[["b","c"],["d"]]}

Returns error if there is no value associated with Flag.

get_arguments() -> Flags

Types

Flags = [{Flag, Values}]

 Flag = atom()

 Values = [string()]

Returns all command line flags (as well as some system internal flags).

get_plain_arguments() -> [Arg]

Types

Arg = string()

Returns the additional plain arguments as a list of strings (possibly empty).

get_status() -> {InternalStatus, ProvidedStatus}

Types

InternalStatus = starting | started | stopping

ProvidedStatus = term()

The current status of the init process can be inspected. During system startup (initialization), InternalStatus is starting, and ProvidedStatus indicates how far the boot script has been interpreted. Each {progress, Info} term interpreted in the boot script affects ProvidedStatus, that is, ProvidedStatus gets the value of Info.

reboot() -> void()

All applications are taken down smoothly, all code is unloaded, and all ports are closed before the system terminates. If the -heart command line flag was given, the heart program will try to reboot the system. Refer to heart(3) for more information.

To limit the shutdown time, the time init is allowed to spend taking down applications, the -shutdown_time command line flag should be used.

restart() -> void()

The system is restarted inside the running Erlang node, which means that the emulator is not restarted. All applications are taken down smoothly, all code is unloaded, and all ports are closed before the system is booted again in the same way as initially started. The same BootArgs are used again.

To limit the shutdown time, the time init is allowed to spend taking down applications, the -shutdown_time command line flag should be used.

script_id() -> Id

Types

Id = term()

Get the identity of the boot script used to boot the system. Id can be any Erlang term. In the delivered boot scripts, Id is {Name, Vsn}. Name and Vsn are strings.

stop() -> void()

All applications are taken down smoothly, all code is unloaded, and all ports are closed before the system terminates. If the -heart command line flag was given, the heart program is terminated before the Erlang node terminates. Refer to heart(3) for more information.

To limit the shutdown time, the time init is allowed to spend taking down applications, the -shutdown_time command line flag should be used.

erl_prim_loader(3), heart(3)

Claes Wikström - support@erlang.ericsson.se
Magnus Fröberg - support@erlang.ericsson.se