The R13B03 release.OTP_R13B03

1 files changed, 384 insertions, 0 deletions

diff --git a/erts/doc/src/init.xml b/erts/doc/src/init.xml
new file mode 100644
index 0000000000..33364c709a
--- /dev/null
+++ b/erts/doc/src/init.xml
@@ -0,0 +1,384 @@
+<?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>&nbsp;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>&nbsp;Flag = atom()</v>
+        <v>&nbsp;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>
+