diff options
Diffstat (limited to 'erts/doc/src/erl_prim_loader.xml')
-rw-r--r-- | erts/doc/src/erl_prim_loader.xml | 213 |
1 files changed, 88 insertions, 125 deletions
diff --git a/erts/doc/src/erl_prim_loader.xml b/erts/doc/src/erl_prim_loader.xml index 6751deda4d..286bac6c93 100644 --- a/erts/doc/src/erl_prim_loader.xml +++ b/erts/doc/src/erl_prim_loader.xml @@ -4,20 +4,21 @@ <erlref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2016</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. + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. </legalnotice> @@ -29,108 +30,70 @@ <file>erl_prim_loader.xml</file> </header> <module>erl_prim_loader</module> - <modulesummary>Low Level Erlang Loader</modulesummary> + <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 + <p>This module 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> + <p><c>erl_prim_loader</c> knows about the environment and how to + fetch modules.</p> + <p>Command-line flag <c>-loader Loader</c> can be used to + choose the method used by <c>erl_prim_loader</c>. Two + <c>Loader</c> methods are supported by the Erlang runtime system: + <c>efile</c> and <c>inet</c>.</p> </description> - <datatypes> - <datatype> - <name name="host"/> - </datatype> - </datatypes> <funcs> <func> - <name name="start" arity="3"/> - <fsummary>Start the Erlang low level loader</fsummary> - <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 <anno>Id</anno></c>, - <c>-loader <anno>Loader</anno></c>, and <c>-hosts <anno>Hosts</anno></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 <anno>Id</anno></c>, - <c>-hosts <anno>Hosts</anno></c>, and <c>-setcookie Cookie</c> flags must - also be supplied. <c><anno>Hosts</anno></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><anno>Hosts</anno></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 name="get_file" arity="1"/> - <fsummary>Get a file</fsummary> + <fsummary>Get a file.</fsummary> <desc> - <p>This function fetches a file using the low level loader. - <c><anno>Filename</anno></c> is either an absolute file name or just the name - of the file, for example <c>"lists.beam"</c>. If an internal + <p>Fetches a file using the low-level loader. + <c><anno>Filename</anno></c> is either an absolute filename or only + 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><anno>FullName</anno></c> is the complete name of the fetched file. <c><anno>Bin</anno></c> is the contents of the file as a binary.</p> - - <p>The <c><anno>Filename</anno></c> can also be a file in an archive. For example + <p><c><anno>Filename</anno></c> can also be a file in an archive, + for example, <c>$OTPROOT/lib/</c><c>mnesia-4.4.7.ez/mnesia-4.4.7/ebin/</c><c>mnesia.beam</c>. - See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p> + For information about archive files, see + <seealso marker="kernel:code"><c>code(3)</c></seealso>.</p> </desc> </func> + <func> <name name="get_path" arity="0"/> - <fsummary>Get the path set in the loader</fsummary> + <fsummary>Get the path set in the loader.</fsummary> <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> + <p>Gets the path set in the loader. The path is + set by the <seealso marker="init"><c>init(3)</c></seealso> + process according to information found in the start script.</p> </desc> </func> + <func> <name name="list_dir" arity="1"/> - <fsummary>List files in a directory</fsummary> + <fsummary>List files in a directory.</fsummary> <desc> <p>Lists all the files in a directory. Returns - <c>{ok, <anno>Filenames</anno>}</c> if successful. Otherwise, it returns + <c>{ok, <anno>Filenames</anno>}</c> if successful, otherwise <c>error</c>. <c><anno>Filenames</anno></c> is a list of the names of all the files in the directory. The names are not sorted.</p> - <p>The <c><anno>Dir</anno></c> can also be a directory in an archive. For example + <p><c><anno>Dir</anno></c> can also be a directory in an archive, + for example, <c>$OTPROOT/lib/</c><c>mnesia-4.4.7.ez/mnesia-4.4.7/ebin</c>. - See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p> + For information about archive files, see + <seealso marker="kernel:code"><c>code(3)</c></seealso>.</p> </desc> </func> + <func> <name name="read_file_info" arity="1"/> - <fsummary>Get information about a file</fsummary> + <fsummary>Get information about a file.</fsummary> <desc> <p>Retrieves information about a file. Returns <c>{ok, <anno>FileInfo</anno>}</c> if successful, otherwise @@ -140,88 +103,88 @@ 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><anno>Filename</anno></c> can also be a file in an archive. For example + <p>For more information about the record <c>file_info</c>, see + <seealso marker="kernel:file"><c>file(3)</c></seealso>.</p> + <p><c><anno>Filename</anno></c> can also be a file in an archive, + for example, <c>$OTPROOT/lib/</c><c>mnesia-4.4.7.ez/mnesia-4.4.7/ebin/</c><c>mnesia</c>. - See <seealso marker="kernel:code">code(3)</seealso> about archive files.</p> + For information about archive files, see + <seealso marker="kernel:code"><c>code(3)</c></seealso>.</p> </desc> </func> + + <func> + <name name="read_link_info" arity="1"/> + <fsummary>Get information about a link or file.</fsummary> + <desc> + <p>Works like + <seealso marker="#read_file_info/1"><c>read_file_info/1</c></seealso> + except that if <c><anno>Filename</anno></c> is a symbolic link, + information about the link is returned in the <c>file_info</c> + record and the <c>type</c> field of the record is set to + <c>symlink</c>.</p> + <p>If <c><anno>Filename</anno></c> is not a symbolic link, this function + returns exactly the same result as <c>read_file_info/1</c>. + On platforms that do not support symbolic links, this function + is always equivalent to <c>read_file_info/1</c>.</p> + </desc> + </func> + <func> <name name="set_path" arity="1"/> - <fsummary>Set the path of the loader</fsummary> + <fsummary>Set the path of the loader.</fsummary> <desc> - <p>This function sets the path of the loader if <c>init</c> + <p>Sets the path of the loader if + <seealso marker="init"><c>init(3)</c></seealso> 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> + <title>Command-Line Flags</title> <p>The <c>erl_prim_loader</c> module interprets the following - command line flags:</p> + 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 + (use the local file system) or <c>inet</c> (load using + the <c>boot_server</c> on another Erlang node).</p> + <p>If flag <c>-loader</c> 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> + 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 + can use. This flag is mandatory if flag <c>-loader inet</c> + is present. On each host, there must be on Erlang node + with the <seealso marker="kernel:erl_boot_server"> + <c>erl_boot_server(3)</c></seealso>, + 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> + is mandatory if flag <c>-loader inet</c> 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> + <title>See Also</title> + <p><seealso marker="init"><c>init(3)</c></seealso>, + <seealso marker="kernel:erl_boot_server"> + <c>erl_boot_server(3)</c></seealso></p> </section> </erlref> |