← Back to branch summary

~rdoering/ubuntu/karmic/erlang/fix-535090

« back to all changes in this revision

Viewing changes to lib/kernel/doc/src/erl_prim_loader.xml

  • Committer: Bazaar Package Importer
  • Author(s): Sergei Golovan
  • Date: 2009-02-15 16:42:52 UTC
  • mfrom: (3.1.2 squeeze)
  • Revision ID: james.westby@ubuntu.com-20090215164252-q5x4rcf8a5pbesb1
Tags: 1:12.b.5-dfsg-2
Upload to unstable after lenny is released.

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/kernel/doc/src/erl_prim_loader.xml
 
1
<?xml version="1.0" encoding="latin1" ?>
 
2
<!DOCTYPE erlref SYSTEM "erlref.dtd">
 
3
 
 
4
<erlref>
 
5
  <header>
 
6
    <copyright>
 
7
      <year>1996</year>
 
8
      <year>2007</year>
 
9
      <holder>Ericsson AB, All Rights Reserved</holder>
 
10
    </copyright>
 
11
    <legalnotice>
 
12
  The contents of this file are subject to the Erlang Public License,
 
13
  Version 1.1, (the "License"); you may not use this file except in
 
14
  compliance with the License. You should have received a copy of the
 
15
  Erlang Public License along with this software. If not, it can be
 
16
  retrieved online at http://www.erlang.org/.
 
17
 
 
18
  Software distributed under the License is distributed on an "AS IS"
 
19
  basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 
20
  the License for the specific language governing rights and limitations
 
21
  under the License.
 
22
 
 
23
  The Initial Developer of the Original Code is Ericsson AB.
 
24
    </legalnotice>
 
25
 
 
26
    <title>erl_prim_loader</title>
 
27
    <prepared></prepared>
 
28
    <docno></docno>
 
29
    <date></date>
 
30
    <rev></rev>
 
31
  </header>
 
32
  <module>erl_prim_loader</module>
 
33
  <modulesummary>Low Level Erlang Loader</modulesummary>
 
34
  <description>
 
35
    <p><c>erl_prim_loader</c> is used to load all Erlang modules into
 
36
      the system. The start script is also fetched with this low level
 
37
      loader.</p>
 
38
    <p><c>erl_prim_loader</c> knows about the environment and how to
 
39
      fetch modules. The loader could, for example, fetch files using
 
40
      the file system (with absolute file names as input), or a
 
41
      database (where the binary format of a module is stored).</p>
 
42
    <p>The <c>-loader Loader</c> command line flag can be used to
 
43
      choose the method used by the <c>erl_prim_loader</c>. Two
 
44
      <c>Loader</c> methods are supported by the Erlang runtime system:
 
45
      <c>efile</c> and <c>inet</c>. If another loader is required, then
 
46
      it has to be implemented by the user. The <c>Loader</c> provided
 
47
      by the user must fulfill the protocol defined below, and it is
 
48
      started with the <c>erl_prim_loader</c> by evaluating
 
49
      <c>open_port({spawn,Loader},[binary])</c>.</p>
 
50
 
 
51
    <warning><p>The support for loading of code from archive files is
 
52
     experimental. The sole purpose of releasing it before it is ready
 
53
     is to obtain early feedback. The file format, semantics,
 
54
     interfaces etc. may be changed in a future release. The functions
 
55
     <c>list_dir/1</c> and <c>read_file_info/1</c> as well as the flag
 
56
     <c>-loader_debug</c> are also experimental</p></warning>
 
57
 
 
58
  </description>
 
59
  <funcs>
 
60
    <func>
 
61
      <name>start(Id, Loader, Hosts) -> {ok, Pid} | {error, What}</name>
 
62
      <fsummary>Start the Erlang low level loader</fsummary>
 
63
      <type>
 
64
        <v>Id = term()</v>
 
65
        <v>Loader = atom() | string()</v>
 
66
        <v>Hosts = [Host]</v>
 
67
        <v>Host = atom()</v>
 
68
        <v>Pid = pid()</v>
 
69
        <v>What = term()</v>
 
70
      </type>
 
71
      <desc>
 
72
        <p>Starts the Erlang low level loader. This function is called
 
73
          by the <c>init</c> process (and module). The <c>init</c>
 
74
          process reads the command line flags <c>-id Id</c>,
 
