The R13B03 release.OTP_R13B03

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>
+