.TH init 3erl "erts 11.1.8" "Ericsson AB" "Erlang Module Definition"
.SH NAME
init \- Coordination of system startup.
.SH DESCRIPTION
.LP
This module is preloaded and contains the code for the \fIinit\fR\& system process that coordinates the startup of the system\&. The first function evaluated at startup is \fIboot(BootArgs)\fR\&, where \fIBootArgs\fR\& is a list of command-line arguments supplied to the Erlang runtime system from the local operating system; see \fIerl(1)\fR\&\&.
.LP
\fIinit\fR\& reads the boot script, which contains instructions on how to initiate the system\&. For more information about boot scripts, see \fIscript(5)\fR\&\&.
.LP
\fIinit\fR\& also contains functions to restart, reboot, and stop the system\&.
.SH DATA TYPES
.nf

\fBmode()\fR\& = embedded | interactive
.br
.fi
.RS
.LP
Code loading mode\&.
.RE

.SH EXPORTS
.LP
.nf

.B
boot(BootArgs) -> no_return()
.br
.fi
.br
.RS
.LP
Types:

.RS 3
BootArgs = [binary()]
.br
.RE
.RE
.RS
.LP
Starts the Erlang runtime system\&. This function is called when the emulator is started and coordinates system startup\&.
.LP
\fIBootArgs\fR\& are all command-line arguments except the emulator flags, that is, flags and plain arguments; see \fIerl(1)\fR\&\&.
.LP
\fIinit\fR\& interprets some of the flags, see section Command-Line Flags below\&. The remaining flags ("user flags") and plain arguments are passed to the \fIinit\fR\& loop and can be retrieved by calling \fIget_arguments/0\fR\& and \fIget_plain_arguments/0\fR\&, respectively\&.
.RE

.LP
.nf

.B
get_argument(Flag) -> {ok, Arg} | error
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Flag = atom()
.br
Arg = [Values :: [string()]]
.br
.RE
.RE
.RS
.LP
Returns all values associated with the command-line user flag \fIFlag\fR\&\&. If \fIFlag\fR\& is provided several times, each \fIValues\fR\& is returned in preserved order\&. Example:
.LP
.nf

% erl -a b c -a d
\&...
1> init:get_argument(a)\&.
{ok,[["b","c"],["d"]]}
.fi
.LP
The following flags are defined automatically and can be retrieved using this function:
.RS 2
.TP 2
.B
\fIroot\fR\&:
The installation directory of Erlang/OTP, \fI$ROOT\fR\&:
.LP
.nf

2> init:get_argument(root)\&.
{ok,[["/usr/local/otp/releases/otp_beam_solaris8_r10b_patched"]]}
.fi
.TP 2
.B
\fIprogname\fR\&:
The name of the program which started Erlang:
.LP
.nf

3> init:get_argument(progname)\&.
{ok,[["erl"]]}
.fi
.TP 2
.B
\fIhome\fR\&:
The home directory (on Unix, the value of $HOME):
.LP
.nf

4> init:get_argument(home)\&.
{ok,[["/home/harry"]]}
.fi
.RE
.LP
Returns \fIerror\fR\& if no value is associated with \fIFlag\fR\&\&.
.RE

.LP
.nf

.B
get_arguments() -> Flags
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Flags = [{Flag :: atom(), Values :: [string()]}]
.br
.RE
.RE
.RS
.LP
Returns all command-line flags and the system-defined flags, see \fIget_argument/1\fR\&\&.
.RE

.LP
.nf

.B
get_plain_arguments() -> [Arg]
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Arg = string()
.br
.RE
.RE
.RS
.LP
Returns any plain command-line arguments as a list of strings (possibly empty)\&.
.RE

.LP
.nf

