code

MODULE

code

MODULE SUMMARY

Erlang Code Server

DESCRIPTION

This module deals with the loading of compiled and interpreted code into a running Erlang system.

The code server dynamically loads modules into the system on demand, which means the first time the module is referenced. This functionality can be turned off using the command line flag -mode embedded. In this mode, all code is loaded during system start-up.

If started in interactive mode, all directories under the $ROOT/lib directory are initially added to the search path of the code server (). The $ROOT directory is the installation directory of the Erlang system, code:root_dir(). Directories can be named Name[-Vsn] and the code server, by default, chooses the greatest (>) directory among those which have the same Name. The -Vsn suffix is optional.

If an ebin directory exists under a chosen directory, it is added to the directory. The Name of the directory (or library) can be used to find the full directory name (including the current version) through the priv_dir/1 and lib_dir/1 functions.

EXPORTS

start() -> {ok, Pid} | {error, What}
start(Flags) -> {ok, Pid} | {error, What}

Types:
Flags = [stick | nostick | embedded | interactive]
Pid = pid()
What = term()

This function starts the code server. start/0 implies that the stick and interactive flags are set.

Flags can also be entered as the command line flags -stick, -nostick and -mode embedded | interactive. -stick and -mode interactive are the defaults. The stick flag indicates that a module can never be re-loaded once it has been loaded from the kernel, stdlib, or compiler directories.

start_link() -> {ok, Pid} | {error, What}
start_link(Flags) -> {ok, Pid} | {error, What}

Types:
Flags = [stick | nostick | embedded | interactive]
Pid = pid()
What = term()

This function starts the code server and sets up a link to the calling process. This function should be used if the code server is supervised. start_link/0 implies that the stick and interactive flags are set.

The Flags can also be given as command line flags, -stick, -nostick and -mode embedded | interactive where -stick and -mode interactive is the default. The stick flag indicates that a module which has been loaded from the kernel, stdlib or compiler directories can never be reloaded.

set_path(DirList) -> true | {error, What}

Types:
DirList = [Dir]
Dir = string()
What = bad_directory | bad_path

Sets the code server search path to the list of directories DirList.

get_path() -> Path

Types:
Path = [Dir]
Dir = string()

Returns the current path.

add_path(Dir) -> true | {error, What}
add_pathz(Dir) -> true | {error, What}

Types:
Dir = string()
What = bad_directory

Adds Dir to the current path. The directory is added as the last directory in the new path. If Dir already exists in the path, it is not added.

add_patha(Dir) -> true | {error, What}

Types:
Dir = string()
What = bad_directory

This function adds Dir to the beginning of the current path. If Dir already exists, the old directory is removed from path.

add_paths(DirList) -> ok
add_pathsz(DirList) -> ok

Types:
DirList = [Dir]
Dir = string()

This function adds the directories in DirList to the end of the current path. If a Dir already exists in the path, it is not added. This function always returns ok, regardless of the validity of each individual Dir.

add_pathsa(DirList) -> ok

Types:
DirList = [Dir]
Dir = string()

Adds the directories in DirList to the beginning of the current path. If a Dir already exists, the old directory is removed from the path. This function always returns ok, regardless of the validity of each individual Dir.

del_path(NameDir) -> true | false | {error, What}

Types:
NameDir = Name | Dir
Name = atom()
Dir = string()
What = bad_name

This function deletes an old occurrence of a directory in the current path with the name .../Name[-*][/ebin]. It is also possible to give the complete directory name Dir in order to delete it.

This function returns true if the directory was deleted, and false if the directory was not found.

replace_path(Name, Dir) -> true | {error, What}

Types:
Name = atom()
Dir = string()
What = bad_name | bad_directory | {badarg, term()}

This function replaces an old occurrence of a directory named .../Name[-*][/ebin], in the current path, with Dir. If Name does not exist, it adds the new directory Dir last in path. The new directory must also be named .../Name[-*][/ebin]. This function should be used if a new version of the directory (library) is added to a running system.

load_file(Module) -> {module, Module} | {error, What}

Types:
Module = atom()
What = nofile | sticky_directory | badarg | term()

This function tries to load the Erlang module Module, using the current path. It looks for the object code file which has a suffix that corresponds to the Erlang machine used, for example Module.beam. The loading fails if the module name found in the object code differs from the name Module. load_binary/3 must be used to load object code with a module name that is different from the file name.

load_abs(File) -> {module, Module} | {error, What}

Types:
File = atom() | string()
Module = atom()
What = nofile | sticky_directory | badarg | term()

This function does the same as load_file(Module), but File is either an absolute file name, or a relative file name. The current path is not searched. It returns a value in the same way as load_file(Module). Note that File should not contain an extension (".beam"); load_abs/1 adds the correct extension itself.

ensure_loaded(Module) -> {module, Module} | {error, What} | {interpret, Module}

Types:
Module = atom()
What = nofile | sticky_directory | embedded | badarg | term()

This function tries to ensure that the module Module is loaded. To work correctly, a file with the same name as Module.Suffix must exist in the current search path. Suffix must correspond to the running Erlang machine, for example .beam. It returns a value in the same way as load_file(File), or {interpret, Module} if Module is interpreted.

If the system is started with the -mode embedded command line flag, this function will not load a module which has not already been loaded. {error, embedded} is returned.

delete(Module) -> true | false

Types:
Module = atom()

This function deletes the code in Module and the code in Module is marked as old. This means that no external function calls can be made to this occurrence of Module, but a process which executes code inside this module continues to do so. Returns true if the operation was successful (i.e., there was a current version of the module, but no old version), otherwise false.

