-spec add_path(Dir) -> add_path_ret() when Dir :: file:filename().

Equivalent to add_pathz/2

-spec add_path(Dir, cache()) -> add_path_ret() when Dir :: file:filename().

Equivalent to add_pathz/2

-spec add_patha(Dir) -> add_path_ret() when Dir :: file:filename().

Equivalent to add_patha/2

-spec add_patha(Dir, cache()) -> add_path_ret() when Dir :: file:filename().

Adds Dir to the beginning of the code path. If Dir exists, it is removed from the old position in the code path.

An optional second argument may be set to the atom cache to control if the contents of the directory must be cached on first traversal. Defaults to nocache.

Returns true if successful, or {error, bad_directory} if Dir is not the name of a directory.

-spec add_paths(Dirs) -> ok when Dirs :: [Dir :: file:filename()].

Equivalent to add_pathsz/2

-spec add_paths(Dirs, cache()) -> ok when Dirs :: [Dir :: file:filename()].

Equivalent to add_pathsz/2

-spec add_pathsa(Dirs) -> ok when Dirs :: [Dir :: file:filename()].

Equivalent to add_pathsa/2

-spec add_pathsa(Dirs, cache()) -> ok when Dirs :: [Dir :: file:filename()].

Traverses Dirs and adds each Dir to the beginning of the code path. This means that the order of Dirs is reversed in the resulting code path. For example, if you add [Dir1,Dir2], the resulting path will be [Dir2,Dir1|OldCodePath].

If a Dir already exists in the code path, it is removed from the old position.

An optional second argument may be set to the atom cache to control if the contents of the directory must be cached on first traversal. Defaults to nocache.

Always returns ok, regardless of the validity of each individual Dir.

-spec add_pathsz(Dirs) -> ok when Dirs :: [Dir :: file:filename()].

Equivalent to add_pathsz/2

-spec add_pathsz(Dirs, cache()) -> ok when Dirs :: [Dir :: file:filename()].

Adds the directories in Dirs to the end of the code path. If a Dir exists, it is not added.

An optional second argument may be set to the atom cache to control if the contents of the directory must be cached on first traversal. Defaults to nocache.

Always returns ok, regardless of the validity of each individual Dir.

-spec add_pathz(Dir) -> add_path_ret() when Dir :: file:filename().

Equivalent to add_pathz/2

-spec add_pathz(Dir, cache()) -> add_path_ret() when Dir :: file:filename().

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.

An optional second argument may be set to the atom cache to control if the contents of the directory must be cached on first traversal. Defaults to nocache.

Returns true if successful, or {error, bad_directory} if Dir is not the name of a directory.

-spec all_available() -> [{Module, Filename, Loaded}]
                 when Module :: string(), Filename :: loaded_filename(), Loaded :: boolean().

Returns a list of tuples {Module, Filename, Loaded} for all available modules. A module is considered to be available if it either is loaded or would be loaded if called. Filename is normally the absolute filename, as described for is_loaded/1.

-spec all_loaded() -> [{Module, Loaded}] when Module :: module(), Loaded :: loaded_filename().

Returns a list of tuples {Module, Loaded} for all loaded modules. Loaded is normally the absolute filename, as described for is_loaded/1.

-spec atomic_load(Modules) -> ok | {error, [{Module, What}]}
               when
                   Modules :: [Module | {Module, Filename, Binary}],
                   Module :: module(),
                   Filename :: file:filename(),
                   Binary :: binary(),
                   What ::
                       badfile | nofile | on_load_not_allowed | duplicated | not_purged |
                       sticky_directory | pending_on_load.

Tries to load all of the modules in the list Modules atomically. That means that either all modules are loaded at the same time, or none of the modules are loaded if there is a problem with any of the modules.

Loading can fail for one the following reasons:

• badfile - The object code has an incorrect format or the module name in the object code is not the expected module name.

• nofile - No file with object code exists.

• on_load_not_allowed - A module contains an -on_load function.

• duplicated - A module is included more than once in Modules.

• not_purged - The object code cannot be loaded because an old version of the code already exists.

• sticky_directory - The object code resides in a sticky directory.

• pending_on_load - A previously loaded module contains an -on_load function that never finished.