75
          <c>-loader Loader</c>, and <c>-hosts Hosts</c>. These are
 
76
          the arguments supplied to the <c>start/3</c> function.</p>
 
77
        <p>If <c>-loader</c> is not given, the default loader is
 
78
          <c>efile</c> which tells the system to read from the file
 
79
          system.</p>
 
80
        <p>If <c>-loader</c> is <c>inet</c>, the <c>-id Id</c>,
 
81
          <c>-hosts Hosts</c>, and <c>-setcookie Cookie</c> flags must
 
82
          also be supplied. <c>Hosts</c> identifies hosts which this
 
83
          node can contact in order to load modules. One Erlang
 
84
          runtime system with a <c>erl_boot_server</c> process must be
 
85
          started on each of hosts given in <c>Hosts</c> in order to
 
86
          answer the requests. See <seealso
 
87
          marker="erl_boot_server">erl_boot_server(3)</seealso>.</p>
 
88
        <p>If <c>-loader</c> is something else, the given port program
 
89
          is started. The port program is supposed to follow
 
90
          the protocol specified below.</p>
 
91
      </desc>
 
92
    </func>
 
93
    <func>
 
94
      <name>get_file(Filename) -> {ok, Bin, FullName} | error</name>
 
95
      <fsummary>Get a file</fsummary>
 
96
      <type>
 
97
        <v>Filename = string()</v>
 
98
        <v>Bin = binary()</v>
 
99
        <v>FullName = string()</v>
 
100
      </type>
 
101
      <desc>
 
102
        <p>This function fetches a file using the low level loader.
 
103
          <c>Filename</c> is either an absolute file name or just the name
 
104
          of the file, for example <c>"lists.beam"</c>. If an internal
 
105
          path is set to the loader, this path is used to find the file.
 
106
          If a user supplied loader is used, the path can be stripped
 
107
          off if it is obsolete, and the loader does not use a path.
 
108
          <c>FullName</c> is the complete name of the fetched file.
 
109
          <c>Bin</c> is the contents of the file as a binary.</p>
 
110
 
 
111
          <p>The <c>Filename</c> can also be a file in an archive. For example
 
112
          <c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia_backup.beam</c>
 
113
          See <seealso marker="code">code(3)</seealso> about archive files.</p>
 
114
      </desc>
 
115
    </func>
 
116
    <func>
 
117
      <name>get_path() -> {ok, Path}</name>
 
118
      <fsummary>Get the path set in the loader</fsummary>
 
119
      <type>
 
120
        <v>Path = [Dir]</v>
 
121
        <v>Dir = string()</v>
 
122
      </type>
 
123
      <desc>
 
124
        <p>This function gets the path set in the loader. The path is
 
125
          set by the <c>init</c> process according to information found
 
126
          in the start script.</p>
 
127
      </desc>
 
128
    </func>
 
129
    <func>
 
130
      <name>list_dir(Dir) -> {ok, Filenames} | error</name>
 
131
      <fsummary>List files in a directory</fsummary>
 
132
      <type>
 
133
        <v>Dir = name()</v>
 
134
        <v>Filenames = [Filename]</v>
 
135
        <v>Filename = string()</v>
 
136
      </type>
 
137
      <desc>
 
138
        <p>Lists all the files in a directory. Returns
 
139
          <c>{ok, Filenames}</c> if successful. Otherwise, it returns
 
140
          <c>error</c>. <c>Filenames</c> is a list of
 
141
          the names of all the files in the directory. The names are
 
142
          not sorted.</p>
 
143
          <p>The <c>Dir</c> can also be a directory in an archive. For example
 
144
          <c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin</c>
 
145
           See <seealso marker="code">code(3)</seealso> about archive files.</p>
 
146
      </desc>
 
147
    </func>
 
148
    <func>
 
149
      <name>read_file_info(Filename) -> {ok, FileInfo} | error</name>
 
150
      <fsummary>Get information about a file</fsummary>
 
151
      <type>
 
152
        <v>Filename = name()</v>
 
153
        <v>FileInfo = #file_info{}</v>
 
154
      </type>
 
155
      <desc>
 
156
        <p>Retrieves information about a file. Returns
 
157
          <c>{ok, FileInfo}</c> if successful, otherwise
 
158
          <c>error</c>. <c>FileInfo</c> is a record
 
159
          <c>file_info</c>, defined in the Kernel include file
 
