# init

### MODULE

init

### MODULE SUMMARY

Called at System Start

### DESCRIPTION

`init` is pre-loaded into the system before the system starts and it coordinates the start-up of the system. The first function evaluated at start-up is `boot(Bootargs)`, where `Bootargs` is a list of the arguments supplied to the Erlang runtime system from the local operating system. The Erlang code for the module `init` is always pre-loaded.

`init` reads a boot script which contains instructions on how to initiate the system. The default boot script (`start.boot`) is in the directory `<ERL_INSTALL_DIR>/bin`.

`init` contains functions to fetch command line flags, or arguments, supplied to the Erlang runtime system.

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

### EXPORTS

`boot(BootArgs) -> void()`

Types:

`BootArgs = [binary()]`

Erlang 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 `Args` to `boot/1`.

The `boot/1` function interprets the `boot`, `mode`, and `s` flags. These are described in `COMMAND LINE FLAGS`.

If the `boot` 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. For 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 to `boot` 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_arguments() -> Flags`

Types:

`Flags = [{Flag,FValue}]`
`Flag = atom()`
`FValue = [Value]`
`Value = string()`

Returns all flags given to the system.

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

Types:

`Flag = atom()`
`Values = [FValue]`
`FValue = [Value]`
`Value = string()`

Returns all values associated with `Flag`. If `Flag` is provided several times, each `FValue` is returned in preserved order.

`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_plain_arguments() -> [Arg]`

Types:

`Arg = string()`

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

`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.

`reboot() -> void()`

All applications are taken down smoothly, all code is unloaded, and all ports are closed before the Erlang node terminates. If the `-heart` system flag was given, the `heart` program will try to reboot the system. Refer to the `heart` module for more information.

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

`stop() -> void()`

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

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

`get_status() -> {InternalStatus, ProvidedStatus}`

Types:

`InternalStatus = starting | started | stopping`
`ProvidedStatus = term()`

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

`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.

### Command Line Flags

The `init` module interprets the following flags:

-boot File
  Specifies the name of the boot script, `File`.boot, used to start the system. Unless `File` contains an absolute path, the system searches for `File`.boot in the current and `<ERL_INSTALL_DIR>/bin` directories
  If this flag is omitted, the `<ERL_INSTALL_DIR>/bin/start.boot` boot script is used.
-boot_var Var Directory [Var Directory]
  If the boot script used contains another path variable than $ROOT, that variable must have a value assigned in order to start the system. A boot variable is used if user applications are installed in a different location than underneath the `<ERL_INSTALL_DIR>/lib` directory. `$Var` is expanded to `Directory` in the boot script.
-mode Mode
  The mode flag indicates if the system will load code automatically at runtime, or if all code should be loaded during system initialization. `Mode` can be either `interactive` (allow automatic code loading) or `embedded` (load all code during start-up).
-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 time is `infinity`.
-run Module [Function [Args]]
  Evaluate the 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 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 255 character limit on atoms, it is recommended that `-run` be used instead.
-eval 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's 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 doesn't terminate, blocks the system initialization process.
-init_debug
  The `init` process writes some debug information while interpreting the boot script.

### Example

    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

### See also

erl_prim_loader(3), heart(3)

### AUTHORS

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

kernel 2.10.4
Copyright © 1991-2005 Ericsson AB