.B
get_status() -> {InternalStatus, ProvidedStatus}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
InternalStatus = internal_status()
.br
ProvidedStatus = term()
.br
.nf
\fBinternal_status()\fR\& = starting | started | stopping
.fi
.br
.RE
.RE
.RS
.LP
The current status of the \fIinit\fR\& process can be inspected\&. During system startup (initialization), \fIInternalStatus\fR\& is \fIstarting\fR\&, and \fIProvidedStatus\fR\& indicates how far the boot script has been interpreted\&. Each \fI{progress, Info}\fR\& term interpreted in the boot script affects \fIProvidedStatus\fR\&, that is, \fIProvidedStatus\fR\& gets the value of \fIInfo\fR\&\&.
.RE

.LP
.nf

.B
reboot() -> ok
.br
.fi
.br
.RS
.LP
All applications are taken down smoothly, all code is unloaded, and all ports are closed before the system terminates\&. If command-line flag \fI-heart\fR\& was specified, the \fIheart\fR\& program tries to reboot the system\&. For more information, see \fIheart(3erl)\fR\&\&.
.LP
To limit the shutdown time, the time \fIinit\fR\& is allowed to spend taking down applications, command-line flag \fI-shutdown_time\fR\& is to be used\&.
.RE

.LP
.nf

.B
restart() -> ok
.br
.fi
.br
.RS
.LP
The same as \fIrestart([])\fR\&\&.
.RE

.LP
.nf

.B
restart(Opts :: [{mode, mode()}]) -> ok
.br
.fi
.br
.RS
.LP
The system is restarted \fIinside\fR\& 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\&.
.LP
The same \fIBootArgs\fR\& are used when restarting the system unless the \fImode\fR\& option is given, allowing the code loading mode to be set to either \fIembedded\fR\& or \fIinteractive\fR\&\&. All other \fIBootArgs\fR\& remain the same\&.
.LP
To limit the shutdown time, the time \fIinit\fR\& is allowed to spend taking down applications, command-line flag \fI-shutdown_time\fR\& is to be used\&.
.RE

.LP
.nf

.B
script_id() -> Id
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Id = term()
.br
.RE
.RE
.RS
.LP
Gets the identity of the boot script used to boot the system\&. \fIId\fR\& can be any Erlang term\&. In the delivered boot scripts, \fIId\fR\& is \fI{Name, Vsn}\fR\&\&. \fIName\fR\& and \fIVsn\fR\& are strings\&.
.RE

.LP
.nf

.B
stop() -> ok
.br
.fi
.br
.RS
.LP
The same as \fIstop(0)\fR\&\&.
.RE

.LP
.nf

.B
stop(Status) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Status = integer() >= 0 | string()
.br
.RE
.RE
.RS
.LP
All applications are taken down smoothly, all code is unloaded, and all ports are closed before the system terminates by calling \fIhalt(Status)\fR\&\&. If command-line flag \fI-heart\fR\& was specified, the \fIheart\fR\& program is terminated before the Erlang node terminates\&. For more information, see \fIheart(3erl)\fR\&\&.
.LP
To limit the shutdown time, the time \fIinit\fR\& is allowed to spend taking down applications, command-line flag \fI-shutdown_time\fR\& is to be used\&.
.RE

.SH "COMMAND-LINE FLAGS"

.LP

.RS -4
.B
Warning:
.RE
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 \fI-code_path_choice\fR\& flag is also experimental\&.

.LP
The \fIinit\fR\& module interprets the following command-line flags:
.RS 2
.TP 2
.B
\fI--\fR\&:
Everything following \fI--\fR\& up to the next flag is considered plain arguments and can be retrieved using \fIget_plain_arguments/0\fR\&\&.
.TP 2
.B
\fI-code_path_choice Choice\fR\&:
Can be set to \fIstrict\fR\& or \fIrelaxed\fR\&\&. It controls how each directory in the code path is to be interpreted:
.RS 2
.TP 2
*
Strictly as it appears in the \fIboot script\fR\&, or
.LP
.TP 2
*
\fIinit\fR\& is to be more relaxed and try to find a suitable directory if it can choose from a regular \fIebin\fR\& directory and an \fIebin\fR\& directory in an archive file\&.
.LP
.RE

