1
<?xml version="1.0" encoding="latin1" ?>
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
7
<year>1996</year><year>2009</year>
8
<holder>Ericsson AB. All Rights Reserved.</holder>
11
The contents of this file are subject to the Erlang Public License,
12
Version 1.1, (the "License"); you may not use this file except in
13
compliance with the License. You should have received a copy of the
14
Erlang Public License along with this software. If not, it can be
15
retrieved online at http://www.erlang.org/.
17
Software distributed under the License is distributed on an "AS IS"
18
basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
19
the License for the specific language governing rights and limitations
24
<title>erl_prim_loader</title>
30
<module>erl_prim_loader</module>
31
<modulesummary>Low Level Erlang Loader</modulesummary>
33
<p><c>erl_prim_loader</c> is used to load all Erlang modules into
34
the system. The start script is also fetched with this low level
36
<p><c>erl_prim_loader</c> knows about the environment and how to
37
fetch modules. The loader could, for example, fetch files using
38
the file system (with absolute file names as input), or a
39
database (where the binary format of a module is stored).</p>
40
<p>The <c>-loader Loader</c> command line flag can be used to
41
choose the method used by the <c>erl_prim_loader</c>. Two
42
<c>Loader</c> methods are supported by the Erlang runtime system:
43
<c>efile</c> and <c>inet</c>. If another loader is required, then
44
it has to be implemented by the user. The <c>Loader</c> provided
45
by the user must fulfill the protocol defined below, and it is
46
started with the <c>erl_prim_loader</c> by evaluating
47
<c>open_port({spawn,Loader},[binary])</c>.</p>
49
<warning><p>The support for loading of code from archive files is
50
experimental. The sole purpose of releasing it before it is ready
51
is to obtain early feedback. The file format, semantics,
52
interfaces etc. may be changed in a future release. The functions
53
<c>list_dir/1</c> and <c>read_file_info/1</c> as well as the flag
54
<c>-loader_debug</c> are also experimental</p></warning>
59
<name>start(Id, Loader, Hosts) -> {ok, Pid} | {error, What}</name>
60
<fsummary>Start the Erlang low level loader</fsummary>
63
<v>Loader = atom() | string()</v>
70
<p>Starts the Erlang low level loader. This function is called
71
by the <c>init</c> process (and module). The <c>init</c>
72
process reads the command line flags <c>-id Id</c>,
73
<c>-loader Loader</c>, and <c>-hosts Hosts</c>. These are
74
the arguments supplied to the <c>start/3</c> function.</p>
75
<p>If <c>-loader</c> is not given, the default loader is
76
<c>efile</c> which tells the system to read from the file
78
<p>If <c>-loader</c> is <c>inet</c>, the <c>-id Id</c>,
79
<c>-hosts Hosts</c>, and <c>-setcookie Cookie</c> flags must
80
also be supplied. <c>Hosts</c> identifies hosts which this
81
node can contact in order to load modules. One Erlang
82
runtime system with a <c>erl_boot_server</c> process must be
83
started on each of hosts given in <c>Hosts</c> in order to
84
answer the requests. See <seealso
85
marker="kernel:erl_boot_server">erl_boot_server(3)</seealso>.</p>
86
<p>If <c>-loader</c> is something else, the given port program
87
is started. The port program is supposed to follow
88
the protocol specified below.</p>
92
<name>get_file(Filename) -> {ok, Bin, FullName} | error</name>
93
<fsummary>Get a file</fsummary>
95
<v>Filename = string()</v>
97
<v>FullName = string()</v>
100
<p>This function fetches a file using the low level loader.
101
<c>Filename</c> is either an absolute file name or just the name
102
of the file, for example <c>"lists.beam"</c>. If an internal
103
path is set to the loader, this path is used to find the file.
104
If a user supplied loader is used, the path can be stripped
105
off if it is obsolete, and the loader does not use a path.
106
<c>FullName</c> is the complete name of the fetched file.
107
<c>Bin</c> is the contents of the file as a binary.</p>
109
<p>The <c>Filename</c> can also be a file in an archive. For example
110
<c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia_backup.beam</c>
111
See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p>
115
<name>get_path() -> {ok, Path}</name>
116
<fsummary>Get the path set in the loader</fsummary>
119
<v>Dir = string()</v>
122
<p>This function gets the path set in the loader. The path is
123
set by the <c>init</c> process according to information found
124
in the start script.</p>
128
<name>list_dir(Dir) -> {ok, Filenames} | error</name>
129
<fsummary>List files in a directory</fsummary>
132
<v>Filenames = [Filename]</v>
133
<v>Filename = string()</v>
136
<p>Lists all the files in a directory. Returns
137
<c>{ok, Filenames}</c> if successful. Otherwise, it returns
138
<c>error</c>. <c>Filenames</c> is a list of
139
the names of all the files in the directory. The names are
141
<p>The <c>Dir</c> can also be a directory in an archive. For example
142
<c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin</c>
143
See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p>
147
<name>read_file_info(Filename) -> {ok, FileInfo} | error</name>
148
<fsummary>Get information about a file</fsummary>
150
<v>Filename = name()</v>
151
<v>FileInfo = #file_info{}</v>
154
<p>Retrieves information about a file. Returns
155
<c>{ok, FileInfo}</c> if successful, otherwise
156
<c>error</c>. <c>FileInfo</c> is a record
157
<c>file_info</c>, defined in the Kernel include file
158
<c>file.hrl</c>. Include the following directive in the module
159
from which the function is called:</p>
161
-include_lib("kernel/include/file.hrl").</code>
162
<p>See <seealso marker="kernel:file">file(3)</seealso> for more info about
163
the record <c>file_info</c>.</p>
164
<p>The <c>Filename</c> can also be a file in an archive. For example
165
<c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia_backup.beam</c>
166
See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p>
170
<name>set_path(Path) -> ok</name>
171
<fsummary>Set the path of the loader</fsummary>
174
<v>Dir = string()</v>
177
<p>This function sets the path of the loader if <c>init</c>
178
interprets a <c>path</c> command in the start script.</p>
184
<title>Protocol</title>
185
<p>The following protocol must be followed if a user provided
186
loader port program is used. The <c>Loader</c> port program is
187
started with the command
188
<c>open_port({spawn,Loader},[binary])</c>. The protocol is as
191
Function Send Receive
192
-------------------------------------------------------------
193
get_file [102 | FileName] [121 | BinaryFile] (on success)
196
stop eof terminate</pre>
200
<title>Command Line Flags</title>
201
<p>The <c>erl_prim_loader</c> module interprets the following
202
command line flags:</p>
204
<tag><c>-loader Loader</c></tag>
206
<p>Specifies the name of the loader used by
207
<c>erl_prim_loader</c>. <c>Loader</c> can be <c>efile</c>
208
(use the local file system), or <c>inet</c> (load using
209
the <c>boot_server</c> on another Erlang node). If
210
<c>Loader</c> is user defined, the defined <c>Loader</c> port
211
program is started.</p>
212
<p>If the <c>-loader</c> flag is omitted, it defaults to
215
<tag><c>-loader_debug</c></tag>
217
<p>Makes the <c>efile</c> loader write some debug information,
218
such as the reason for failures, while it handles files.</p>
220
<tag><c>-hosts Hosts</c></tag>
222
<p>Specifies which other Erlang nodes the <c>inet</c> loader
223
can use. This flag is mandatory if the <c>-loader inet</c>
224
flag is present. On each host, there must be on Erlang node
225
with the <c>erl_boot_server</c> which handles the load
226
requests. <c>Hosts</c> is a list of IP addresses (hostnames
227
are not acceptable).</p>
229
<tag><c>-id Id</c></tag>
231
<p>Specifies the identity of the Erlang runtime system. If
232
the system runs as a distributed node, <c>Id</c> must be
233
identical to the name supplied with the <c>-sname</c> or
234
<c>-name</c> distribution flags.</p>
236
<tag><c>-setcookie Cookie</c></tag>
238
<p>Specifies the cookie of the Erlang runtime system. This flag
239
is mandatory if the <c>-loader inet</c> flag is present.</p>
245
<title>SEE ALSO</title>
246
<p><seealso marker="init">init(3)</seealso>,
247
<seealso marker="kernel:erl_boot_server">erl_boot_server(3)</seealso></p>
added
removed
erts/doc/src/erl_prim_loader.xml
