1init(3)                    Erlang Module Definition                    init(3)
2
3
4

NAME

6       init - Coordination of system startup.
7

DESCRIPTION

9       This  module  is  preloaded  and  contains the code for the init system
10       process that coordinates the startup of the system. The first  function
11       evaluated  at  startup  is  boot(BootArgs), where BootArgs is a list of
12       command-line arguments supplied to the Erlang runtime system  from  the
13       local operating system; see erl(1).
14
15       init  reads the boot script, which contains instructions on how to ini‐
16       tiate  the  system.  For  more  information  about  boot  scripts,  see
17       script(4).
18
19       init also contains functions to restart, reboot, and stop the system.
20

EXPORTS

22       boot(BootArgs) -> no_return()
23
24              Types:
25
26                 BootArgs = [binary()]
27
28              Starts  the  Erlang runtime system. This function is called when
29              the emulator is started and coordinates system startup.
30
31              BootArgs are all  command-line  arguments  except  the  emulator
32              flags, that is, flags and plain arguments; see erl(1).
33
34              init  interprets  some  of  the  flags, see section Command-Line
35              Flags below. The remaining flags ("user flags") and plain  argu‐
36              ments  are passed to the init loop and can be retrieved by call‐
37              ing get_arguments/0 and get_plain_arguments/0, respectively.
38
39       get_argument(Flag) -> {ok, Arg} | error
40
41              Types:
42
43                 Flag = atom()
44                 Arg = [Values :: [string()]]
45
46              Returns all values associated with the  command-line  user  flag
47              Flag. If Flag is provided several times, each Values is returned
48              in preserved order. Example:
49
50              % erl -a b c -a d
51              1> init:get_argument(a).
52              {ok,[["b","c"],["d"]]}
53
54              The  following  flags  are  defined  automatically  and  can  be
55              retrieved using this function:
56
57                root:
58                  The installation directory of Erlang/OTP, $ROOT:
59
60                2> init:get_argument(root).
61                {ok,[["/usr/local/otp/releases/otp_beam_solaris8_r10b_patched"]]}
62
63                progname:
64                  The name of the program which started Erlang:
65
66                3> init:get_argument(progname).
67                {ok,[["erl"]]}
68
69                home:
70                  The home directory:
71
72                4> init:get_argument(home).
73                {ok,[["/home/harry"]]}
74
75              Returns error if no value is associated with Flag.
76
77       get_arguments() -> Flags
78
79              Types:
80
81                 Flags = [{Flag :: atom(), Values :: [string()]}]
82
83              Returns all command-line flags and the system-defined flags, see
84              get_argument/1.
85
86       get_plain_arguments() -> [Arg]
87
88              Types:
89
90                 Arg = string()
91
92              Returns any plain command-line arguments as a  list  of  strings
93              (possibly empty).
94
95       get_status() -> {InternalStatus, ProvidedStatus}
96
97              Types:
98
99                 InternalStatus = internal_status()
100                 ProvidedStatus = term()
101                 internal_status() = starting | started | stopping
102
103              The  current status of the init process can be inspected. During
104              system startup (initialization), InternalStatus is starting, and
105              ProvidedStatus indicates how far the boot script has been inter‐
106              preted. Each {progress,  Info}  term  interpreted  in  the  boot
107              script  affects ProvidedStatus, that is, ProvidedStatus gets the
108              value of Info.
109
110       reboot() -> ok
111
112              All applications are taken down smoothly, all code is  unloaded,
113              and  all  ports are closed before the system terminates. If com‐
114              mand-line flag -heart was specified, the heart program tries  to
115              reboot the system. For more information, see heart(3).
116
117              To  limit  the  shutdown time, the time init is allowed to spend
118              taking down applications, command-line flag -shutdown_time is to
119              be used.
120
121       restart() -> ok
122
123              The  system  is  restarted inside the running Erlang node, which
124              means that the emulator is not restarted. All  applications  are
125              taken  down  smoothly,  all  code is unloaded, and all ports are
126              closed before the system is booted again in the same way as ini‐
127              tially started. The same BootArgs are used again.
128
129              To  limit  the  shutdown time, the time init is allowed to spend
130              taking down applications, command-line flag -shutdown_time is to
131              be used.
132
133       script_id() -> Id
134
135              Types:
136
137                 Id = term()
138
139              Gets the identity of the boot script used to boot the system. Id
140              can be any Erlang term. In the delivered  boot  scripts,  Id  is
141              {Name, Vsn}. Name and Vsn are strings.
142
143       stop() -> ok
144
145              The same as stop(0).
146
147       stop(Status) -> ok
148
149              Types:
150
151                 Status = integer() >= 0 | string()
152
153              All  applications are taken down smoothly, all code is unloaded,
154              and all ports are closed before the system terminates by calling
155              halt(Status).  If  command-line  flag  -heart was specified, the
156              heart program is terminated before the Erlang  node  terminates.
157              For more information, see heart(3).
158
159              To  limit  the  shutdown time, the time init is allowed to spend
160              taking down applications, command-line flag -shutdown_time is to
161              be used.
162

