<?xml version="1.0" encoding="latin1" ?> <!DOCTYPE erlref SYSTEM "erlref.dtd"> <erlref> <header> <copyright> <year>1996</year><year>2009</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> The contents of this file are subject to the Erlang Public License, Version 1.1, (the "License"); you may not use this file except in compliance with the License. You should have received a copy of the Erlang Public License along with this software. If not, it can be retrieved online at http://www.erlang.org/. Software distributed under the License is distributed on an "AS IS" basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for the specific language governing rights and limitations under the License. </legalnotice> <title>init</title> <prepared></prepared> <docno></docno> <date></date> <rev></rev> <file>init.xml</file> </header> <module>init</module> <modulesummary>Coordination of System Startup</modulesummary> <description> <p>The <c>init</c> module is pre-loaded and contains the code for the <c>init</c> system process which coordinates the start-up of the system. The first function evaluated at start-up is <c>boot(BootArgs)</c>, where <c>BootArgs</c> is a list of command line arguments supplied to the Erlang runtime system from the local operating system. See <seealso marker="erts:erl">erl(1)</seealso>.</p> <p><c>init</c> reads the boot script which contains instructions on how to initiate the system. See <seealso marker="sasl:script">script(4)</seealso> for more information about boot scripts.</p> <p><c>init</c> also contains functions to restart, reboot, and stop the system.</p> </description> <funcs> <func> <name>boot(BootArgs) -> void()</name> <fsummary>Start the Erlang runtime system</fsummary> <type> <v>BootArgs = [binary()]</v> </type> <desc> <p>Starts the Erlang runtime system. This function is called when the emulator is started and coordinates system start-up.</p> <p><c>BootArgs</c> are all command line arguments except the emulator flags, that is, flags and plain arguments. See <seealso marker="erts:erl">erl(1)</seealso>.</p> <p><c>init</c> itself interprets some of the flags, see <seealso marker="#flags">Command Line Flags</seealso> below. The remaining flags ("user flags") and plain arguments are passed to the <c>init</c> loop and can be retrieved by calling <c>get_arguments/0</c> and <c>get_plain_arguments/0</c>, respectively.</p> </desc> </func> <func> <name>get_args() -> [Arg]</name> <fsummary>Get all non-flag command line arguments</fsummary> <type> <v>Arg = atom()</v> </type> <desc> <p>Returns any plain command line arguments as a list of atoms (possibly empty). It is recommended that <c>get_plain_arguments/1</c> is used instead, because of the limited length of atoms.</p> </desc> </func> <func> <name>get_argument(Flag) -> {ok, Arg} | error</name> <fsummary>Get the values associated with a command line user flag</fsummary> <type> <v>Flag = atom()</v> <v>Arg = [Values]</v> <v> Values = [string()]</v> </type> <desc> <p>Returns all values associated with the command line user flag <c>Flag</c>. If <c>Flag</c> is provided several times, each <c>Values</c> is returned in preserved order.</p> <pre> % <input>erl -a b c -a d</input> ... 1> <input>init:get_argument(a).</input> {ok,[["b","c"],["d"]]}</pre> <p>There are also a number of flags, which are defined automatically and can be retrieved using this function:</p> <taglist> <tag><c>root</c></tag> <item> <p>The installation directory of Erlang/OTP, <c>$ROOT</c>.</p> <pre> 2> <input>init:get_argument(root).</input> {ok,[["/usr/local/otp/releases/otp_beam_solaris8_r10b_patched"]]}</pre> </item> <tag><c>progname</c></tag> <item> <p>The name of the program which started Erlang.</p> <pre> 3> <input>init:get_argument(progname).</input> {ok,[["erl"]]}</pre> </item> <tag><c>home</c></tag> <item> <p>The home directory.</p> <pre> 4> <input>init:get_argument(home).</input> {ok,[["/home/harry"]]}</pre> </item> </taglist> <p>Returns <c>error</c> if there is no value associated with <c>Flag</c>.</p> </desc> </func> <func> <name>get_arguments() -> Flags</name> <fsummary>Get all command line user flags</fsummary> <type> <v>Flags = [{Flag, Values}]</v> <v> Flag = atom()</v> <v> Values = [string()]</v> </type> <desc> <p>Returns all command line flags, as well as the system defined flags, see <c>get_argument/1</c>.</p> </desc> </func> <func> <name>get_plain_arguments() -> [Arg]</name> <fsummary>Get all non-flag command line arguments</fsummary> <type> <v>Arg = string()</v> </type> <desc> <p>Returns any plain command line arguments as a list of strings (possibly empty).</p> </desc> </func> <func> <name>get_status() -> {InternalStatus, ProvidedStatus}</name> <fsummary>Get system status information</fsummary> <type> <v>InternalStatus = starting | started | stopping</v> <v>ProvidedStatus = term()</v> </type> <desc> <p>The current status of the <c>init</c> process can be inspected. During system startup (initialization), <c>InternalStatus</c> is <c>starting</c>, and <c>ProvidedStatus</c> indicates how far the boot script has been interpreted. Each <c>{progress, Info}</c> term interpreted in the boot script affects <c>ProvidedStatus</c>, that is, <c>ProvidedStatus</c> gets the value of <c>Info</c>.</p> </desc> </func> <func> <name>reboot() -> void()</name> <fsummary>Take down and restart an Erlang node smoothly</fsummary> <desc> <p>All applications are taken down smoothly, all code is unloaded, and all ports are closed before the system terminates. If the <c>-heart</c> command line flag was given, the <c>heart</c> program will try to reboot the system. Refer to <c>heart(3)</c> for more information.</p> <p>To limit the shutdown time, the time <c>init</c> is allowed to spend taking down applications, the <c>-shutdown_time</c> command line flag should be used.</p> </desc> </func> <func> <name>restart() -> void()</name> <fsummary>Restart the running Erlang node</fsummary> <desc> <p>The system is restarted <em>inside</em> 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 <c>BootArgs</c> are used again.</p> <p>To limit the shutdown time, the time <c>init</c> is allowed to spend taking down applications, the <c>-shutdown_time</c> command line flag should be used.</p> </desc> </func> <func> <name>script_id() -> Id</name> <fsummary>Get the identity of the used boot script</fsummary> <type> <v>Id = term()</v> </type> <desc> <p>Get the identity of the boot script used to boot the system. <c>Id</c> can be any Erlang term. In the delivered boot scripts, <c>Id</c> is <c>{Name, Vsn}</c>. <c>Name</c> and <c>Vsn</c> are strings.</p> </desc> </func> <func> <name>stop() -> void()</name> <fsummary>Take down an Erlang node smoothly</fsummary> <desc> <p>All applications are taken down smoothly, all code is unloaded, and all ports are closed before the system terminates. If the <c>-heart</c> command line flag was given, the <c>heart</c> program is terminated before the Erlang node terminates. Refer to <c>heart(3)</c> for more information.</p> <p>To limit the shutdown time, the time <c>init</c> is allowed to spend taking down applications, the <c>-shutdown_time</c> command line flag should be used.</p> </desc> </func> <func> <name>stop(Status) -> void()</name> <fsummary>Take down an Erlang node smoothly</fsummary> <type> <v>Status = int()>=0 | string()</v> </type> <desc> <p>All applications are taken down smoothly, all code is unloaded, and all ports are closed before the system terminates by calling <c>halt(Status)</c>. If the <c>-heart</c> command line flag was given, the <c>heart</c> program is terminated before the Erlang node terminates. Refer to <c>heart(3)</c> for more information.</p> <p>To limit the shutdown time, the time <c>init</c> is allowed to spend taking down applications, the <c>-shutdown_time</c> command line flag should be used.</p> </desc> </func> </funcs> <section> <marker id="flags"></marker> <title>Command Line Flags</title> <warning><p>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 <c>-code_path_choice</c> flag is also experimental.</p></warning> <p>The <c>init</c> module interprets the following command line flags:</p> <taglist> <tag><c>--</c></tag> <item> <p>Everything following <c>--</c> up to the next flag is considered plain arguments and can be retrieved using <c>get_plain_arguments/0</c>.</p> </item> <tag><c>-code_path_choice Choice</c></tag> <item> <p>This flag can be set to <c>strict</c> or <c>relaxed</c>. It controls whether each directory in the code path should be interpreted strictly as it appears in the <c>boot script</c> or if <c>init</c> 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 <c>boot script</c>. See <seealso marker="sasl:script">script(4)</seealso> for more information about interpretation of boot scripts. The flag does also have a similar affect on how the code server works. See <seealso marker="kernel:code">code(3)</seealso>.</p> </item> <tag><c>-eval Expr</c></tag> <item> <p>Scans, parses and evaluates an arbitrary expression <c>Expr</c> 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:</p> <pre> % <input>erl -eval '{X,Y,Z}' = now(), random:seed(X,Y,Z).'</input></pre> <p>This example uses Erlang as a hexadecimal calculator:</p> <pre> % <input>erl -noshell -eval 'R = 16#1F+16#A0, io:format("~.16B~n", [R])' \\</input> <input>-s erlang halt</input> BF</pre> <p>If multiple <c>-eval</c> expressions are specified, they are evaluated sequentially in the order specified. <c>-eval</c> expressions are evaluated sequentially with <c>-s</c> and <c>-run</c> function calls (this also in the order specified). As with <c>-s</c> and <c>-run</c>, an evaluation that does not terminate, blocks the system initialization process.</p> </item> <tag><c>-extra</c></tag> <item> <p>Everything following <c>-extra</c> is considered plain arguments and can be retrieved using <c>get_plain_arguments/0</c>.</p> </item> <tag><c>-run Mod [Func [Arg1, Arg2, ...]]</c></tag> <item> <p>Evaluates the specified function call during system initialization. <c>Func</c> defaults to <c>start</c>. 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 <c>[Arg1,Arg2,...]</c> as argument. All arguments are passed as strings. If an exception is raised, Erlang stops with an error message.</p> <p>Example:</p> <pre> % <input>erl -run foo -run foo bar -run foo bar baz 1 2</input></pre> <p>This starts the Erlang runtime system and evaluates the following functions:</p> <code type="none"> foo:start() foo:bar() foo:bar(["baz", "1", "2"]).</code> <p>The functions are executed sequentially in an initialization process, which then terminates normally and passes control to the user. This means that a <c>-run</c> call which does not return will block further processing; to avoid this, use some variant of <c>spawn</c> in such cases.</p> </item> <tag><c>-s Mod [Func [Arg1, Arg2, ...]]</c></tag> <item> <p>Evaluates the specified function call during system initialization. <c>Func</c> defaults to <c>start</c>. 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 <c>[Arg1,Arg2,...]</c> as argument. All arguments are passed as atoms. If an exception is raised, Erlang stops with an error message.</p> <p>Example:</p> <pre> % <input>erl -s foo -s foo bar -s foo bar baz 1 2</input></pre> <p>This starts the Erlang runtime system and evaluates the following functions:</p> <code type="none"> foo:start() foo:bar() foo:bar([baz, '1', '2']).</code> <p>The functions are executed sequentially in an initialization process, which then terminates normally and passes control to the user. This means that a <c>-s</c> call which does not return will block further processing; to avoid this, use some variant of <c>spawn</c> in such cases.</p> <p>Due to the limited length of atoms, it is recommended that <c>-run</c> be used instead.</p> </item> </taglist> </section> <section> <title>Example</title> <pre> % <input>erl -- a b -children thomas claire -ages 7 3 -- x y</input> ... 1> <input>init:get_plain_arguments().</input> ["a","b","x","y"] 2> <input>init:get_argument(children).</input> {ok,[["thomas","claire"]]} 3> <input>init:get_argument(ages).</input> {ok, [["7","3"]]} 4> <input>init:get_argument(silly).</input> error</pre> </section> <section> <title>SEE ALSO</title> <p><seealso marker="erl_prim_loader">erl_prim_loader(3)</seealso>, <seealso marker="kernel:heart">heart(3)</seealso></p> </section> </erlref>