diff options
Diffstat (limited to 'erts/doc/src/init.xml')
| -rw-r--r-- | erts/doc/src/init.xml | 226 |
1 files changed, 125 insertions, 101 deletions
diff --git a/erts/doc/src/init.xml b/erts/doc/src/init.xml index a88a815ef6..54507c6572 100644 --- a/erts/doc/src/init.xml +++ b/erts/doc/src/init.xml @@ -19,7 +19,7 @@ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. - + </legalnotice> <title>init</title> @@ -30,128 +30,140 @@ <file>init.xml</file> </header> <module>init</module> - <modulesummary>Coordination of System Startup</modulesummary> + <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>This module is preloaded and contains the code for + the <c>init</c> system process that coordinates the startup of + the system. The first function evaluated at startup 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"><c>erl(1)</c></seealso>.</p> + + <p><c>init</c> reads the boot script, which contains instructions on + how to initiate the system. For more information about boot scripts, see + <seealso marker="sasl:script"><c>sasl:script(4)</c></seealso>.</p> + <p><c>init</c> also contains functions to restart, reboot, and stop the system.</p> </description> + <funcs> <func> <name name="boot" arity="1"/> - <fsummary>Start the Erlang runtime system</fsummary> + <fsummary>Start the Erlang runtime system.</fsummary> <desc> <p>Starts the Erlang runtime system. This function is called - when the emulator is started and coordinates system start-up.</p> - <p><c><anno>BootArgs</anno></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. + when the emulator is started and coordinates system startup.</p> + <p><c><anno>BootArgs</anno></c> are all command-line arguments except + the emulator flags, that is, flags and plain arguments; see + <seealso marker="erts:erl"><c>erl(1)</c></seealso>.</p> + <p><c>init</c> interprets some of the flags, see section + <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> + <seealso marker="#get_arguments/0"><c>get_arguments/0</c></seealso> + and <seealso marker="#get_plain_arguments/0"> + <c>get_plain_arguments/0</c></seealso>, respectively.</p> </desc> </func> + <func> <name name="get_argument" arity="1"/> - <fsummary>Get the values associated with a command line user flag</fsummary> + <fsummary>Get the values associated with a command-line user flag. + </fsummary> <desc> - <p>Returns all values associated with the command line user flag - <c><anno>Flag</anno></c>. If <c><anno>Flag</anno></c> is provided several times, each - <c><anno>Values</anno></c> is returned in preserved order.</p> + <p>Returns all values associated with the command-line user flag + <c><anno>Flag</anno></c>. If <c><anno>Flag</anno></c> is provided + several times, each <c><anno>Values</anno></c> is returned in + preserved order. Example:</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 + <p>The following flags 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> + <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> + <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> + <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> + <p>Returns <c>error</c> if no value is associated with <c>Flag</c>.</p> </desc> </func> + <func> <name name="get_arguments" arity="0"/> - <fsummary>Get all command line user flags</fsummary> + <fsummary>Get all command-line user flags.</fsummary> <desc> - <p>Returns all command line flags, as well as the system - defined flags, see <c>get_argument/1</c>.</p> + <p>Returns all command-line flags and the system-defined flags, see + <seealso marker="#get_argument/1"><c>get_argument/1</c></seealso>.</p> </desc> </func> + <func> <name name="get_plain_arguments" arity="0"/> - <fsummary>Get all non-flag command line arguments</fsummary> + <fsummary>Get all non-flag command-line arguments.</fsummary> <desc> - <p>Returns any plain command line arguments as a list of strings + <p>Returns any plain command-line arguments as a list of strings (possibly empty).</p> </desc> </func> + <func> <name name="get_status" arity="0"/> - <fsummary>Get system status information</fsummary> + <fsummary>Get system status information.</fsummary> <type name="internal_status"/> <desc> <p>The current status of the <c>init</c> process can be inspected. During system startup (initialization), <c><anno>InternalStatus</anno></c> is <c>starting</c>, and - <c><anno>ProvidedStatus</anno></c> indicates how far the boot script has - been interpreted. Each <c>{progress, Info}</c> term - interpreted in the boot script affects <c><anno>ProvidedStatus</anno></c>, - that is, <c><anno>ProvidedStatus</anno></c> gets the value of <c>Info</c>.</p> + <c><anno>ProvidedStatus</anno></c> indicates how far the boot + script has been interpreted. Each <c>{progress, Info}</c> term + interpreted in the boot script affects + <c><anno>ProvidedStatus</anno></c>, that is, + <c><anno>ProvidedStatus</anno></c> gets the value of <c>Info</c>.</p> </desc> </func> + <func> <name name="reboot" arity="0"/> - <fsummary>Take down and restart an Erlang node smoothly</fsummary> + <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> + terminates. If command-line flag <c>-heart</c> was specified, + the <c>heart</c> program tries to reboot the system. For more + information, see + <seealso marker="kernel:heart"><c>kernel:heart(3)</c></seealso>.</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> + to spend taking down applications, command-line flag + <c>-shutdown_time</c> is to be used.</p> </desc> </func> + <func> <name name="restart" arity="0"/> - <fsummary>Restart the running Erlang node</fsummary> + <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 @@ -160,80 +172,91 @@ 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> + to spend taking down applications, command-line flag + <c>-shutdown_time</c> is to be used.</p> </desc> </func> + <func> <name name="script_id" arity="0"/> - <fsummary>Get the identity of the used boot script</fsummary> + <fsummary>Get the identity of the used boot script.</fsummary> <desc> - <p>Get the identity of the boot script used to boot the system. + <p>Gets the identity of the boot script used to boot the system. <c><anno>Id</anno></c> can be any Erlang term. In the delivered boot - scripts, <c><anno>Id</anno></c> is <c>{Name, Vsn}</c>. <c>Name</c> and - <c>Vsn</c> are strings.</p> + scripts, <c><anno>Id</anno></c> is <c>{Name, Vsn}</c>. <c>Name</c> + and <c>Vsn</c> are strings.</p> </desc> </func> + <func> <name name="stop" arity="0"/> - <fsummary>Take down an Erlang node smoothly</fsummary> + <fsummary>Take down an Erlang node smoothly.</fsummary> <desc> <p>The same as <seealso marker="#stop/1"><c>stop(0)</c></seealso>.</p> </desc> </func> + <func> <name name="stop" arity="1"/> - <fsummary>Take down an Erlang node smoothly</fsummary> + <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 by calling <c>halt(<anno>Status</anno>)</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> + terminates by calling <c>halt(<anno>Status</anno>)</c>. If + command-line flag <c>-heart</c> was specified, the <c>heart</c> + program is terminated before the Erlang node terminates. + For more information, see + <seealso marker="kernel:heart"><c>kernel:heart(3)</c></seealso>.</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> + to spend taking down applications, command-line flag + <c>-shutdown_time</c> is to 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> + <title>Command-Line Flags</title> + <warning> + <p>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 + <c>-code_path_choice</c> flag is also experimental.</p> + </warning> - <p>The <c>init</c> module interprets the following command line - flags:</p> + <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> + <seealso marker="#get_plain_arguments/0"> + <c>get_plain_arguments/0</c></seealso>.</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> - + <p>Can be set to <c>strict</c> or <c>relaxed</c>. It controls how each + directory in the code path is to be interpreted:</p> + <list type="bulleted"> + <item> + <p>Strictly as it appears in the <c>boot script</c>, or</p> + </item> + <item> + <p><c>init</c> is to be more relaxed and try to find a suitable + directory if it can choose from a regular <c>ebin</c> directory + and an <c>ebin</c> directory in an archive file.</p> + </item> + </list> + <p>This flag is particular + useful when you want to elaborate with code loading from + archives without editing the <c>boot script</c>. For more + information about interpretation of boot scripts, see + <seealso marker="sasl:script"><c>sasl:script(4)</c></seealso>. + The flag has also a similar effect on how the code server works; see + <seealso marker="kernel:code"><c>kernel:code(3)</c></seealso>.</p> </item> <tag><c>-epmd_module Module</c></tag> <item> @@ -242,11 +265,11 @@ </item> <tag><c>-eval Expr</c></tag> <item> - <p>Scans, parses and evaluates an arbitrary expression + <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 uses Erlang as a hexadecimal calculator:</p> + 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:</p> <pre> % <input>erl -noshell -eval 'R = 16#1F+16#A0, io:format("~.16B~n", [R])' \\</input> <input>-s erlang halt</input> @@ -256,14 +279,15 @@ BF</pre> <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 + 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> + <seealso marker="#get_plain_arguments/0"> + <c>get_plain_arguments/0</c></seealso>.</p> </item> <tag><c>-run Mod [Func [Arg1, Arg2, ...]]</c></tag> <item> @@ -285,8 +309,8 @@ 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 + the user. This means that a <c>-run</c> call that does not + return blocks 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> @@ -309,11 +333,11 @@ 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 + the user. This means that a <c>-s</c> call that does not + return blocks 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> + <p>Because of the limited length of atoms, it is recommended to + use <c>-run</c> instead.</p> </item> </taglist> </section> @@ -335,9 +359,9 @@ 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> + <title>See Also</title> + <p><seealso marker="erl_prim_loader"><c>erl_prim_loader(3)</c></seealso>, + <seealso marker="kernel:heart"><c>kernel:heart(3)</c></seealso></p> </section> </erlref> |