160
          <c>file.hrl</c>. Include the following directive in the module
 
161
          from which the function is called:</p>
 
162
        <code type="none">
 
163
-include_lib("kernel/include/file.hrl").</code>
 
164
        <p>See <seealso marker="file">file(3)</seealso> for more info about
 
165
          the record <c>file_info</c>.</p>
 
166
        <p>The <c>Filename</c> can also be a file in an archive. For example
 
167
          <c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia_backup.beam</c>
 
168
          See <seealso marker="code">code(3)</seealso> about archive files.</p>
 
169
      </desc>
 
170
    </func>
 
171
    <func>
 
172
      <name>set_path(Path) -> ok</name>
 
173
      <fsummary>Set the path of the loader</fsummary>
 
174
      <type>
 
175
        <v>Path = [Dir]</v>
 
176
        <v>Dir = string()</v>
 
177
      </type>
 
178
      <desc>
 
179
        <p>This function sets the path of the loader if <c>init</c>
 
180
          interprets a <c>path</c> command in the start script.</p>
 
181
      </desc>
 
182
    </func>
 
183
  </funcs>
 
184
 
 
185
  <section>
 
186
    <title>Protocol</title>
 
187
    <p>The following protocol must be followed if a user provided
 
188
      loader port program is used. The <c>Loader</c> port program is
 
189
      started with the command
 
190
      <c>open_port({spawn,Loader},[binary])</c>. The protocol is as
 
191
      follows:</p>
 
192
    <pre>
 
193
Function          Send               Receive
 
194
-------------------------------------------------------------
 
195
get_file          [102 | FileName]   [121 | BinaryFile] (on success)
 
196
                                     [122]              (failure)
 
197
 
 
198
stop              eof                terminate</pre>
 
199
  </section>
 
200
 
 
201
  <section>
 
202
    <title>Command Line Flags</title>
 
203
    <p>The <c>erl_prim_loader</c> module interprets the following
 
204
      command line flags:</p>
 
205
    <taglist>
 
206
      <tag><c>-loader Loader</c></tag>
 
207
      <item>
 
208
        <p>Specifies the name of the loader used by
 
209
          <c>erl_prim_loader</c>. <c>Loader</c> can be <c>efile</c>
 
210
          (use the local file system), or <c>inet</c> (load using
 
211
          the <c>boot_server</c> on another Erlang node). If
 
212
          <c>Loader</c> is user defined, the defined <c>Loader</c> port
 
213
          program is started.</p>
 
214
        <p>If the <c>-loader</c> flag is omitted, it defaults to
 
215
          <c>efile</c>.</p>
 
216
      </item>
 
217
      <tag><c>-loader_debug</c></tag>
 
218
      <item>
 
219
          <p>Makes the <c>efile</c> loader write some debug information,
 
220
           such as the reason for failures, while it handles files.</p>
 
221
      </item>
 
222
      <tag><c>-hosts Hosts</c></tag>
 
223
      <item>
 
224
        <p>Specifies which other Erlang nodes the <c>inet</c> loader
 
225
          can use. This flag is mandatory if the <c>-loader inet</c>
 
226
          flag is present. On each host, there must be on Erlang node
 
227
          with the <c>erl_boot_server</c> which handles the load
 
228
          requests. <c>Hosts</c> is a list of IP addresses (hostnames
 
229
          are not acceptable).</p>
 
230
      </item>
 
231
      <tag><c>-id Id</c></tag>
 
232
      <item>
 
233
        <p>Specifies the identity of the Erlang runtime system. If
 
234
          the system runs as a distributed node, <c>Id</c> must be
 
235
          identical to the name supplied with the <c>-sname</c> or
 
236
          <c>-name</c> distribution flags.</p>
 
237
      </item>
 
238
      <tag><c>-setcookie Cookie</c></tag>
 
239
      <item>
 
240
        <p>Specifies the cookie of the Erlang runtime system. This flag
 
241
          is mandatory if the <c>-loader inet</c> flag is present.</p>
 
242
      </item>
 
243
    </taglist>
 
244
  </section>
 
245
 
 
246
  <section>
 
247
    <title>SEE ALSO</title>
 
248
    <p><seealso marker="init">init(3)</seealso>, 
 
249
      <seealso marker="erl_boot_server">erl_boot_server(3)</seealso></p>
 
250
  </section>
 
251
</erlref>
 
252