.TH erl_prim_loader 3erl "erts 6.2" "Ericsson AB" "Erlang Module Definition"
.SH NAME
erl_prim_loader \- Low Level Erlang Loader
.SH DESCRIPTION
.LP
\fIerl_prim_loader\fR\& is used to load all Erlang modules into the system\&. The start script is also fetched with this low level loader\&.
.LP
\fIerl_prim_loader\fR\& 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)\&.
.LP
The \fI-loader Loader\fR\& command line flag can be used to choose the method used by the \fIerl_prim_loader\fR\&\&. Two \fILoader\fR\& methods are supported by the Erlang runtime system: \fIefile\fR\& and \fIinet\fR\&\&. If another loader is required, then it has to be implemented by the user\&. The \fILoader\fR\& provided by the user must fulfill the protocol defined below, and it is started with the \fIerl_prim_loader\fR\& by evaluating \fIopen_port({spawn,Loader},[binary])\fR\&\&.
.LP

.RS -4
.B
Warning:
.RE
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 \fIlist_dir/1\fR\& and \fIread_file_info/1\fR\& as well as the flag \fI-loader_debug\fR\& are also experimental

.SH DATA TYPES
.nf

\fBhost()\fR\& = atom()
.br
.fi
.SH EXPORTS
.LP
.nf

.B
start(Id, Loader, Hosts) -> {ok, Pid} | {error, What}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Id = term()
.br
Loader = atom() | string()
.br
Hosts = Host | [Host]
.br
Host = \fBhost()\fR\&
.br
Pid = pid()
.br
What = term()
.br
.RE
.RE
.RS
.LP
Starts the Erlang low level loader\&. This function is called by the \fIinit\fR\& process (and module)\&. The \fIinit\fR\& process reads the command line flags \fI-id Id\fR\&, \fI-loader Loader\fR\&, and \fI-hosts Hosts\fR\&\&. These are the arguments supplied to the \fIstart/3\fR\& function\&.
.LP
If \fI-loader\fR\& is not given, the default loader is \fIefile\fR\& which tells the system to read from the file system\&.
.LP
If \fI-loader\fR\& is \fIinet\fR\&, the \fI-id Id\fR\&, \fI-hosts Hosts\fR\&, and \fI-setcookie Cookie\fR\& flags must also be supplied\&. \fIHosts\fR\& identifies hosts which this node can contact in order to load modules\&. One Erlang runtime system with a \fIerl_boot_server\fR\& process must be started on each of hosts given in \fIHosts\fR\& in order to answer the requests\&. See \fBerl_boot_server(3erl)\fR\&\&.
.LP
If \fI-loader\fR\& is something else, the given port program is started\&. The port program is supposed to follow the protocol specified below\&.
.RE

.LP
.nf

.B
get_file(Filename) -> {ok, Bin, FullName} | error
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Filename = atom() | string()
.br
Bin = binary()
.br
FullName = string()
.br
.RE
.RE
.RS
.LP
This function fetches a file using the low level loader\&. \fIFilename\fR\& is either an absolute file name or just the name of the file, for example \fI"lists\&.beam"\fR\&\&. 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\&. \fIFullName\fR\& is the complete name of the fetched file\&. \fIBin\fR\& is the contents of the file as a binary\&.
.LP
The \fIFilename\fR\& can also be a file in an archive\&. For example \fI$OTPROOT/lib/\fR\&\fImnesia-4\&.4\&.7\&.ez/mnesia-4\&.4\&.7/ebin/\fR\&\fImnesia\&.beam\fR\&\&. See \fBcode(3erl)\fR\& about archive files\&.
.RE

.LP
.nf

.B
get_path() -> {ok, Path}
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Path = [Dir :: string()]
.br
.RE
.RE
.RS
.LP
This function gets the path set in the loader\&. The path is set by the \fIinit\fR\& process according to information found in the start script\&.
.RE

.LP
.nf

.B
list_dir(Dir) -> {ok, Filenames} | error
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Dir = string()
.br
Filenames = [Filename :: string()]
.br
.RE
.RE
.RS
.LP
Lists all the files in a directory\&. Returns \fI{ok, Filenames}\fR\& if successful\&. Otherwise, it returns \fIerror\fR\&\&. \fIFilenames\fR\& is a list of the names of all the files in the directory\&. The names are not sorted\&.
.LP
The \fIDir\fR\& can also be a directory in an archive\&. For example \fI$OTPROOT/lib/\fR\&\fImnesia-4\&.4\&.7\&.ez/mnesia-4\&.4\&.7/ebin\fR\&\&. See \fBcode(3erl)\fR\& about archive files\&.
.RE