COMMAND-LINE FLAGS

164   Warning:
165       The support for loading of code from archive files is experimental. The
166       only purpose of releasing it before it is  ready  is  to  obtain  early
167       feedback.  The  file  format,  semantics, interfaces, and so on, can be
168       changed in a future release. The -code_path_choice flag is also experi‐
169       mental.
170
171
172       The init module interprets the following command-line flags:
173
174         --:
175           Everything  following  --  up  to the next flag is considered plain
176           arguments and can be retrieved using get_plain_arguments/0.
177
178         -code_path_choice Choice:
179           Can be set to strict or relaxed. It controls how each directory  in
180           the code path is to be interpreted:
181
182           * Strictly as it appears in the boot script, or
183
184           * init  is  to be more relaxed and try to find a suitable directory
185             if it can choose from a regular ebin directory and an ebin direc‐
186             tory in an archive file.
187
188           This flag is particular useful when you want to elaborate with code
189           loading from archives without editing the  boot  script.  For  more
190           information  about  interpretation  of boot scripts, see script(4).
191           The flag has also a similar effect on how the  code  server  works;
192           see code(3).
193
194         -epmd_module Module:
195           Specifies  the  module  to  use for registration and lookup of node
196           names. Defaults to erl_epmd.
197
198         -eval Expr:
199           Scans, parses, and evaluates an arbitrary  expression  Expr  during
200           system  initialization.  If  any of these steps fail (syntax error,
201           parse error, or exception during evaluation), Erlang stops with  an
202           error  message.  In the following example Erlang is used as a hexa‐
203           decimal calculator:
204
205         % erl -noshell -eval 'R = 16#1F+16#A0, io:format("~.16B~n", [R])' \\
206         -s erlang halt
207         BF
208
209           If multiple -eval expressions are  specified,  they  are  evaluated
210           sequentially  in  the order specified. -eval expressions are evalu‐
211           ated sequentially with -s and -run function calls (this also in the
212           order  specified). As with -s and -run, an evaluation that does not
213           terminate blocks the system initialization process.
214
215         -extra:
216           Everything following -extra is considered plain arguments  and  can
217           be retrieved using get_plain_arguments/0.
218
219         -run Mod [Func [Arg1, Arg2, ...]]:
220           Evaluates the specified function call during system initialization.
221           Func defaults to start. If no arguments are provided, the  function
222           is assumed to be of arity 0. Otherwise it is assumed to be of arity
223           1, taking the list [Arg1,Arg2,...] as argument. All  arguments  are
224           passed  as strings. If an exception is raised, Erlang stops with an
225           error message.
226
227           Example:
228
229         % erl -run foo -run foo bar -run foo bar baz 1 2
230
231           This starts the Erlang runtime system and evaluates  the  following
232           functions:
233
234         foo:start()
235         foo:bar()
236         foo:bar(["baz", "1", "2"]).
237
238           The  functions  are  executed  sequentially  in  an  initialization
239           process, which then terminates normally and passes control  to  the
240           user.  This means that a -run call that does not return blocks fur‐
241           ther processing; to avoid this, use some variant of spawn  in  such
242           cases.
243
244         -s Mod [Func [Arg1, Arg2, ...]]:
245           Evaluates the specified function call during system initialization.
246           Func defaults to start. If no arguments are provided, the  function
247           is assumed to be of arity 0. Otherwise it is assumed to be of arity
248           1, taking the list [Arg1,Arg2,...] as argument. All  arguments  are
249           passed  as  atoms.  If an exception is raised, Erlang stops with an
250           error message.
251
252           Example:
253
254         % erl -s foo -s foo bar -s foo bar baz 1 2
255
256           This starts the Erlang runtime system and evaluates  the  following
257           functions:
258
259         foo:start()
260         foo:bar()
261         foo:bar([baz, '1', '2']).
262
263           The  functions  are  executed  sequentially  in  an  initialization
264           process, which then terminates normally and passes control  to  the
265           user. This means that a -s call that does not return blocks further
266           processing; to avoid this, use some variant of spawn in such cases.
267
268           Because of the limited length of atoms, it is  recommended  to  use
269           -run instead.
270

EXAMPLE

272       % erl -- a b -children thomas claire -ages 7 3 -- x y
273
274       1> init:get_plain_arguments().
275       ["a","b","x","y"]
276       2> init:get_argument(children).
277       {ok,[["thomas","claire"]]}
278       3> init:get_argument(ages).
279       {ok, [["7","3"]]}
280       4> init:get_argument(silly).
281       error
282

SEE ALSO

284       erl_prim_loader(3), heart(3)
285
286
287
288Ericsson AB                       erts 10.5.6                          init(3)
Impressum