purge(Module) -> true | false

Types:
Module = atom()

This function purges the code in Module, that is, it removes code marked as old. If some processes still execute code in the old occurrence of Module, these processes are killed before the module is purged. Returns true if a process has been killed, otherwise false.

soft_purge(Module) -> true | false

Types:
Module = atom()

This function purges the code in Module, that is, it removes code marked as old, but only if no process currently runs the old code. It returns false if a process uses the old code, otherwise true.

is_loaded(Module) -> {file, Loaded} | false

Types:
Module = atom()
Loaded = AbsFileName | preloaded | interpreted
AbsFileName = string()

This function tests if module Module is loaded. If the module is loaded, the absolute file name of the file from which the code was obtained is returned.

all_loaded() -> [LoadMod]

Types:
LoadMod = {Module, Loaded}
Module = atom()
Loaded = AbsFileName | preloaded | interpreted
AbsFileName = string()

This function returns a list of tuples of the type {Module, Loaded} for all loaded modules. Loaded is the absolute file name of the loaded module, the atom preloaded if the module was pre-loaded, or the atom interpreted if the module is interpreted.

load_binary(Module, File, Binary) -> {module, Module} | {error, What}

Types:
Module = atom()
What = sticky_directory | badarg | term()

This function can be used to load object code on remote Erlang nodes. It can also be used to load object code where the file name and module name differ. This, however, is a very unusual situation and should be used with care. The parameter Binary must contain object code for the module Module. The File parameter is only used by the code server to keep a record from which file the object code in Module comes. Accordingly, File is not opened and read by the code server.

stop() -> stopped

Stops the code server.

root_dir() -> RootDir

Types:
RootDir = string()

Returns the root directory of the Erlang system, which is the directory where the Erlang system is installed.

lib_dir() -> LibDir

Types:
LibDir = string()

Returns the library directory.

lib_dir(Name) -> LibDir | {error, What}

Types:
Name = atom()
LibDir = string()
What = bad_name

This function returns the current lib directory for the Name[-*] directory (or library). The current path is searched for a directory named .../Name-* (the -* suffix is optional for directories in the search path and it represents the version of the directory).

compiler_dir() -> CompDir

Types:
CompDir = string()

This function returns the compiler directory.

priv_dir(Name) -> PrivDir | {error, What}

Types:
Name = atom()
PrivDir = string()
What = bad_name

This function returns the current priv directory for the Name[-*] directory. The current path is searched for a directory named .../Name-* (the -* suffix is optional for directories in the search path and it represents the version of the directory). The /priv suffix is added to the end of the found directory.

get_object_code(Module) -> {Module, Bin, AbsFileName} | error

Types:
Module = atom()
Bin = binary()
AbsFileName = string()

This function searches the code path in the code server for the object code of the module Module. It returns {Mod, Bin, Filename} if successful, and error if not. Bin is a binary data object which contains the object code for the module. This can be useful if code is to be loaded on a remote node in a distributed system. For example, loading module Module on node N is done as follows:

...          
{Mod, B, F} = code:get_object_code(Mod),
rpc:call(N,code, load_binary, [Mod, F, B]),
...
        

objfile_extension() -> Ext

Types:
Ext = string()

This function returns the object code file extension for the running Erlang machine, for example ".beam".

stick_dir(Dir) -> ok | {error, term()}

Types:
Dir = string()

This function marks Dir as 'sticky'. The system issues a warning and rejects the request if a user tries to re-load a module in a sticky directory. Sticky directories are used to warn the user about inadvertent changes to system software.

unstick_dir(Dir) -> ok | {error, term()}

Types:
Dir = string()

This function unsticks a directory which has been marked sticky. Code which is located in the unstuck directory can be re-loaded into the system.

which(Module) -> WhichFile

Types:
Module = atom()
WhichFile = FileName | non_existing | preloaded | interpreted
FileName = string()

If the module is not loaded already, this function returns the directory path to the first file name in the search path of the code server which contains the object code for Module . If the module is loaded, it returns the directory path to the file name which contains the loaded object code. If the module is pre-loaded or interpreted, this is returned instead. non_existingis returned if the module cannot be found.

clash() -> ok

Searches the entire code space for module names with identical names and writes a report to stdout.

interpret(Module) -> {module, Module} | {error, What}

Types:
Module = atom()
What = no_interpreter | sticky_directory | badarg

Marks Module as being interpreted.

interpret_binary(Module, File, Binary) -> {module, Module} | {error, What}

Types:
Module = atom()
File = string()
Binary = binary()
What = no_interpreter | sticky_directory | badarg | term()

Loads the interpreted Module into the interpreter. The parameter Binary contains the abstract form (and the source code) of the module. The file File parameter locates the used source code file.

delete_interpret(Module) -> ok | {error, What}

Types:
Module = atom()
What = no_interpreter | badarg

Stops interpretation of Module.

interpreted() -> Modules

Types:
Modules = [Module]
Module = atom()

Returns a list of all modules which are being interpreted.

interpreted(Module) -> true | false

Types:
Module = atom()

Returns true if Module is being interpreted, otherwise false.

Notes

Dir has the described type string() in all functions. For backwards compatibility, atom() is also allowed, but string() is recommended.

The described type for Module is atom() in all functions. For backwards compatibility, string() is also allowed.

AUTHORS

Joe Armstrong - support@erlang.ericsson.se
Magnus Fröberg - support@erlang.ericsson.se
Robert Virding - support@erlang.ericsson.se
Claes Wikström - support@erlang.ericsson.se