code(3)

MODULE
code - 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 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.jam. 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).

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 . jam. 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 ".jam".

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 - joe@erix.ericsson.se
Magnus Froberg - magnus@erix.ericsson.se
Robert Virding - rv@erix.ericsson.se
Claes Wikstrom - klacke@erix.ericsson.se