init(3)

MODULE
init - 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 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 system.

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

EXPORTS

boot(BootArgs) -> void()

    Types
        BootArgs = [term()]

    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 -s foo bar -charles peterson

    This starts the Erlang 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.

get_arguments() -> Flags

    Types
        Flags = [{Flag, [Value]}]
        Flag = atom()
        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 (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
        ProvidedStatus = term()

    During system start (initialization), the current status can be inspected. Internally, the init module can be either starting, or started. 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.

    -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 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 system and then evaluates the following Erlang functions:

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

        The control is then passed to the user.

        Example: erl -s c lc File1 File2 -s erlang halt

        This starts Erlang and evaluates c:lc([File1, File2]), which compiles the files File1 and File2. This is followed by erlang:halt() (the BIF halt/1) which stops the system.

    -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_args().
[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 Wikstrom - klacke@erix.ericsson.se
Magnus Froberg - magnus@erix.ericsson.se