If it is important to minimize the time that an application is inactive while changing code, use prepare_loading/1 and finish_loading/1 instead of atomic_load/1. Here is an example:

{ok,Prepared} = code:prepare_loading(Modules),
%% Put the application into an inactive state or do any
%% other preparation needed before changing the code.
ok = code:finish_loading(Prepared),
%% Resume the application.

-spec clash() -> ok.

Searches all directories in the code path for module names with identical names and writes a report to stdout.

-spec clear_cache() -> ok.

Clear the code path cache. If a directory is cached, its cache is cleared once and then it will be recalculated and cached once more in a future traversal.

If you want to clear the cache for a single path, you might re-add it to the code path (with add_path/2) or replace it (with replace_path/3). If you want to disable all cache, you can reset the code path with code:set_path(code:get_path()).

Always returns ok.

-spec compiler_dir() -> file:filename().

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

-spec coverage_support() -> Supported when Supported :: boolean().

Returns true if the system supports coverage and false otherwise.

-spec del_path(NameOrDir) -> boolean() | {error, What}
            when NameOrDir :: Name | Dir, Name :: atom(), Dir :: file:filename(), 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. Also, the complete directory name Dir can be specified as argument.

Returns:

• true - If successful

• false - If the directory is not found

• {error, bad_name} - If the argument is invalid

-spec del_paths(NamesOrDirs) -> ok
             when NamesOrDirs :: [Name | Dir], Name :: atom(), Dir :: file:filename().

Deletes directories from the code path. The argument is a list of either atoms or complete directory names. If an atom Name, the directory with the name .../Name[-Vsn][/ebin] is deleted from the code path.

Always returns ok, regardless of the validity of each individual NamesOrDirs.

-spec delete(Module) -> boolean() when Module :: module().

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 no external function calls can be made to it.

Returns true if successful, or false if there is old code for Module that must be purged first, or if Module is not a (loaded) module.

-spec ensure_loaded(Module) -> {module, Module} | {error, What}
                 when Module :: module(), What :: embedded | badfile | nofile | on_load_failure.

Tries to load a module in the same way as load_file/1, unless the module is already loaded. If called concurrently, this function ensures only one process attempts to load said module at a given time.

In embedded mode, it does not load a module that is not already loaded, but returns {error, embedded} instead. See Error Reasons for Code-Loading Functions for a description of other possible error reasons.

-spec ensure_modules_loaded([Module]) -> ok | {error, [{Module, What}]}
                         when Module :: module(), What :: badfile | nofile | on_load_failure.

Tries to load any modules not already loaded in the list Modules in the same way as load_file/1. Unlike ensure_loaded/1, modules are loaded even in embedded mode.

Returns ok if successful, or {error,[{Module,Reason}]} if loading of some modules fails. See Error Reasons for Code-Loading Functions for a description of other possible error reasons.

-spec finish_loading(Prepared) -> ok | {error, [{Module, What}]}
                  when
                      Prepared :: prepared_code(),
                      Module :: module(),
                      What :: not_purged | sticky_directory | pending_on_load.

Tries to load code for all modules that have been previously prepared by prepare_loading/1. The loading occurs atomically, meaning that either all modules are loaded at the same time, or none of the modules are loaded.

This function can fail with one of the following error reasons:

• not_purged - The object code cannot be loaded because an old version of the code already exists.

• sticky_directory - The object code resides in a sticky directory.

• pending_on_load - A previously loaded module contains an -on_load function that never finished.

-spec get_coverage(Level, module()) -> Result
                when
                    Level :: function | line | cover_id_line,
                    Result :: [{Entity, CoverageInfo}],
                    Entity :: {Function, Arity} | Line | CoverId,
                    CoverageInfo :: Covered | Counter,
                    Function :: atom(),
                    Arity :: arity(),
                    Line :: non_neg_integer(),
                    CoverId :: pos_integer(),
                    Covered :: boolean(),
                    Counter :: non_neg_integer().

If Level is function, returns line coverage for the given module according to its coverage mode:

• function - For each function in module Module, a boolean indicating whether that function has been executed at least once is returned.

• function_counters - For each function in module Module, an integer giving the number of times that line has been executed is returned.

