Provided by: erlang-manpages_16.b.3-dfsg-1ubuntu2_all bug

NAME

       erl_prim_loader - Low Level Erlang Loader

DESCRIPTION

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

   Warning:
       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

DATA TYPES

       host() = atom()

EXPORTS

       start(Id, Loader, Hosts) -> {ok, Pid} | {error, What}

              Types:

                 Id = term()
                 Loader = atom() | string()
                 Hosts = Host | [Host]
                 Host = host()
                 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(3erl).

              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

              Types:

                 Filename = atom() | 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
              $OTPROOT/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia.beam.  See  code(3erl)  about
              archive files.

       get_path() -> {ok, Path}

              Types:

                 Path = [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

              Types:

                 Dir = string()
                 Filenames = [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
              $OTPROOT/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin. See code(3erl) about archive files.

       read_file_info(Filename) -> {ok, FileInfo} | error

              Types:

                 Filename = string()
                 FileInfo = file: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(3erl) for more info about the record file_info.

              The   Filename   can   also   be   a   file   in   an    archive.    For    example
              $OTPROOT/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin/mnesia. See code(3erl) about archive
              files.

       set_path(Path) -> ok

              Types:

                 Path = [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(3erl), erl_boot_server(3erl)