---
name: "init"
section: "3erl"
platform: "linux"
package: "erlang-manpages"
version: "1:25.2.3+dfsg-1+deb12u4"
release: "Debian 12 (Bookworm)"
platforms: ["linux"]
url: "https://new.carta.tech/init/3erl"
---

# init(3erl)

Coordination of system startup.

## NAME

init - Coordination of system startup.

## DESCRIPTION

This module is preloaded and contains the code for the *init* system process that coordinates the startup of the system. The first function evaluated at startup is *boot(BootArgs)*, where *BootArgs* is a list of command-line arguments supplied to the Erlang runtime system from the local operating system; see *[erl(1)](/erl/1.md)*.

*init* reads the boot script, which contains instructions on how to initiate the system. For more information about boot scripts, see *[script(5)](/script/5.md)*.

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

## DATA TYPES

```
mode() = embedded | interactive
```

Code loading mode.

## EXPORTS

```
boot(BootArgs) -> no_return()
```

Types:

BootArgs = \[binary()\]\

Starts the Erlang runtime system. This function is called when the emulator is started and coordinates system startup.

*BootArgs* are all command-line arguments except the emulator flags, that is, flags and plain arguments; see *[erl(1)](/erl/1.md)*.

*init* interprets some of the flags, see section Command-Line Flags below. The remaining flags ("user flags") and plain arguments are passed to the *init* loop and can be retrieved by calling *get\_arguments/0* and *get\_plain\_arguments/0*, respectively.

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

Types:

Flag = atom()\
 Arg = \[Values :: \[string()\]\]\

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

```
% erl -a b c -a d
...
1> init:get_argument(a).
{ok,[["b","c"],["d"]]}
```

The following flags are defined automatically and can be retrieved using this function:

- ***root*:**

  The installation directory of Erlang/OTP, *$ROOT*:

```
2> init:get_argument(root).
{ok,[["/usr/local/otp/releases/otp_beam_solaris8_r10b_patched"]]}
```

- ***progname*:**

  The name of the program which started Erlang:

```
3> init:get_argument(progname).
{ok,[["erl"]]}
```

- ***home*:**

  The home directory (on Unix, the value of $HOME):

```
4> init:get_argument(home).
{ok,[["/home/harry"]]}
```

Returns *error* if no value is associated with *Flag*.

```
get_arguments() -> Flags
```

Types:

Flags = \[{Flag :: atom(), Values :: \[string()\]}\]\

Returns all command-line flags and the system-defined flags, see *get\_argument/1*.

```
get_plain_arguments() -> [Arg]
```

Types:

Arg = string()\

Returns any plain command-line arguments as a list of strings (possibly empty).

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

Types:

InternalStatus = internal\_status()\
 ProvidedStatus = term()\

```
internal_status() = starting | started | stopping
```

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() -> ok
```

All applications are taken down smoothly, all code is unloaded, and all ports are closed before the system terminates. If command-line flag *-heart* was specified, the *heart* program tries to reboot the system. For more information, see *[heart(3erl)](/heart/3erl.md)*.

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

```
restart() -> ok
```

The same as *restart(\[\])*.

```
restart(Opts :: [{mode, mode()}]) -> ok
```

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 when restarting the system unless the *mode* option is given, allowing the code loading mode to be set to either *embedded* or *interactive*. All other *BootArgs* remain the same.

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

```
script_id() -> Id
```

Types:

Id = term()\

Gets 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() -> ok
```

The same as *stop(0)*.

```
stop(Status) -> ok
```

Types:

Status = integer() \>= 0 \| string()\

All applications are taken down smoothly, all code is unloaded, and all ports are closed before the system terminates by calling *halt(Status)*. If command-line flag *-heart* was specified, the *heart* program is terminated before the Erlang node terminates. For more information, see *[heart(3erl)](/heart/3erl.md)*.

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

## COMMAND-LINE FLAGS

**Warning:**

The support for loading of code from archive files is experimental. The only purpose of releasing it before it is ready is to obtain early feedback. The file format, semantics, interfaces, and so on, can be changed in a future release. The *-code\_path\_choice* flag is also experimental.

The *init* module interprets the following command-line flags:

- ***--*:**

  Everything following *--* up to the next flag is considered plain arguments and can be retrieved using *get\_plain\_arguments/0*.

- ***-code\_path\_choice Choice*:**

  Can be set to *strict* or *relaxed*. It controls how each directory in the code path is to be interpreted:

  - \*

    Strictly as it appears in the *boot script*, or

  - \*

    *init* is to be more relaxed and try to find a suitable directory if it can choose from a regular *ebin* directory and an *ebin* directory in an archive file.

  This flag is particular useful when you want to elaborate with code loading from archives without editing the *boot script*. For more information about interpretation of boot scripts, see *[script(5)](/script/5.md)*. The flag has also a similar effect on how the code server works; see *[code(3erl)](/code/3erl.md)*.

- ***-epmd\_module Module*:**

  Specifies the module to use for registration and lookup of node names. Defaults to *erl\_epmd*.

- ***-eval Expr*:**

  Scans, parses, and evaluates an arbitrary expression *Expr* during system initialization. If any of these steps fail (syntax error, parse error, or exception during evaluation), Erlang stops with an error message. In the following example Erlang is used 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 are 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.

- ***-extra*:**

  Everything following *-extra* is considered plain arguments and can be retrieved using *get\_plain\_arguments/0*.

- ***-run Mod \[Func \[Arg1, Arg2, ...\]\]*:**

  Evaluates the specified function call during system initialization. *Func* defaults to *start*. If no arguments are provided, the function is assumed to be of arity 0. Otherwise it is assumed to be of arity 1, taking the list *\[Arg1,Arg2,...\]* as argument. All arguments are passed as strings. If an exception is raised, Erlang stops with an error message.

  Example:

```
% erl -run foo -run foo bar -run foo bar baz 1 2
```

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

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

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

- ***-s Mod \[Func \[Arg1, Arg2, ...\]\]*:**

  Evaluates the specified function call during system initialization. *Func* defaults to *start*. If no arguments are provided, the function is assumed to be of arity 0. Otherwise it is assumed to be of arity 1, taking the list *\[Arg1,Arg2,...\]* as argument. All arguments are passed as atoms. If an exception is raised, Erlang stops with an error message.

  Example:

```
% erl -s foo -s foo bar -s foo bar baz 1 2
```

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

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

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

Because of the limited length of atoms, it is recommended to use *-run* instead.

## 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(3erl)](/erl_prim_loader/3erl.md)*, *[heart(3erl)](/heart/3erl.md)*