.LP
.nf

.B
read_file_info(Filename) -> {ok, FileInfo} | error
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Filename = string()
.br
FileInfo = \fBfile:file_info()\fR\&
.br
.RE
.RE
.RS
.LP
Retrieves information about a file\&. Returns \fI{ok, FileInfo}\fR\& if successful, otherwise \fIerror\fR\&\&. \fIFileInfo\fR\& is a record \fIfile_info\fR\&, defined in the Kernel include file \fIfile\&.hrl\fR\&\&. Include the following directive in the module from which the function is called:
.LP
.nf

-include_lib("kernel/include/file.hrl").
.fi
.LP
See \fBfile(3erl)\fR\& for more info about the record \fIfile_info\fR\&\&.
.LP
The \fIFilename\fR\& can also be a file in an archive\&. For example \fI$OTPROOT/lib/\fR\&\fImnesia-4\&.4\&.7\&.ez/mnesia-4\&.4\&.7/ebin/\fR\&\fImnesia\fR\&\&. See \fBcode(3erl)\fR\& about archive files\&.
.RE

.LP
.nf

.B
read_link_info(Filename) -> {ok, FileInfo} | error
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Filename = string()
.br
FileInfo = \fBfile:file_info()\fR\&
.br
.RE
.RE
.RS
.LP
This function works like \fBread_file_info/1\fR\& except that if \fIFilename\fR\& is a symbolic link, information about the link will be returned in the \fIfile_info\fR\& record and the \fItype\fR\& field of the record will be set to \fIsymlink\fR\&\&.
.LP
If \fIFilename\fR\& is not a symbolic link, this function returns exactly the same result as \fIread_file_info/1\fR\&\&. On platforms that do not support symbolic links, this function is always equivalent to \fIread_file_info/1\fR\&\&.
.RE

.LP
.nf

.B
set_path(Path) -> ok
.br
.fi
.br
.RS
.LP
Types:

.RS 3
Path = [Dir :: string()]
.br
.RE
.RE
.RS
.LP
This function sets the path of the loader if \fIinit\fR\& interprets a \fIpath\fR\& command in the start script\&.
.RE

.SH "PROTOCOL"

.LP
The following protocol must be followed if a user provided loader port program is used\&. The \fILoader\fR\& port program is started with the command \fIopen_port({spawn,Loader},[binary])\fR\&\&. The protocol is as follows:
.LP
.nf

Function          Send               Receive
-------------------------------------------------------------
get_file          [102 | FileName]   [121 | BinaryFile] (on success)
                                     [122]              (failure)

stop              eof                terminate
.fi
.SH "COMMAND LINE FLAGS"

.LP
The \fIerl_prim_loader\fR\& module interprets the following command line flags:
.RS 2
.TP 2
.B
\fI-loader Loader\fR\&:
Specifies the name of the loader used by \fIerl_prim_loader\fR\&\&. \fILoader\fR\& can be \fIefile\fR\& (use the local file system), or \fIinet\fR\& (load using the \fIboot_server\fR\& on another Erlang node)\&. If \fILoader\fR\& is user defined, the defined \fILoader\fR\& port program is started\&.
.RS 2
.LP
If the \fI-loader\fR\& flag is omitted, it defaults to \fIefile\fR\&\&.
.RE

.TP 2
.B
\fI-loader_debug\fR\&:
Makes the \fIefile\fR\& loader write some debug information, such as the reason for failures, while it handles files\&.
.TP 2
.B
\fI-hosts Hosts\fR\&:
Specifies which other Erlang nodes the \fIinet\fR\& loader can use\&. This flag is mandatory if the \fI-loader inet\fR\& flag is present\&. On each host, there must be on Erlang node with the \fIerl_boot_server\fR\& which handles the load requests\&. \fIHosts\fR\& is a list of IP addresses (hostnames are not acceptable)\&.
.TP 2
.B
\fI-id Id\fR\&:
Specifies the identity of the Erlang runtime system\&. If the system runs as a distributed node, \fIId\fR\& must be identical to the name supplied with the \fI-sname\fR\& or \fI-name\fR\& distribution flags\&.
.TP 2
.B
\fI-setcookie Cookie\fR\&:
Specifies the cookie of the Erlang runtime system\&. This flag is mandatory if the \fI-loader inet\fR\& flag is present\&.
.RE
.SH "SEE ALSO"

.LP
\fBinit(3erl)\fR\&, \fBerl_boot_server(3erl)\fR\&