code(3)

MODULE
code - Erlang Code Server

DESCRIPTION

This module deals with the loading of compiled code into a running Erlang runtime 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 Erlang/OTP, 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.

The code server incorporates a code path cache. The cache functionality is disabled by default. To activate it, start the emulator with 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 cache. This feature is used by application 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.

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 thestick 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}

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

    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
        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
        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, or the atom preloaded if the module was pre-loaded.

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 Erlang/OTP, which is the directory where it 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".

rehash() -> ok

    This function creates or rehashes the code path cache.

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 | cover_compiled
        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, preloaded is returned. If the module is Cover compiled, cover_compiled is returned.non_existing is returned if the module cannot be found.

where_is_file(File) -> FullName

    Types
        File = string()
        FullName = string() | non_existing

    This function searches the directories in the code path for File (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 e.g. to locate application resource files. If the code path cache is used, the code server will efficiently read the full name from the cache (if File is an object code file or a .app file, that is).

clash() -> ok

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

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