From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- erts/doc/src/init.xml | 384 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 384 insertions(+) create mode 100644 erts/doc/src/init.xml (limited to 'erts/doc/src/init.xml') 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 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + init + + + + + init.xml +
+ init + Coordination of System Startup + +

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(4) for more + information about boot scripts.

+

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

+ + + + boot(BootArgs) -> void() + Start the Erlang runtime system + + 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_args() -> [Arg] + Get all non-flag command line arguments + + Arg = atom() + + +

Returns any plain command line arguments as a list of atoms + (possibly empty). It is recommended that + get_plain_arguments/1 is used instead, because of + the limited length of atoms.

+ + + + get_argument(Flag) -> {ok, Arg} | error + Get the values associated with a command line user flag + + Flag = atom() + Arg = [Values] +  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 + Get all command line user flags + + Flags = [{Flag, Values}] +  Flag = atom() +  Values = [string()] + + +

Returns all command line flags, as well as the system + defined flags, see get_argument/1.

+ + + + get_plain_arguments() -> [Arg] + Get all non-flag command line arguments + + Arg = string() + + +

Returns any plain command line arguments as a list of strings + (possibly empty).

+ + + + get_status() -> {InternalStatus, ProvidedStatus} + Get system status information + + InternalStatus = starting | started | stopping + ProvidedStatus = term() + + +

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() -> void() + Take down and restart an Erlang node smoothly + +

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(3) 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() -> void() + Restart the running Erlang node + +

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 + Get the identity of the used boot script + + 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() -> void() + Take down an Erlang node smoothly + +

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(3) 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) -> void() + Take down an Erlang node smoothly + + Status = int()>=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(3) 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 +

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(4) for more information + about interpretation of boot scripts. The flag does also have + a similar affect on how the code server works. See code(3).

+ + + -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(3), + heart(3)

+
+ + -- cgit v1.2.3