• line - For each function in module Module, a boolean indicating whether that function has been executed at least once is returned.

• line_counters - For each function in module Module, a boolean indicating whether that function has been executed at least once is returned (note that in this mode, counters for the number of times each function has been executed cannot be retrieved).

If Level is line, returns line coverage for the given module according to its coverage mode:

• line - For each executable line in the module, a boolean indicating whether that line has been executed at least once is returned.

• line_counters - For each executable line in the module, an integer giving the number of times that line was executed is returned.

Level cover_id_line is used by the cover tool.

Failures:

• badarg - If Level is not function or line.

• badarg - If Module is not an atom.

• badarg - If Module does not refer to a loaded module.

• badarg - If Module was not loaded in another coverage mode than none.

• badarg - If Level is line and Module has not been loaded with either line or line_counters enabled.

• badarg - If the runtime system does not support coverage.

-spec get_coverage_mode() -> Mode when Mode :: coverage_mode().

Returns the current coverage mode as set by option +JPcover for erl or set_coverage_mode/1.

Failure:

• badarg - If the runtime system does not support coverage.

-spec get_coverage_mode(Module) -> Mode when Module :: module(), Mode :: coverage_mode().

Get coverage mode for the given module.

Failures:

• badarg - If Module is not an atom.

• badarg - If Module does not refer to a loaded module.

• badarg - If the runtime system does not support coverage.

-spec get_doc(Mod) -> {ok, Res} | {error, Reason}
           when
               Mod :: module(),
               Res ::
                   #docs_v1{anno :: term(),
                            beam_language :: term(),
                            format :: term(),
                            module_doc :: term(),
                            metadata :: term(),
                            docs :: term()},
               Reason :: non_existing | missing | file:posix().

Searches the code path for EEP-48 style documentation and returns it if available. If no documentation can be found the function tries to generate documentation from the debug information in the module. If no debug information is available, this function will return {error,missing}.

For more information about the documentation chunk see Documentation Storage and Format in Kernel's User's Guide.

-spec get_mode() -> embedded | interactive.

Returns an atom describing the mode of the code server: interactive or embedded.

This information is useful when an external entity (for example, an IDE) provides additional code for a running node. If the code server is in interactive mode, it only has to add the path to the code. If the code server is in embedded mode, the code must be loaded with load_binary/3.

-spec get_object_code(Module) -> {Module, Binary, Filename} | error
                   when Module :: module(), Binary :: binary(), Filename :: file:filename().

Searches the code path for the object code of module Module. Returns {Module, Binary, Filename} if successful, otherwise error. 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]),
...

-spec get_path() -> Path when Path :: [Dir :: file:filename()].

Returns the code path.

-spec is_loaded(Module) -> {file, Loaded} | false when Module :: module(), Loaded :: loaded_filename().

Checks if Module is loaded. If it is, {file, Loaded} is returned, otherwise false.

Normally, Loaded is the absolute filename Filename from which the code is obtained. If the module is preloaded (see script(4)), Loaded==preloaded. If the module is Cover-compiled (see cover), Loaded==cover_compiled.

-spec is_sticky(Module) -> boolean() when Module :: module().

Returns true if Module is the name of a module that has been loaded from a sticky directory (in other words: an attempt to reload the module will fail), or false if Module is not a loaded module or is not sticky.

-spec lib_dir() -> file:filename().

Returns the library directory, $OTPROOT/lib, where $OTPROOT is the root directory of Erlang/OTP.

Example:

> code:lib_dir().
"/usr/local/otp/lib"

-spec lib_dir(Name) -> file:filename() | {error, bad_name} when Name :: atom().

Returns the path for the "library directory", the top directory, for an application Name located under $OTPROOT/lib or on a directory referred to with environment variable ERL_LIBS.

If a regular directory called Name or Name-Vsn exists in the code path with an ebin subdirectory, the path to this directory is returned (not the ebin directory).

If the directory refers to a directory in an archive, the archive name is stripped away before the path is returned. For example, if directory /usr/local/otp/lib/mnesia-4.2.2.ez/mnesia-4.2.2/ebin is in the path, /usr/local/otp/lib/mnesia-4.2.2/ebin is returned. This means that the library directory for an application is the same, regardless if the application resides in an archive or not.