.RS 2
.LP
This flag is particular useful when you want to elaborate with code loading from archives without editing the \fIboot script\fR\&\&. For more information about interpretation of boot scripts, see \fIscript(5)\fR\&\&. The flag has also a similar effect on how the code server works; see \fIcode(3erl)\fR\&\&.
.RE

.TP 2
.B
\fI-epmd_module Module\fR\&:
Specifies the module to use for registration and lookup of node names\&. Defaults to \fIerl_epmd\fR\&\&.
.TP 2
.B
\fI-eval Expr\fR\&:
Scans, parses, and evaluates an arbitrary expression \fIExpr\fR\& 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:
.LP
.nf

% erl -noshell -eval \&'R = 16#1F+16#A0, io:format("~\&.16B~n", [R])\&' \\\\
-s erlang halt
BF
.fi
.RS 2
.LP
If multiple \fI-eval\fR\& expressions are specified, they are evaluated sequentially in the order specified\&. \fI-eval\fR\& expressions are evaluated sequentially with \fI-s\fR\& and \fI-run\fR\& function calls (this also in the order specified)\&. As with \fI-s\fR\& and \fI-run\fR\&, an evaluation that does not terminate blocks the system initialization process\&.
.RE

.TP 2
.B
\fI-extra\fR\&:
Everything following \fI-extra\fR\& is considered plain arguments and can be retrieved using \fIget_plain_arguments/0\fR\&\&.
.TP 2
.B
\fI-run Mod [Func [Arg1, Arg2, \&.\&.\&.]]\fR\&:
Evaluates the specified function call during system initialization\&. \fIFunc\fR\& defaults to \fIstart\fR\&\&. 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 \fI[Arg1,Arg2,\&.\&.\&.]\fR\& as argument\&. All arguments are passed as strings\&. If an exception is raised, Erlang stops with an error message\&.
.RS 2
.LP
Example:
.RE

.LP
.nf

% erl -run foo -run foo bar -run foo bar baz 1 2
.fi
.RS 2
.LP
This starts the Erlang runtime system and evaluates the following functions:
.RE

.LP
.nf

foo:start()
foo:bar()
foo:bar(["baz", "1", "2"]).
.fi
.RS 2
.LP
The functions are executed sequentially in an initialization process, which then terminates normally and passes control to the user\&. This means that a \fI-run\fR\& call that does not return blocks further processing; to avoid this, use some variant of \fIspawn\fR\& in such cases\&.
.RE

.TP 2
.B
\fI-s Mod [Func [Arg1, Arg2, \&.\&.\&.]]\fR\&:
Evaluates the specified function call during system initialization\&. \fIFunc\fR\& defaults to \fIstart\fR\&\&. 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 \fI[Arg1,Arg2,\&.\&.\&.]\fR\& as argument\&. All arguments are passed as atoms\&. If an exception is raised, Erlang stops with an error message\&.
.RS 2
.LP
Example:
.RE

.LP
.nf

% erl -s foo -s foo bar -s foo bar baz 1 2
.fi
.RS 2
.LP
This starts the Erlang runtime system and evaluates the following functions:
.RE

.LP
.nf

foo:start()
foo:bar()
foo:bar([baz, '1', '2']).
.fi
.RS 2
.LP
The functions are executed sequentially in an initialization process, which then terminates normally and passes control to the user\&. This means that a \fI-s\fR\& call that does not return blocks further processing; to avoid this, use some variant of \fIspawn\fR\& in such cases\&.
.RE

.RS 2
.LP
Because of the limited length of atoms, it is recommended to use \fI-run\fR\& instead\&.
.RE

.RE
.SH "EXAMPLE"

.LP
.nf

% 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
.fi
.SH "SEE ALSO"

.LP
\fIerl_prim_loader(3erl)\fR\&, \fIheart(3erl)\fR\&