diff options
Diffstat (limited to 'erts/doc/src/erl_prim_loader.xml')
| -rw-r--r-- | erts/doc/src/erl_prim_loader.xml | 251 |
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> + |