aboutsummaryrefslogtreecommitdiffstats
path: root/erts/doc/src/erl_prim_loader.xml
diff options
context:
space:
mode:
Diffstat (limited to 'erts/doc/src/erl_prim_loader.xml')
-rw-r--r--erts/doc/src/erl_prim_loader.xml251
1 files changed, 251 insertions, 0 deletions
diff --git a/erts/doc/src/erl_prim_loader.xml b/erts/doc/src/erl_prim_loader.xml
new file mode 100644
index 0000000000..ccaa9b725f
--- /dev/null
+++ b/erts/doc/src/erl_prim_loader.xml
@@ -0,0 +1,251 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1996</year><year>2009</year>
+ <holder>Ericsson AB. All Rights Reserved.</holder>
+ </copyright>
+ <legalnotice>
+ 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.
+
+ </legalnotice>
+
+ <title>erl_prim_loader</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ <file>erl_prim_loader.xml</file>
+ </header>
+ <module>erl_prim_loader</module>
+ <modulesummary>Low Level Erlang Loader</modulesummary>
+ <description>
+ <p><c>erl_prim_loader</c> is used to load all Erlang modules into
+ the system. The start script is also fetched with this low level
+ loader.</p>
+ <p><c>erl_prim_loader</c> knows about the environment and how to
+ fetch modules. The loader could, for example, fetch files using
+ the file system (with absolute file names as input), or a
+ database (where the binary format of a module is stored).</p>
+ <p>The <c>-loader Loader</c> command line flag can be used to
+ choose the method used by the <c>erl_prim_loader</c>. Two
+ <c>Loader</c> methods are supported by the Erlang runtime system:
+ <c>efile</c> and <c>inet</c>. If another loader is required, then
+ it has to be implemented by the user. The <c>Loader</c> provided
+ by the user must fulfill the protocol defined below, and it is
+ started with the <c>erl_prim_loader</c> by evaluating
+ <c>open_port({spawn,Loader},[binary])</c>.</p>
+
+ <warning><p>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 functions
+ <c>list_dir/1</c> and <c>read_file_info/1</c> as well as the flag
+ <c>-loader_debug</c> are also experimental</p></warning>
+
+ </description>
+ <funcs>
+ <func>
+ <name>start(Id, Loader, Hosts) -> {ok, Pid} | {error, What}</name>
+ <fsummary>Start the Erlang low level loader</fsummary>
+ <type>
+ <v>Id = term()</v>
+ <v>Loader = atom() | string()</v>
+ <v>Hosts = [Host]</v>
+ <v>Host = atom()</v>
+ <v>Pid = pid()</v>
+ <v>What = term()</v>
+ </type>
+ <desc>
+ <p>Starts the Erlang low level loader. This function is called
+ by the <c>init</c> process (and module). The <c>init</c>
+ process reads the command line flags <c>-id Id</c>,
+ <c>-loader Loader</c>, and <c>-hosts Hosts</c>. These are
+ the arguments supplied to the <c>start/3</c> function.</p>
+ <p>If <c>-loader</c> is not given, the default loader is
+ <c>efile</c> which tells the system to read from the file
+ system.</p>
+ <p>If <c>-loader</c> is <c>inet</c>, the <c>-id Id</c>,
+ <c>-hosts Hosts</c>, and <c>-setcookie Cookie</c> flags must
+ also be supplied. <c>Hosts</c> identifies hosts which this
+ node can contact in order to load modules. One Erlang
+ runtime system with a <c>erl_boot_server</c> process must be
+ started on each of hosts given in <c>Hosts</c> in order to
+ answer the requests. See <seealso
+ marker="kernel:erl_boot_server">erl_boot_server(3)</seealso>.</p>
+ <p>If <c>-loader</c> is something else, the given port program
+ is started. The port program is supposed to follow
+ the protocol specified below.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_file(Filename) -> {ok, Bin, FullName} | error</name>
+ <fsummary>Get a file</fsummary>
+ <type>
+ <v>Filename = string()</v>
+ <v>Bin = binary()</v>
+ <v>FullName = string()</v>
+ </type>
+ <desc>
+ <p>This function fetches a file using the low level loader.
+ <c>Filename</c> is either an absolute file name or just the name
+ of the file, for example <c>"lists.beam"</c>. If an internal
+ path is set to the loader, this path is used to find the file.
+ If a user supplied loader is used, the path can be stripped
+ off if it is obsolete, and the loader does not use a path.
+ <c>FullName</c> is the complete name of the fetched file.
+ <c>Bin</c> is the contents of the file as a binary.</p>
+
+ <p>The <c>Filename</c> can also be a file in an archive. For example
+ <c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia_backup.beam</c>
+ See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p>
+ </desc>
+ </func>
+ <func>
+ <name>get_path() -> {ok, Path}</name>
+ <fsummary>Get the path set in the loader</fsummary>
+ <type>
+ <v>Path = [Dir]</v>
+ <v>Dir = string()</v>
+ </type>
+ <desc>
+ <p>This function gets the path set in the loader. The path is
+ set by the <c>init</c> process according to information found
+ in the start script.</p>
+ </desc>
+ </func>
+ <func>
+ <name>list_dir(Dir) -> {ok, Filenames} | error</name>
+ <fsummary>List files in a directory</fsummary>
+ <type>
+ <v>Dir = name()</v>
+ <v>Filenames = [Filename]</v>
+ <v>Filename = string()</v>
+ </type>
+ <desc>
+ <p>Lists all the files in a directory. Returns
+ <c>{ok, Filenames}</c> if successful. Otherwise, it returns
+ <c>error</c>. <c>Filenames</c> is a list of
+ the names of all the files in the directory. The names are
+ not sorted.</p>
+ <p>The <c>Dir</c> can also be a directory in an archive. For example
+ <c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin</c>
+ See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p>
+ </desc>
+ </func>
+ <func>
+ <name>read_file_info(Filename) -> {ok, FileInfo} | error</name>
+ <fsummary>Get information about a file</fsummary>
+ <type>
+ <v>Filename = name()</v>
+ <v>FileInfo = #file_info{}</v>
+ </type>
+ <desc>
+ <p>Retrieves information about a file. Returns
+ <c>{ok, FileInfo}</c> if successful, otherwise
+ <c>error</c>. <c>FileInfo</c> is a record
+ <c>file_info</c>, defined in the Kernel include file
+ <c>file.hrl</c>. Include the following directive in the module
+ from which the function is called:</p>
+ <code type="none">
+-include_lib("kernel/include/file.hrl").</code>
+ <p>See <seealso marker="kernel:file">file(3)</seealso> for more info about
+ the record <c>file_info</c>.</p>
+ <p>The <c>Filename</c> can also be a file in an archive. For example
+ <c>/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia_backup.beam</c>
+ See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p>
+ </desc>
+ </func>
+ <func>
+ <name>set_path(Path) -> ok</name>
+ <fsummary>Set the path of the loader</fsummary>
+ <type>
+ <v>Path = [Dir]</v>
+ <v>Dir = string()</v>
+ </type>
+ <desc>
+ <p>This function sets the path of the loader if <c>init</c>
+ interprets a <c>path</c> command in the start script.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>Protocol</title>
+ <p>The following protocol must be followed if a user provided
+ loader port program is used. The <c>Loader</c> port program is
+ started with the command
+ <c>open_port({spawn,Loader},[binary])</c>. The protocol is as
+ follows:</p>
+ <pre>
+Function Send Receive
+-------------------------------------------------------------
+get_file [102 | FileName] [121 | BinaryFile] (on success)
+ [122] (failure)
+
+stop eof terminate</pre>
+ </section>
+
+ <section>
+ <title>Command Line Flags</title>
+ <p>The <c>erl_prim_loader</c> module interprets the following
+ command line flags:</p>
+ <taglist>
+ <tag><c>-loader Loader</c></tag>
+ <item>
+ <p>Specifies the name of the loader used by
+ <c>erl_prim_loader</c>. <c>Loader</c> can be <c>efile</c>
+ (use the local file system), or <c>inet</c> (load using
+ the <c>boot_server</c> on another Erlang node). If
+ <c>Loader</c> is user defined, the defined <c>Loader</c> port
+ program is started.</p>
+ <p>If the <c>-loader</c> flag is omitted, it defaults to
+ <c>efile</c>.</p>
+ </item>
+ <tag><c>-loader_debug</c></tag>
+ <item>
+ <p>Makes the <c>efile</c> loader write some debug information,
+ such as the reason for failures, while it handles files.</p>
+ </item>
+ <tag><c>-hosts Hosts</c></tag>
+ <item>
+ <p>Specifies which other Erlang nodes the <c>inet</c> loader
+ can use. This flag is mandatory if the <c>-loader inet</c>
+ flag is present. On each host, there must be on Erlang node
+ with the <c>erl_boot_server</c> which handles the load
+ requests. <c>Hosts</c> is a list of IP addresses (hostnames
+ are not acceptable).</p>
+ </item>
+ <tag><c>-id Id</c></tag>
+ <item>
+ <p>Specifies the identity of the Erlang runtime system. If
+ the system runs as a distributed node, <c>Id</c> must be
+ identical to the name supplied with the <c>-sname</c> or
+ <c>-name</c> distribution flags.</p>
+ </item>
+ <tag><c>-setcookie Cookie</c></tag>
+ <item>
+ <p>Specifies the cookie of the Erlang runtime system. This flag
+ is mandatory if the <c>-loader inet</c> flag is present.</p>
+ </item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>SEE ALSO</title>
+ <p><seealso marker="init">init(3)</seealso>,
+ <seealso marker="kernel:erl_boot_server">erl_boot_server(3)</seealso></p>
+ </section>
+</erlref>
+