![[Ericsson AB]](min_head.gif)
This module contains the interface to the Erlang code server, which deals with the loading of compiled code into a running Erlang runtime system.
The runtime system can be started in either embedded or
interactive mode. Which one is decided by the command
line flag -mode.
% erl -mode interactive
Default mode is interactive.
To prevent accidently reloading modules affecting the Erlang
runtime system itself, the kernel, stdlib and
compiler directories are considered sticky. This
means that the system issues a warning and rejects the request if
a user tries to reload a module residing in any of them.
The feature can be disabled by using the command line flag
-nostick.
In interactive mode, the code server maintains a search path -- usually called the code path -- consisting of a list of directories, which it searches sequentially when trying to load a module.
Initially, the code path consists of the current working
directory and all Erlang object code directories under the library
directory $ROOT/lib, where $ROOT is the installation
directory of Erlang/OTP, code:root_dir(). Directories can
be named Name[-Vsn] and the code server, by default,
chooses the directory with the highest version number among those
which have the same Name. The -Vsn suffix is
optional. If an ebin directory exists under
Name[-Vsn], it is this directory which is added to
the code path.
The code server incorporates a code path cache. The cache
functionality is disabled by default. To activate it, start
the emulator with the command line flag -code_path_cache
or call code:rehash(). When the cache is created (or
updated), the code server searches for modules in the code path
directories. This may take some time if the the code path is long.
After the cache creation, the time for loading modules in a large
system (one with a large directory structure) is significantly
reduced compared to having the cache disabled. The code server
is able to look up the location of a module from the cache in
constant time instead of having to search through the code path
directories.
Application resource files (.app files) are also stored
in the code path cache. This feature is used by the application
controller (see
application(3)) to load
applications efficiently in large systems.
Note that when the code path cache is created (or updated), any relative directory names in the code path are converted to absolute.
The code of a module can exists in two variants in a system: current code and old code. When a module is loaded into the system for the first time, the code of the module becomes 'current' and the global export table is updated with references to all functions exported from the module.
If then a new instance of the module is loaded (perhaps because of the correction of an error), then the code of the previous instance becomes 'old', and all export entries referring to the previous instance are removed. After that the new instance is loaded as if it was loaded for the first time, as described above, and becomes 'current'.
Both old and current code for a module are valid, and may even be evaluated concurrently. The difference is that exported functions in old code are unavailable. Hence there is no way to make a global call to an exported function in old code, but old code may still be evaluated because of processes lingering in it.
If a third instance of the module is loaded, the code server will remove (purge) the old code and any processes lingering in it will be terminated. Then the third instance becomes 'current' and the previously current code becomes 'old'.
For more information about old and current code, and how to make a process switch from old to current code, refer to Erlang Reference Manual.
set_path(Path) -> true | {error, What}
Types:
Path = [Dir]
Dir = string()
What = bad_directory | bad_path
Sets the code path to the list of directories Path.
Returns true if successful, or
{error, bad_directory} if any Dir is not
the name of a directory, or {error, bad_path} if
the argument is invalid.
Types:
Path = [Dir]
Dir = string()
Returns the code path
add_path(Dir) -> true | {error, What}
add_pathz(Dir) -> true | {error, What}
Types:
Dir = string()
What = bad_directory
Adds Dir to the code path. The directory is added as
the last directory in the new path. If Dir already
exists in the path, it is not added.
Returns true if successful, or
{error, bad_directory} if Dir is not the name
of a directory.
add_patha(Dir) -> true | {error, What}
Types:
Dir = string()
What = bad_directory
Adds Dir to the beginning of the code path. If
Dir already exists, it is removed from the old
position in the code path.
Returns true if successful, or
{error, bad_directory} if Dir is not the name
of a directory.
add_paths(Dirs) -> ok
add_pathsz(Dirs) -> ok
Types:
Dirs = [Dir]
Dir = string()
Adds the directories in Dirs to the end of the code
path. If a Dir already exists, it is not added. This
function always returns ok, regardless of the validity
of each individual Dir.
Types:
Dirs = [Dir]
Dir = string()
Adds the directories in Dirs to the beginning of
the code path. If a Dir already exists, it is removed
from the old position in the code path. This function always
returns ok, regardless of the validity of each
individual Dir.
del_path(Name | Dir) -> true | false | {error, What}
Types:
Name = atom()
Dir = string()
What = bad_name
Deletes a directory from the code path. The argument can be
an atom Name, in which case the directory with
the name .../Name[-Vsn][/ebin] is deleted from the code
path. It is also possible to give the complete directory name
Dir as argument.
Returns true if successful, or false if
the directory is not found, or {error, bad_name} if
the argument is invalid.
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[-Vsn][/ebin], in the code path, with
Dir. If Name does not exist, it adds the new
directory Dir last in the code path. The new directory
must also be named .../Name[-Vsn][/ebin]. This function
should be used if a new version of the directory (library) is
added to a running system.
Returns true if successful, or
{error, bad_name} if Name is not found, or
{error, bad_directory} if Dir does not exist, or
{error, {badarg, [Name, Dir]}} if Name or
Dir is invalid.
load_file(Module) -> {module, Module} | {error, What}
Types:
Module = atom()
What = nofile | sticky_directory | badarg | term()
Tries to load the Erlang module Module, using
the code path. It looks for the object code file with an
extension 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.
Returns {module, Module} if successful, or
{error, nofile} if no object code is found, or
{error, sticky_directory} if the object code resides in
a sticky directory, or {error, badarg} if the argument
is invalid. Also if the loading fails, an error tuple is
returned. See
erlang:load_module/2
for possible values of What.
load_abs(Filename) -> {module, Module} | {error, What}
Types:
Filename = string()
Module = atom()
What = nofile | sticky_directory | badarg | term()
Does the same as load_file(Module), but
Filename is either an absolute file name, or a
relative file name. The code path is not searched. It returns
a value in the same way as
load_file/1. Note
that Filename should not contain the extension (for
example ".beam"); load_abs/1 adds the correct
extension itself.
ensure_loaded(Module) -> {module, Module} | {error, What}
Types:
Module = atom()
What = nofile | sticky_directory | embedded | badarg | term()
Tries to to load a module in the same way as
load_file/1. In
embedded mode, however, it does not load a module which is not
already loaded, but returns {error, embedded} instead.
load_binary(Module, Filename, Binary) -> {module, Module}
| {error, What}
Types:
Module = atom()
Filename = string()
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 not recommended. The parameter
Binary must contain object code for Module.
Filename is only used by the code server to keep a
record of from which file the object code for Module
comes. Accordingly, Filename is not opened and read by
the code server.
Returns {module, Module} if successful, or
{error, sticky_directory} if the object code resides in
a sticky directory, or {error, badarg} if any argument
is invalid. Also if the loading fails, an error tuple is
returned. See
erlang:load_module/2
for possible values of What.
delete(Module) -> true | false
Types:
Module = atom()
Removes the current code for Module, that is,
the current code for Module is made old. This means
that processes can continue to execute the code in the module,
but that no external function calls can be made to it.
Returns true if successful, or false if there
is old code for Module which must be purged first, or
if Module is not a (loaded) module.
Types:
Module = atom()
Purges the code for Module, that is, removes code
marked as old. If some processes still linger in the old code,
these processes are killed before the code is removed.
Returns true if successful and any process needed to
be killed, otherwise false.
soft_purge(Module) -> true | false
Types:
Module = atom()
Purges the code for Module, that is, removes code
marked as old, but only if no processes linger in it.
Returns false if the module could not be purged due
to processes lingering in old code, otherwise true.
is_loaded(Module) -> {file, Loaded} | false
Types:
Module = atom()
Loaded = Absname | preloaded | cover_compiled
Absname = string()
Checks if Module is loaded. If it is,
{file, Loaded} is returned, otherwise false.
Normally, Loaded is the absolute file name
Absname from which the code was obtained. If the module
is preloaded (see
script(4)),
Loaded==preloaded. If the module is Cover compiled (see
cover(3)),
Loaded==cover_compiled.
all_loaded() -> [{Module, Loaded}]
Types:
Module = atom()
Loaded = Absname | preloaded | cover_compiled
Absname = string()
Returns a list of tuples {Module, Loaded} for all
loaded modules. Loaded is normally the absolute file
name, as described for
is_loaded/1.
Types:
Module = atom()
Which = Filename | non_existing | preloaded | cover_compiled
Filename = string()
If the module is not loaded, this function searches the code
path for the first file which contains object code for
Module and returns the absolute file name. If
the module is loaded, it returns the name of the file which
contained the loaded object code. If the module is pre-loaded,
preloaded is returned. If the module is Cover compiled,
cover_compiled is returned. non_existing is
returned if the module cannot be found.
get_object_code(Module) -> {Module, Binary, Filename}
| error
Types:
Module = atom()
Binary = binary()
Filename = string()
Searches the code path for the object code of the module
Module. It returns {Module, Binary, Filename}
if successful, and error if not. Binary 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 a node Node is done as
follows:
...
{_Module, Binary, Filename} = code:get_object_code(Module),
rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
...
Types:
RootDir = string()
Returns the root directory of Erlang/OTP, which is the directory where it is installed.
Types:
LibDir = string()
Returns the library directory, $ROOT/lib, where
$ROOT is the root directory of Erlang/OTP.
lib_dir(Name) -> Dir | {error, What}
Types:
Name = atom()
Dir = string()
What = bad_name
Searches the code path for a directory named
.../Name[-Vsn][/ebin] and returns the directory
.../Name[-Vsn]. Mainly intended for finding the library
directory of the Erlang/OTP application called Name.
> code:lib_dir(mnesia).
/usr/local/otp/lib/mnesia-4.2.2"
Returns {error, bad_name} if Name is not found
or if the argument is not valid.
Types:
Dir = string()
Searches the code path for the compiler library directory.
Equivalent of calling code:lib_dir(compiler).
priv_dir(Name) -> PrivDir | {error, What}
Types:
Name = atom()
PrivDir = string()
What = bad_name
Searches the code path for a directory named
.../Name[-Vsn][/ebin] and returns the directory
.../Name[-Vsn]/priv. It is not checked if this
directory really exists. Mainly intended for finding
the priv directory of the Erlang/OTP application called
Name.
> code:priv_dir(mnesia).
/usr/local/otp/lib/mnesia-4.2.2/priv"
Types:
Ext = string()
Returns the object code file extension that corresponds to the Erlang machine used, normally ".beam".
stick_dir(Dir) -> ok | {error, What}
Types:
Dir = string()
What = term()
This function marks Dir as sticky.
Returns ok if successful, and an error tuple
otherwise.
unstick_dir(Dir) -> ok | {error, What}
Types:
Dir = string()
What = term()
This function unsticks a directory which has been marked as sticky.
Returns ok if successful, and an error tuple
otherwise.
This function creates or rehashes the code path cache.
where_is_file(Filename) -> Absname | non_existing
Types:
Filename = Absname = string()
Searches the code path for Filename, a file of
arbitrary type. If found, the full name is returned.
non_existing is returned if the file cannot be found.
The function can be useful, for example, to locate
application resource files. If the code path cache is used,
the code server will efficiently read the full name from
the cache, provided that Filename is an object code
file or an .app file.
Searches the entire code space for module names with
identical names and writes a report to stdout.