Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2.2_all 
NAME
init - Coordination of System Startup
DESCRIPTION
The init module is pre-loaded and contains the code for the init system process which
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. See erl(1).
init reads the boot script which contains instructions on how to initiate the system. See
script(5) for more information about boot scripts.
init also contains functions to restart, reboot, and stop the system.
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 start-up.
BootArgs are all command line arguments except the emulator flags, that is, flags
and plain arguments. See erl(1).
init itself interprets some of the flags, see 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.
% erl -a b c -a d
...
1> init:get_argument(a).
{ok,[["b","c"],["d"]]}
There are also a number of flags, which 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.
4> init:get_argument(home).
{ok,[["/home/harry"]]}
Returns error if there is no value associated with Flag.
get_arguments() -> Flags
Types:
Flags = [{Flag :: atom(), Values :: [string()]}]
Returns all command line flags, as well as 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 the -heart command line flag was given, the
heart program will try to reboot the system. Refer to heart(3erl) 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() -> 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 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() -> ok
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(3erl)
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.
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 the -heart command
line flag was given, the heart program is terminated before the Erlang node
terminates. Refer to heart(3erl) 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.
COMMAND LINE FLAGS
Warning:
The support for loading of code from archive files is experimental. The sole purpose of
releasing it before it is ready is to obtain early feedback. The file format, semantics,
interfaces etc. may 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:
This flag can be set to strict or relaxed. It controls whether each directory in the
code path should be interpreted strictly as it appears in the boot script or if init
should 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. See script(5) for more information about interpretation of
boot scripts. The flag does also have a similar affect on how the code server works.
See code(3erl).
-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. 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 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 which
does not return will block 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 which
does not return 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.
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), heart(3erl)