Example:

> 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 or on a directory referred to through environment variable ERL_LIBS. Fails with an exception if Name has the wrong type.

Warning

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

-spec lib_dir(Name, SubDir) -> file:filename() | {error, bad_name} when Name :: atom(), SubDir :: atom().

Change

This function is deprecated and will be removed in a future release.

Returns the path to a subdirectory directly under the top directory of an application. Normally the subdirectories reside under the top directory for the application, but when applications at least partly reside in an archive, the situation is different. Some of the subdirectories can reside as regular directories while others reside in an archive file. It is not checked whether this directory exists.

Instead of using this function, use code:lib_dir/1.

Example:

> filename:join(code:lib_dir(megaco), "priv").
"/usr/local/otp/lib/megaco-3.9.1.1/priv"

Fails with an exception if Name or SubDir has the wrong type.

-spec load_abs(Filename) -> load_ret() when Filename :: file:filename().

Same as load_file(Module), but Filename is an absolute or relative filename. The code path is not searched. It returns a value in the same way as load_file/1. Notice that Filename must not contain the extension (for example, .beam) because load_abs/1 adds the correct extension.

-spec load_binary(Module, Filename, Binary) -> {module, Module} | {error, What}
               when
                   Module :: module(),
                   Filename :: loaded_filename(),
                   Binary :: binary(),
                   What :: badarg | load_error_rsn().

This function can be used to load object code on remote Erlang nodes. Argument 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. Thus, Filename is not opened and read by the code server.

Returns {module, Module} if successful, or {error, Reason} if loading fails. See Error Reasons for Code-Loading Functions for a description of the possible error reasons.

-spec load_file(Module) -> load_ret() when Module :: module().

Tries to load the Erlang module Module, using the code path. It looks for the object code file with an extension corresponding 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, Reason} if loading fails. See Error Reasons for Code-Loading Functions for a description of the possible error reasons.

-spec modified_modules() -> [module()].

Returns the list of all currently loaded modules for which module_status/1 returns modified. See also all_loaded/0.

-spec module_status() -> [{module(), module_status()}].

See module_status/1 and all_loaded/0 for details.

-spec module_status(Module :: module() | [module()]) -> module_status() | [{module(), module_status()}].

The status of a module can be one of:

• not_loaded - If Module is not currently loaded.

• loaded - If Module is loaded and the object file exists and contains the same code.

• removed - If Module is loaded but no corresponding object file can be found in the code path.

• modified - If Module is loaded but the object file contains code with a different MD5 checksum.

Preloaded modules are always reported as loaded, without inspecting the contents on disk. Cover compiled modules will always be reported as modified if an object file exists, or as removed otherwise. Modules whose load path is an empty string (which is the convention for auto-generated code) will only be reported as loaded or not_loaded.

See also modified_modules/0.

-spec objfile_extension() -> nonempty_string().

Returns the object code file extension corresponding to the Erlang machine used, namely .beam.

-spec prepare_loading(Modules) -> {ok, Prepared} | {error, [{Module, What}]}
                   when
                       Modules :: [Module | {Module, Filename, Binary}],
                       Module :: module(),
                       Filename :: file:filename(),
                       Binary :: binary(),
                       Prepared :: prepared_code(),
                       What :: badfile | nofile | on_load_not_allowed | duplicated.

Prepares to load the modules in the list Modules. Finish the loading by calling finish_loading(Prepared).

This function can fail with one of the following error reasons:

• badfile - The object code has an incorrect format or the module name in the object code is not the expected module name.

• nofile - No file with object code exists.

• on_load_not_allowed - A module contains an -on_load function.

• duplicated - A module is included more than once in Modules.

-spec priv_dir(Name) -> file:filename() | {error, bad_name} when Name :: atom().

Returns the path to the priv directory in an application. Equivalent to code:lib_dir(Name, priv).

Warning

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

-spec purge(Module) -> boolean() when Module :: module().

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.

Note

As of ERTS version 9.0, a process is only considered to be lingering in the code if it has direct references to the code. For more information see documentation of erlang:check_process_code/3, which is used in order to determine this.

Returns true if successful and any process is needed to be killed, otherwise false.

