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

DATA TYPES

22       mode() = embedded | interactive
23
24              Code loading mode.
25

EXPORTS

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

COMMAND-LINE FLAGS

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

EXAMPLE

286       % erl -- a b -children thomas claire -ages 7 3 -- x y
287
288       1> init:get_plain_arguments().
289       ["a","b","x","y"]
290       2> init:get_argument(children).
291       {ok,[["thomas","claire"]]}
292       3> init:get_argument(ages).
293       {ok, [["7","3"]]}
294       4> init:get_argument(silly).
295       error
296

SEE ALSO

298       erl_prim_loader(3), heart(3)
299
300
301
302Ericsson AB                      erts 13.2.2.4                         init(3)
Impressum