# code

### MODULE

code

### MODULE SUMMARY

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

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

kernel 2.10.4
Copyright © 1991-2005 Ericsson AB