From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- erts/doc/src/erl_prim_loader.xml | 251 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 251 insertions(+) create mode 100644 erts/doc/src/erl_prim_loader.xml (limited to 'erts/doc/src/erl_prim_loader.xml') 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 @@ + + + + +
+ + 19962009 + Ericsson AB. All Rights Reserved. + + + 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. + + + + erl_prim_loader + + + + + erl_prim_loader.xml +
+ erl_prim_loader + Low Level Erlang Loader + +

erl_prim_loader is used to load all Erlang modules into + the system. The start script is also fetched with this low level + loader.

+

erl_prim_loader 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).

+

The -loader Loader command line flag can be used to + choose the method used by the erl_prim_loader. Two + Loader methods are supported by the Erlang runtime system: + efile and inet. If another loader is required, then + it has to be implemented by the user. The Loader provided + by the user must fulfill the protocol defined below, and it is + started with the erl_prim_loader by evaluating + open_port({spawn,Loader},[binary]).

+ +

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 + list_dir/1 and read_file_info/1 as well as the flag + -loader_debug are also experimental

 + + + + + start(Id, Loader, Hosts) -> {ok, Pid} | {error, What} + Start the Erlang low level loader + + Id = term() + Loader = atom() | string() + Hosts = [Host] + Host = atom() + Pid = pid() + What = term() + + +

Starts the Erlang low level loader. This function is called + by the init process (and module). The init + process reads the command line flags -id Id, + -loader Loader, and -hosts Hosts. These are + the arguments supplied to the start/3 function.

+

If -loader is not given, the default loader is + efile which tells the system to read from the file + system.

+

If -loader is inet, the -id Id, + -hosts Hosts, and -setcookie Cookie flags must + also be supplied. Hosts identifies hosts which this + node can contact in order to load modules. One Erlang + runtime system with a erl_boot_server process must be + started on each of hosts given in Hosts in order to + answer the requests. See erl_boot_server(3).

+

If -loader is something else, the given port program + is started. The port program is supposed to follow + the protocol specified below.

+ + + + get_file(Filename) -> {ok, Bin, FullName} | error + Get a file + + Filename = string() + Bin = binary() + FullName = string() + + +

This function fetches a file using the low level loader. + Filename is either an absolute file name or just the name + of the file, for example "lists.beam". 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. + FullName is the complete name of the fetched file. + Bin is the contents of the file as a binary.

+ +

The Filename can also be a file in an archive. For example + /otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia_backup.beam + See code(3) about archive files.

+ + + + get_path() -> {ok, Path} + Get the path set in the loader + + Path = [Dir] + Dir = string() + + +

This function gets the path set in the loader. The path is + set by the init process according to information found + in the start script.

+ + + + list_dir(Dir) -> {ok, Filenames} | error + List files in a directory + + Dir = name() + Filenames = [Filename] + Filename = string() + + +

Lists all the files in a directory. Returns + {ok, Filenames} if successful. Otherwise, it returns + error. Filenames is a list of + the names of all the files in the directory. The names are + not sorted.

+

The Dir can also be a directory in an archive. For example + /otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin + See code(3) about archive files.

+ + + + read_file_info(Filename) -> {ok, FileInfo} | error + Get information about a file + + Filename = name() + FileInfo = #file_info{} + + +

Retrieves information about a file. Returns + {ok, FileInfo} if successful, otherwise + error. FileInfo is a record + file_info, defined in the Kernel include file + file.hrl. Include the following directive in the module + from which the function is called:

+ +-include_lib("kernel/include/file.hrl"). +

See file(3) for more info about + the record file_info.

+

The Filename can also be a file in an archive. For example + /otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia_backup.beam + See code(3) about archive files.

+ + + + set_path(Path) -> ok + Set the path of the loader + + Path = [Dir] + Dir = string() + + +

This function sets the path of the loader if init + interprets a path command in the start script.

+ + + + +
+ Protocol +

The following protocol must be followed if a user provided + loader port program is used. The Loader port program is + started with the command + open_port({spawn,Loader},[binary]). The protocol is as + follows:

+ 
+Function          Send               Receive
+-------------------------------------------------------------
+get_file          [102 | FileName]   [121 | BinaryFile] (on success)
+                                     [122]              (failure)
+
+stop              eof                terminate
+
+ +
+ Command Line Flags +

The erl_prim_loader module interprets the following + command line flags:

+ + -loader Loader + +

Specifies the name of the loader used by + erl_prim_loader. Loader can be efile + (use the local file system), or inet (load using + the boot_server on another Erlang node). If + Loader is user defined, the defined Loader port + program is started.

+

If the -loader flag is omitted, it defaults to + efile.

+ + -loader_debug + +

Makes the efile loader write some debug information, + such as the reason for failures, while it handles files.

+ + -hosts Hosts + +

Specifies which other Erlang nodes the inet loader + can use. This flag is mandatory if the -loader inet + flag is present. On each host, there must be on Erlang node + with the erl_boot_server which handles the load + requests. Hosts is a list of IP addresses (hostnames + are not acceptable).

+ + -id Id + +

Specifies the identity of the Erlang runtime system. If + the system runs as a distributed node, Id must be + identical to the name supplied with the -sname or + -name distribution flags.

+ + -setcookie Cookie + +

Specifies the cookie of the Erlang runtime system. This flag + is mandatory if the -loader inet flag is present.

+ + +
+ +
+ SEE ALSO +

init(3), + erl_boot_server(3)

+
+ + -- cgit v1.2.3