code(3)

MODULE
code - Erlang Code Server

DESCRIPTION

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.

    *   In embedded mode, all code is loaded during system start-up according to the boot script. (Code can also be loaded later by explicitly ordering the code server to do so).

    *   In interactive mode, only some code is loaded during system startup-up, basically the modules needed by the runtime system itself. Other code is dynamically loaded when first referenced. When a call to a function in a certain module is made, and the module is not loaded, the code server searches for and tries to load the module.

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.

CODE PATH

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 $OTPROOT/lib, where $OTPROOT 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 environment variable ERL_LIBS (defined in the operating system) can be used to define additional library directories that will be handled in the same way as the standard OTP library directory described above, except that directories that do not have an ebin directory will be ignored.

All application directories found in the additional directories will appear before the standard OTP applications, except for the Kernel and STDLIB applications, which will be placed before any additional applications. In other words, modules found in any of the additional library directories will override modules with the same name in OTP, except for modules in Kernel and STDLIB.

The environment variable ERL_LIBS (if defined) shold contain a colon-separated (for Unix-like systems) or semicolon-separated (for Windows) list of additional libraries.

Example: On an Unix-like system, ERL_LIBS could be set to /usr/local/jungerl:/home/some_user/my_erlang_lib. (On Windows, use semi-colon as separator.)

CODE PATH CACHE

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.

CURRENT AND OLD CODE

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.

ARGUMENT TYPES AND INVALID ARGUMENTS

Generally, module and application names are atoms, while file and directory names are strings. For backward compatibility reasons, some functions accept both strings and atoms, but a future release will probably only allow the arguments that are documented.

From the R12B release, functions in this module will generally fail with an exception if they are passed an incorrect type (for instance, an integer or a tuple where an atom was expected). An error tuple will be returned if type of argument was correct, but there was some other error (for instance, a non-existing directory given to set_path/1.

EXPORTS

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.

get_path() -> Path

    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.

add_pathsa(Dirs) -> ok

    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, unless the module is already loaded. 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.

purge(Module) -> true | false

    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.

which(Module) -> Which

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

root_dir() -> string()

    Returns the root directory of Erlang/OTP, which is the directory where it is installed.
    > code:root_dir().
    "/usr/local/otp"

lib_dir() -> string()

    Returns the library directory, $OTPROOT/lib, where $OTPROOT is the root directory of Erlang/OTP.
    > code:lib_dir().
    "/usr/local/otp/lib"

lib_dir(Name) -> string() | {error, bad_name}

    Types
        Name = atom()

    This function is mainly intended for finding out the path for the "library directory", the top directory, for an application Name located under $OTPROOT/lib.

    If there is a directory called Name in the code path, optionally with a -Vsn suffix and/or an ebin subdirectory, the name of this directory is returned.
    > code:lib_dir(mnesia).
    "/usr/local/otp/lib/mnesia-4.2.2"

    Returns {error, bad_name} if Name is not the name of an application under $OTPROOT/lib. Fails with an exception if Name has the wrong type.

  Warning:

For backward compatibiliy, Name is also allowed to be a string. That will probably change in a future release.

compiler_dir() -> string()

    Returns the compiler library directory. Equivalent to code:lib_dir(compiler).

priv_dir(Name) -> string() | {error, bad_name}

    Types
        Name = atom()

    This function is mainly intended for finding out the path for the priv directory for an application Name located under $OTPROOT/lib.

    If there is a directory called Name in the code path, optionally with a -Vsn suffix and/or an ebin subdirectory, the function returns the name of this directory with priv appended. It is not checked if this directory really exists.
    > code:priv_dir(mnesia).
    "/usr/local/otp/lib/mnesia-4.2.2/priv"

    Returns {error, bad_name} if Name is not the name of an application under $OTPROOT/lib. Fails with an exception if Name has the wrong type.

  Warning:

For backward compatibiliy, Name is also allowed to be a string. That will probably change in a future release.

objfile_extension() -> ".beam"

    Returns the object code file extension that corresponds to the Erlang machine used, namely ".beam".

stick_dir(Dir) -> ok | error

    Types
        Dir = string()
        What = term()

    This function marks Dir as sticky.

    Returns ok if successful or error if not.

unstick_dir(Dir) -> ok | error

    Types
        Dir = string()
        What = term()

    This function unsticks a directory which has been marked as sticky.

    Returns ok if successful or error if not.

rehash() -> ok

    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.

clash() -> ok

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