-spec replace_path(Name, Dir) -> replace_path_ret() when Name :: atom(), Dir :: file:filename().

Equivalent to replace_path/3

-spec replace_path(Name, Dir, cache()) -> replace_path_ret() when Name :: atom(), Dir :: file:filename().

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 is to be used if a new version of the directory (library) is added to a running system.

An optional third argument may be set to the atom cache to control if the contents of the directory must be cached on first traversal. Defaults to nocache.

Returns:

• true - If successful

• {error, bad_name} - If Name is not found

• {error, bad_directory} - If Dir does not exist

• {error, {badarg, [Name, Dir]}} - If Name or Dir is invalid

-spec reset_coverage(Module) -> ok when Module :: module().

Reset coverage information for module Module.

Failures:

• badarg - If Module is not an atom.

• badarg - If Module does not refer to a loaded module.

• badarg - If Module was not loaded with coverage enabled.

• badarg - If the runtime system does not support coverage.

-spec root_dir() -> file:filename().

Returns the root directory of Erlang/OTP, which is the directory where it is installed.

Example:

> code:root_dir().
"/usr/local/otp"

-spec set_coverage_mode(Mode) -> OldMode when Mode :: coverage_mode(), OldMode :: coverage_mode().

Sets the coverage mode for modules that are subsequently loaded, similar to option +JPcover for erl:

• function - All modules that are loaded will be instrumented to keep track of which functions are executed. Information about which functions that have been executed can be retrieved by calling get_coverage(function, Module).

• function_counters - All modules that are loaded will be instrumented to count how many times each function is executed. Information about how many times each function has been executed can be retrieved by calling get_coverage(function, Module).

• line - When modules that have been compiled with the line_coverage option are loaded, they will be instrumented to keep track of which lines have been executed. Information about which lines have been executed can be retrieved by calling get_coverage(line, Module), and information about which functions that have been executed can be retrieved by calling get_coverage(function, Module).

• line_counters - When modules that have been compiled with the line_coverage option are loaded, they will be instrumented to count the number of times each line is executed. Information about how many times each line has been executed can be retrieved by calling get_coverage(line, Module), and information about which functions that have been executed can be retrieved by calling get_coverage(function, Module) (note that in this mode, counters for the number of times each function has been executed cannot be retrieved).

• none - Modules will be loaded without coverage instrumentation.

Returns the previous coverage mode.

Failures:

• badarg - If Mode is not a valid coverage mode.

• badarg - If the runtime system does not support coverage.

-spec set_path(Path) -> set_path_ret() when Path :: [Dir :: file:filename()].

Equivalent to set_path/2

-spec set_path(Path, cache()) -> set_path_ret() when Path :: [Dir :: file:filename()].

Sets the code path to the list of directories Path.

An optional second argument may be set to the atom cache to control if the contents of the directory must be cached on first traversal. Defaults to nocache.

Returns:

• true - If successful

• {error, bad_directory} - If any Dir is not a directory name

-spec soft_purge(Module) -> boolean() when Module :: module().

Purges the code for Module, that is, removes code marked as old, but only if no processes linger in it.

Note

As of ERTS version 9.0, a process is only considered to be lingering in the code if it has direct references to the code. For more information see documentation of erlang:check_process_code/3, which is used in order to determine this.

Returns false if the module cannot be purged because of processes lingering in old code, otherwise true.

-spec stick_dir(Dir) -> ok | error when Dir :: file:filename().

Marks Dir as sticky.

Returns ok if successful, otherwise error.

-spec unstick_dir(Dir) -> ok | error when Dir :: file:filename().

Unsticks a directory that is marked as sticky.

Returns ok if successful, otherwise error.

-spec where_is_file(Filename) -> non_existing | Absname
                 when Filename :: file:filename(), Absname :: file:filename().

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.

-spec which(Module) -> Which when Module :: module(), Which :: loaded_filename() | non_existing.

If the module is not loaded, this function searches the code path for the first file containing object code for Module and returns the absolute filename.

If the module is loaded, it returns the name of the file containing the loaded object code.

If the module is preloaded, preloaded is returned.

If the module is Cover-compiled, cover_compiled is returned.

If the module cannot be found, non_existing is returned.