File 1411-code-order-function-docs-alphabetically.patch of Package erlang
From f5c2d376d637ed51771307a1f340784f3b8a8493 Mon Sep 17 00:00:00 2001
From: Maria Scott <maria-12648430@hnc-agency.org>
Date: Tue, 20 Jun 2023 12:52:57 +0200
Subject: [PATCH] code: order function docs alphabetically
---
lib/kernel/doc/src/code.xml | 768 ++++++++++++++++++------------------
1 file changed, 384 insertions(+), 384 deletions(-)
diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml
index b4b7d51221..5a1bb44cef 100644
--- a/lib/kernel/doc/src/code.xml
+++ b/lib/kernel/doc/src/code.xml
@@ -327,10 +327,10 @@ zip:create("mnesia-4.4.7.ez",
<name name="cache"/>
</datatype>
<datatype>
- <name name="load_ret"/>
+ <name name="load_error_rsn"/>
</datatype>
<datatype>
- <name name="load_error_rsn"/>
+ <name name="load_ret"/>
</datatype>
<datatype>
<name name="module_status"/>
@@ -348,31 +348,6 @@ zip:create("mnesia-4.4.7.ez",
</datatypes>
<funcs>
- <func>
- <name name="set_path" arity="1" since=""/>
- <name name="set_path" arity="2" since="OTP 26.0"/>
- <fsummary>Set the code server search path.</fsummary>
- <desc>
- <p>Sets the code path to the list of directories <c><anno>Path</anno></c>.</p>
- <p>An optional second argument may be set to the atom <c>cache</c> to
- control if the contents of the directory must be cached on first traversal.
- Defaults to <c>nocache</c>.</p>
- <p>Returns:</p>
- <taglist>
- <tag><c>true</c></tag>
- <item><p>If successful</p></item>
- <tag><c>{error, bad_directory}</c></tag>
- <item><p>If any <c><anno>Dir</anno></c> is not a directory name</p></item>
- </taglist>
- </desc>
- </func>
- <func>
- <name name="get_path" arity="0" since=""/>
- <fsummary>Return the code server search path.</fsummary>
- <desc>
- <p>Returns the code path.</p>
- </desc>
- </func>
<func>
<name name="add_path" arity="1" since=""/>
<name name="add_path" arity="2" since="OTP 26.0"/>
@@ -446,144 +421,32 @@ zip:create("mnesia-4.4.7.ez",
</desc>
</func>
<func>
- <name name="del_path" arity="1" since=""/>
- <fsummary>Delete a directory from the code path.</fsummary>
- <desc>
- <p>Deletes a directory from the code path. The argument can be
- an atom <c><anno>Name</anno></c>, in which case the directory with
- the name <c>.../<anno>Name</anno>[-Vsn][/ebin]</c> is deleted from the code
- path. Also, the complete directory name <c><anno>Dir</anno></c> can be
- specified as argument.</p>
- <p>Returns:</p>
- <taglist>
- <tag><c>true</c></tag>
- <item><p>If successful</p></item>
- <tag><c>false</c></tag>
- <item><p>If the directory is not found</p></item>
- <tag><c>{error, bad_name}</c></tag>
- <item><p>If the argument is invalid</p></item>
- </taglist>
- </desc>
- </func>
- <func>
- <name name="del_paths" arity="1" since="OTP 26.0"/>
- <fsummary>Deletes directories from the code path.</fsummary>
- <desc>
- <p>Deletes directories from the code path. The argument is a list of either
- atoms or complete directory names. If an atom <c><anno>Name</anno></c>,
- the directory with the name <c>.../<anno>Name</anno>[-Vsn][/ebin]</c> is
- deleted from the code path.</p>
- <p>Always returns <c>ok</c>, regardless of the validity
- of each individual <c><anno>NamesOrDirs</anno></c>.</p>
- </desc>
- </func>
- <func>
- <name name="clear_cache" arity="0" since="OTP 26.0"/>
- <fsummary>Clears the code path cache.</fsummary>
- <desc>
- <p>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.</p>
- <p>If you want to clear the cache for a single path, you might re-add it
- to the code path (with <c>add_path/2</c>) or
- replace it (with <c>replace_path/3</c>).
- If you want to disable all cache, you can reset the code path
- with <c>code:set_path(code:get_path())</c>.</p>
- <p>Always returns <c>ok</c>.</p>
- </desc>
- </func>
- <func>
- <name name="replace_path" arity="2" since=""/>
- <name name="replace_path" arity="3" since="OTP 26.0"/>
- <fsummary>Replace a directory with another in the code path.</fsummary>
- <desc>
- <p>Replaces an old occurrence of a directory
- named <c>.../<anno>Name</anno>[-Vsn][/ebin]</c> in the code path, with
- <c><anno>Dir</anno></c>. If <c><anno>Name</anno></c> does not exist, it adds
- the new directory <c><anno>Dir</anno></c> last in the code path. The new
- directory must also be named <c>.../<anno>Name</anno>[-Vsn][/ebin]</c>.
- This function is to be used if a new version of the directory (library) is
- added to a running system.</p>
- <p>An optional third argument may be set to the atom <c>cache</c> to
- control if the contents of the directory must be cached on first traversal.
- Defaults to <c>nocache</c>.</p>
- <p>Returns:</p>
- <taglist>
- <tag><c>true</c></tag>
- <item><p>If successful</p></item>
- <tag><c>{error, bad_name}</c></tag>
- <item><p>If <c><anno>Name</anno></c> is not found</p></item>
- <tag><c>{error, bad_directory}</c></tag>
- <item><p>If <c><anno>Dir</anno></c> does not exist</p></item>
- <tag><c>{error, {badarg, [<anno>Name</anno>, <anno>Dir</anno>]}}</c></tag>
- <item><p>If <c><anno>Name</anno></c> or <c><anno>Dir</anno></c> is invalid</p></item>
- </taglist>
- </desc>
- </func>
- <func>
- <name name="load_file" arity="1" since=""/>
- <fsummary>Load a module.</fsummary>
- <type name="load_ret"/>
- <desc>
- <p>Tries to load the Erlang module <c><anno>Module</anno></c>, using
- the code path. It looks for the object code file with an
- extension corresponding to the Erlang machine used, for
- example, <c><anno>Module</anno>.beam</c>. The loading fails if the module
- name found in the object code differs from the name
- <c><anno>Module</anno></c>.
- <seemfa marker="#load_binary/3"><c>load_binary/3</c></seemfa> must
- be used to load object code with a module name that is
- different from the file name.</p>
- <p>Returns <c>{module, <anno>Module</anno>}</c> if successful, or
- <c>{error, Reason}</c> if loading fails.
- See <seeerl marker="#error_reasons">Error Reasons for Code-Loading Functions</seeerl> for a description of the possible error reasons.</p>
- </desc>
- </func>
- <func>
- <name name="load_abs" arity="1" since=""/>
- <fsummary>Load a module, residing in a specified file.</fsummary>
- <type name="load_ret"/>
+ <name name="all_available" arity="0" since="OTP 23.0"/>
+ <fsummary>Get all available modules.</fsummary>
<type name="loaded_filename"/>
<type name="loaded_ret_atoms"/>
+ <type_desc name="loaded_filename"><c><anno>Filename</anno></c> is an absolute
+ filename.</type_desc>
<desc>
- <p>Same as <c>load_file(<anno>Module</anno>)</c>, but
- <c><anno>Filename</anno></c> is an absolute or
- relative filename. The code path is not searched. It returns
- a value in the same way as
- <seemfa marker="#load_file/1"><c>load_file/1</c></seemfa>. Notice
- that <c><anno>Filename</anno></c> must not contain the extension (for
- example, <c>.beam</c>) because <c>load_abs/1</c> adds the correct
- extension.</p>
- </desc>
- </func>
- <func>
- <name name="ensure_loaded" arity="1" since=""/>
- <fsummary>Ensure that a module is loaded.</fsummary>
- <desc>
- <p>Tries to load a module in the same way as
- <seemfa marker="#load_file/1"><c>load_file/1</c></seemfa>,
- unless the module is already loaded.
- However, in embedded mode it does not load a module that is not
- already loaded, but returns <c>{error, embedded}</c> instead.
- See <seeerl marker="#error_reasons">Error Reasons for Code-Loading Functions</seeerl> for a description of other possible error reasons.</p>
+ <p>Returns a list of tuples <c>{<anno>Module</anno>, <anno>Filename</anno>,
+ <anno>Loaded</anno>}</c> for all available modules. A module is considered
+ to be available if it either is loaded or would be loaded if called.
+ <c><anno>Filename</anno></c> is normally the absolute filename, as described for
+ <seemfa marker="#is_loaded/1"><c>is_loaded/1</c></seemfa>.</p>
</desc>
</func>
<func>
- <name name="load_binary" arity="3" since=""/>
- <fsummary>Load object code for a module.</fsummary>
+ <name name="all_loaded" arity="0" since=""/>
+ <fsummary>Get all loaded modules.</fsummary>
<type name="loaded_filename"/>
<type name="loaded_ret_atoms"/>
+ <type_desc name="loaded_filename"><c><anno>Filename</anno></c> is an absolute
+ filename.</type_desc>
<desc>
- <p>This function can be used to load object code on remote
- Erlang nodes. Argument <c><anno>Binary</anno></c> must contain
- object code for <c><anno>Module</anno></c>.
- <c><anno>Filename</anno></c> is only used by the code server to keep a
- record of from which file the object code for <c><anno>Module</anno></c>
- comes. Thus, <c><anno>Filename</anno></c> is not opened and read by
- the code server.</p>
- <p>Returns <c>{module, <anno>Module</anno>}</c> if successful, or
- <c>{error, Reason}</c> if loading fails.
- See <seeerl marker="#error_reasons">Error Reasons for Code-Loading Functions</seeerl> for a description of the possible error reasons.</p>
+ <p>Returns a list of tuples <c>{<anno>Module</anno>, <anno>Loaded</anno>}</c> for all
+ loaded modules. <c><anno>Loaded</anno></c> is normally the absolute filename,
+ as described for
+ <seemfa marker="#is_loaded/1"><c>is_loaded/1</c></seemfa>.</p>
</desc>
</func>
<func>
@@ -646,80 +509,70 @@ ok = code:finish_loading(Prepared),
</desc>
</func>
<func>
- <name name="prepare_loading" arity="1" since="OTP 19.0"/>
- <fsummary>Prepare a list of modules atomically</fsummary>
+ <name name="clash" arity="0" since=""/>
+ <fsummary>Search for modules with identical names.</fsummary>
<desc>
- <p>Prepares to load the modules in the list
- <c><anno>Modules</anno></c>.
- Finish the loading by calling
- <seemfa marker="#finish_loading/1">finish_loading(Prepared)</seemfa>.</p>
- <p>This function can fail with one of the following error reasons:</p>
- <taglist>
- <tag><c>badfile</c></tag>
- <item>
- <p>The object code has an incorrect format or the module
- name in the object code is not the expected module name.</p>
- </item>
- <tag><c>nofile</c></tag>
- <item>
- <p>No file with object code exists.</p>
- </item>
- <tag><c>on_load_not_allowed</c></tag>
- <item>
- <p>A module contains an
- <seeguide marker="system/reference_manual:code_loading#on_load">-on_load function</seeguide>.</p>
- </item>
- <tag><c>duplicated</c></tag>
- <item>
- <p>A module is included more than once in
- <c><anno>Modules</anno></c>.</p>
- </item>
- </taglist>
+ <p>Searches all directories in the code path for module names with
+ identical names and writes a report to <c>stdout</c>.</p>
</desc>
</func>
<func>
- <name name="finish_loading" arity="1" since="OTP 19.0"/>
- <fsummary>Finish loading a list of prepared modules atomically</fsummary>
+ <name name="clear_cache" arity="0" since="OTP 26.0"/>
+ <fsummary>Clears the code path cache.</fsummary>
<desc>
- <p>Tries to load code for all modules that have been previously
- prepared by
- <seemfa marker="#prepare_loading/1">prepare_loading/1</seemfa>.
- The loading occurs atomically, meaning that
- either all modules are loaded at the same time, or
- none of the modules are loaded.</p>
- <p>This function can fail with one of the following error reasons:</p>
- <taglist>
- <tag><c>not_purged</c></tag>
- <item>
- <p>The object code cannot be loaded because an old version
- of the code already exists.</p>
- </item>
- <tag><c>sticky_directory</c></tag>
- <item>
- <p>The object code resides in a sticky directory.</p>
- </item>
- <tag><c>pending_on_load</c></tag>
- <item>
- <p>A previously loaded module contains an
- <c>-on_load</c> function that never finished.</p>
- </item>
- </taglist>
+ <p>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.</p>
+ <p>If you want to clear the cache for a single path, you might re-add it
+ to the code path (with <c>add_path/2</c>) or
+ replace it (with <c>replace_path/3</c>).
+ If you want to disable all cache, you can reset the code path
+ with <c>code:set_path(code:get_path())</c>.</p>
+ <p>Always returns <c>ok</c>.</p>
</desc>
</func>
<func>
- <name name="ensure_modules_loaded" arity="1" since="OTP 19.0"/>
- <fsummary>Ensure that a list of modules is loaded</fsummary>
+ <name name="compiler_dir" arity="0" since=""/>
+ <fsummary>Library directory for the compiler.</fsummary>
<desc>
- <p>Tries to load any modules not already loaded in the list
- <c><anno>Modules</anno></c> in the same way as
- <seemfa marker="#load_file/1">load_file/1</seemfa>.</p>
- <p>Returns <c>ok</c> if successful, or
- <c>{error,[{Module,Reason}]}</c> if loading of some modules fails.
- See <seeerl marker="#error_reasons">Error Reasons for Code-Loading Functions</seeerl> for a description of other possible error reasons.</p>
+ <p>Returns the compiler library directory. Equivalent to
+ <c>code:lib_dir(compiler)</c>.</p>
</desc>
</func>
<func>
- <name name="delete" arity="1" since=""/>
+ <name name="del_path" arity="1" since=""/>
+ <fsummary>Delete a directory from the code path.</fsummary>
+ <desc>
+ <p>Deletes a directory from the code path. The argument can be
+ an atom <c><anno>Name</anno></c>, in which case the directory with
+ the name <c>.../<anno>Name</anno>[-Vsn][/ebin]</c> is deleted from the code
+ path. Also, the complete directory name <c><anno>Dir</anno></c> can be
+ specified as argument.</p>
+ <p>Returns:</p>
+ <taglist>
+ <tag><c>true</c></tag>
+ <item><p>If successful</p></item>
+ <tag><c>false</c></tag>
+ <item><p>If the directory is not found</p></item>
+ <tag><c>{error, bad_name}</c></tag>
+ <item><p>If the argument is invalid</p></item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name name="del_paths" arity="1" since="OTP 26.0"/>
+ <fsummary>Deletes directories from the code path.</fsummary>
+ <desc>
+ <p>Deletes directories from the code path. The argument is a list of either
+ atoms or complete directory names. If an atom <c><anno>Name</anno></c>,
+ the directory with the name <c>.../<anno>Name</anno>[-Vsn][/ebin]</c> is
+ deleted from the code path.</p>
+ <p>Always returns <c>ok</c>, regardless of the validity
+ of each individual <c><anno>NamesOrDirs</anno></c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name name="delete" arity="1" since=""/>
<fsummary>Remove current code for a module.</fsummary>
<desc>
<p>Removes the current code for <c><anno>Module</anno></c>, that is,
@@ -732,98 +585,84 @@ ok = code:finish_loading(Prepared),
</desc>
</func>
<func>
- <name name="purge" arity="1" since=""/>
- <fsummary>Remove old code for a module.</fsummary>
- <desc>
- <p>Purges the code for <c><anno>Module</anno></c>, 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.</p>
- <note><p>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
- <seemfa marker="erts:erlang#check_process_code/3"><c>erlang:check_process_code/3</c></seemfa>,
- which is used in order to determine this.</p></note>
- <p>Returns <c>true</c> if successful and any process is needed to
- be killed, otherwise <c>false</c>.</p>
- </desc>
- </func>
- <func>
- <name name="soft_purge" arity="1" since=""/>
- <fsummary>Remove old code for a module, unless no process uses it.</fsummary>
+ <name name="ensure_loaded" arity="1" since=""/>
+ <fsummary>Ensure that a module is loaded.</fsummary>
<desc>
- <p>Purges the code for <c><anno>Module</anno></c>, that is, removes code
- marked as old, but only if no processes linger in it.</p>
- <note><p>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
- <seemfa marker="erts:erlang#check_process_code/3"><c>erlang:check_process_code/3</c></seemfa>,
- which is used in order to determine this.</p></note>
- <p>Returns <c>false</c> if the module cannot be purged because
- of processes lingering in old code, otherwise <c>true</c>.</p>
+ <p>Tries to load a module in the same way as
+ <seemfa marker="#load_file/1"><c>load_file/1</c></seemfa>,
+ unless the module is already loaded.
+ However, in embedded mode it does not load a module that is not
+ already loaded, but returns <c>{error, embedded}</c> instead.
+ See <seeerl marker="#error_reasons">Error Reasons for Code-Loading Functions</seeerl> for a description of other possible error reasons.</p>
</desc>
</func>
<func>
- <name name="is_loaded" arity="1" since=""/>
- <fsummary>Check if a module is loaded.</fsummary>
- <type name="loaded_filename"/>
- <type name="loaded_ret_atoms"/>
- <type_desc name="loaded_filename"><c><anno>Filename</anno></c> is an absolute
- filename.</type_desc>
+ <name name="ensure_modules_loaded" arity="1" since="OTP 19.0"/>
+ <fsummary>Ensure that a list of modules is loaded</fsummary>
<desc>
- <p>Checks if <c><anno>Module</anno></c> is loaded. If it is,
- <c>{file, <anno>Loaded</anno>}</c> is returned, otherwise <c>false</c>.</p>
- <p>Normally, <c><anno>Loaded</anno></c> is the absolute filename
- <c>Filename</c> from which the code is obtained. If the module
- is preloaded (see
- <seefile marker="sasl:script"><c>script(4)</c></seefile>),
- <c>Loaded==preloaded</c>. If the module is Cover-compiled (see
- <seeerl marker="tools:cover"><c>cover(3)</c></seeerl>),
- <c>Loaded==cover_compiled</c>.</p>
+ <p>Tries to load any modules not already loaded in the list
+ <c><anno>Modules</anno></c> in the same way as
+ <seemfa marker="#load_file/1">load_file/1</seemfa>.</p>
+ <p>Returns <c>ok</c> if successful, or
+ <c>{error,[{Module,Reason}]}</c> if loading of some modules fails.
+ See <seeerl marker="#error_reasons">Error Reasons for Code-Loading Functions</seeerl> for a description of other possible error reasons.</p>
</desc>
</func>
<func>
- <name name="all_available" arity="0" since="OTP 23.0"/>
- <fsummary>Get all available modules.</fsummary>
- <type name="loaded_filename"/>
- <type name="loaded_ret_atoms"/>
- <type_desc name="loaded_filename"><c><anno>Filename</anno></c> is an absolute
- filename.</type_desc>
+ <name name="finish_loading" arity="1" since="OTP 19.0"/>
+ <fsummary>Finish loading a list of prepared modules atomically</fsummary>
<desc>
- <p>Returns a list of tuples <c>{<anno>Module</anno>, <anno>Filename</anno>,
- <anno>Loaded</anno>}</c> for all available modules. A module is considered
- to be available if it either is loaded or would be loaded if called.
- <c><anno>Filename</anno></c> is normally the absolute filename, as described for
- <seemfa marker="#is_loaded/1"><c>is_loaded/1</c></seemfa>.</p>
+ <p>Tries to load code for all modules that have been previously
+ prepared by
+ <seemfa marker="#prepare_loading/1">prepare_loading/1</seemfa>.
+ The loading occurs atomically, meaning that
+ either all modules are loaded at the same time, or
+ none of the modules are loaded.</p>
+ <p>This function can fail with one of the following error reasons:</p>
+ <taglist>
+ <tag><c>not_purged</c></tag>
+ <item>
+ <p>The object code cannot be loaded because an old version
+ of the code already exists.</p>
+ </item>
+ <tag><c>sticky_directory</c></tag>
+ <item>
+ <p>The object code resides in a sticky directory.</p>
+ </item>
+ <tag><c>pending_on_load</c></tag>
+ <item>
+ <p>A previously loaded module contains an
+ <c>-on_load</c> function that never finished.</p>
+ </item>
+ </taglist>
</desc>
</func>
<func>
- <name name="all_loaded" arity="0" since=""/>
- <fsummary>Get all loaded modules.</fsummary>
- <type name="loaded_filename"/>
- <type name="loaded_ret_atoms"/>
- <type_desc name="loaded_filename"><c><anno>Filename</anno></c> is an absolute
- filename.</type_desc>
+ <name name="get_doc" arity="1" since="OTP 23.0"/>
+ <fsummary>Gets the documentation for a module.</fsummary>
<desc>
- <p>Returns a list of tuples <c>{<anno>Module</anno>, <anno>Loaded</anno>}</c> for all
- loaded modules. <c><anno>Loaded</anno></c> is normally the absolute filename,
- as described for
- <seemfa marker="#is_loaded/1"><c>is_loaded/1</c></seemfa>.</p>
+ <p>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
+ <c>{error,missing}</c>.
+ </p>
+ <p>For more information about the documentation chunk see
+ <seeguide marker="kernel:eep48_chapter">Documentation Storage and Format</seeguide>
+ in Kernel's User's Guide.</p>
</desc>
</func>
<func>
- <name name="which" arity="1" since=""/>
- <fsummary>The object code file of a module.</fsummary>
- <type name="loaded_filename"/>
- <type name="loaded_ret_atoms"/>
+ <name name="get_mode" arity="0" since="OTP R16B"/>
+ <fsummary>The mode of the code server.</fsummary>
<desc>
- <p>If the module is not loaded, this function searches the code
- path for the first file containing object code for
- <c><anno>Module</anno></c> and returns the absolute filename.</p>
- <p>If the module is loaded, it returns the name of the file
- containing the loaded object code.</p>
- <p>If the module is preloaded, <c>preloaded</c> is returned.</p>
- <p>If the module is Cover-compiled, <c>cover_compiled</c> is returned.</p>
- <p>If the module cannot be found, <c>non_existing</c> is returned.</p>
+ <p>Returns an atom describing the mode of the code server:
+ <c>interactive</c> or <c>embedded</c>.</p>
+ <p>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
+ <seemfa marker="#load_binary/3"><c>load_binary/3</c></seemfa>.</p>
</desc>
</func>
<func>
@@ -846,30 +685,40 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
</desc>
</func>
<func>
- <name name="get_doc" arity="1" since="OTP 23.0"/>
- <fsummary>Gets the documentation for a module.</fsummary>
+ <name name="get_path" arity="0" since=""/>
+ <fsummary>Return the code server search path.</fsummary>
<desc>
- <p>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
- <c>{error,missing}</c>.
- </p>
- <p>For more information about the documentation chunk see
- <seeguide marker="kernel:eep48_chapter">Documentation Storage and Format</seeguide>
- in Kernel's User's Guide.</p>
+ <p>Returns the code path.</p>
</desc>
</func>
<func>
- <name name="root_dir" arity="0" since=""/>
- <fsummary>Root directory of Erlang/OTP.</fsummary>
+ <name name="is_loaded" arity="1" since=""/>
+ <fsummary>Check if a module is loaded.</fsummary>
+ <type name="loaded_filename"/>
+ <type name="loaded_ret_atoms"/>
+ <type_desc name="loaded_filename"><c><anno>Filename</anno></c> is an absolute
+ filename.</type_desc>
<desc>
- <p>Returns the root directory of Erlang/OTP, which is
- the directory where it is installed.</p>
- <p><em>Example:</em></p>
- <pre>
-> <input>code:root_dir().</input>
-"/usr/local/otp"</pre>
+ <p>Checks if <c><anno>Module</anno></c> is loaded. If it is,
+ <c>{file, <anno>Loaded</anno>}</c> is returned, otherwise <c>false</c>.</p>
+ <p>Normally, <c><anno>Loaded</anno></c> is the absolute filename
+ <c>Filename</c> from which the code is obtained. If the module
+ is preloaded (see
+ <seefile marker="sasl:script"><c>script(4)</c></seefile>),
+ <c>Loaded==preloaded</c>. If the module is Cover-compiled (see
+ <seeerl marker="tools:cover"><c>cover(3)</c></seeerl>),
+ <c>Loaded==cover_compiled</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name name="is_sticky" arity="1" since=""/>
+ <fsummary>Test if a module is sticky.</fsummary>
+ <desc>
+ <p>Returns <c>true</c> if <c><anno>Module</anno></c> 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 <c>false</c> if <c><anno>Module</anno></c> is not a loaded module or is
+ not sticky.</p>
</desc>
</func>
<func>
@@ -938,77 +787,66 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
</desc>
</func>
<func>
- <name name="compiler_dir" arity="0" since=""/>
- <fsummary>Library directory for the compiler.</fsummary>
- <desc>
- <p>Returns the compiler library directory. Equivalent to
- <c>code:lib_dir(compiler)</c>.</p>
- </desc>
- </func>
- <func>
- <name name="priv_dir" arity="1" since=""/>
- <fsummary>Priv directory for an application.</fsummary>
- <desc>
- <p>Returns the path to the <c>priv</c> directory in an
- application. Equivalent to <c>code:lib_dir(<anno>Name</anno>, priv)</c>.</p>
-
- <warning><p>For backward compatibility, <c><anno>Name</anno></c> is also allowed to
- be a string. That will probably change in a future release.</p></warning>
- </desc>
- </func>
- <func>
- <name name="objfile_extension" arity="0" since=""/>
- <fsummary>Object code file extension.</fsummary>
- <desc>
- <p>Returns the object code file extension corresponding to
- the Erlang machine used, namely <c>.beam</c>.</p>
- </desc>
- </func>
- <func>
- <name name="stick_dir" arity="1" since=""/>
- <fsummary>Mark a directory as sticky.</fsummary>
- <desc>
- <p>Marks <c><anno>Dir</anno></c> as sticky.</p>
- <p>Returns <c>ok</c> if successful, otherwise <c>error</c>.</p>
- </desc>
- </func>
- <func>
- <name name="unstick_dir" arity="1" since=""/>
- <fsummary>Remove a sticky directory mark.</fsummary>
+ <name name="load_abs" arity="1" since=""/>
+ <fsummary>Load a module, residing in a specified file.</fsummary>
+ <type name="load_ret"/>
+ <type name="loaded_filename"/>
+ <type name="loaded_ret_atoms"/>
<desc>
- <p>Unsticks a directory that is marked as
- sticky.</p>
- <p>Returns <c>ok</c> if successful, otherwise <c>error</c>.</p>
+ <p>Same as <c>load_file(<anno>Module</anno>)</c>, but
+ <c><anno>Filename</anno></c> is an absolute or
+ relative filename. The code path is not searched. It returns
+ a value in the same way as
+ <seemfa marker="#load_file/1"><c>load_file/1</c></seemfa>. Notice
+ that <c><anno>Filename</anno></c> must not contain the extension (for
+ example, <c>.beam</c>) because <c>load_abs/1</c> adds the correct
+ extension.</p>
</desc>
</func>
<func>
- <name name="is_sticky" arity="1" since=""/>
- <fsummary>Test if a module is sticky.</fsummary>
+ <name name="load_binary" arity="3" since=""/>
+ <fsummary>Load object code for a module.</fsummary>
+ <type name="loaded_filename"/>
+ <type name="loaded_ret_atoms"/>
<desc>
- <p>Returns <c>true</c> if <c><anno>Module</anno></c> 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 <c>false</c> if <c><anno>Module</anno></c> is not a loaded module or is
- not sticky.</p>
+ <p>This function can be used to load object code on remote
+ Erlang nodes. Argument <c><anno>Binary</anno></c> must contain
+ object code for <c><anno>Module</anno></c>.
+ <c><anno>Filename</anno></c> is only used by the code server to keep a
+ record of from which file the object code for <c><anno>Module</anno></c>
+ comes. Thus, <c><anno>Filename</anno></c> is not opened and read by
+ the code server.</p>
+ <p>Returns <c>{module, <anno>Module</anno>}</c> if successful, or
+ <c>{error, Reason}</c> if loading fails.
+ See <seeerl marker="#error_reasons">Error Reasons for Code-Loading Functions</seeerl> for a description of the possible error reasons.</p>
</desc>
</func>
<func>
- <name name="where_is_file" arity="1" since=""/>
- <fsummary>Full name of a file located in the code path.</fsummary>
+ <name name="load_file" arity="1" since=""/>
+ <fsummary>Load a module.</fsummary>
+ <type name="load_ret"/>
<desc>
- <p>Searches the code path for <c><anno>Filename</anno></c>, a file of
- arbitrary type. If found, the full name is returned.
- <c>non_existing</c> is returned if the file cannot be found.
- The function can be useful, for example, to locate
- application resource files.</p>
+ <p>Tries to load the Erlang module <c><anno>Module</anno></c>, using
+ the code path. It looks for the object code file with an
+ extension corresponding to the Erlang machine used, for
+ example, <c><anno>Module</anno>.beam</c>. The loading fails if the module
+ name found in the object code differs from the name
+ <c><anno>Module</anno></c>.
+ <seemfa marker="#load_binary/3"><c>load_binary/3</c></seemfa> must
+ be used to load object code with a module name that is
+ different from the file name.</p>
+ <p>Returns <c>{module, <anno>Module</anno>}</c> if successful, or
+ <c>{error, Reason}</c> if loading fails.
+ See <seeerl marker="#error_reasons">Error Reasons for Code-Loading Functions</seeerl> for a description of the possible error reasons.</p>
</desc>
</func>
<func>
- <name name="clash" arity="0" since=""/>
- <fsummary>Search for modules with identical names.</fsummary>
+ <name name="modified_modules" arity="0" since="OTP 20.0"/>
+ <fsummary>Return a list of all modules modified on disk.</fsummary>
<desc>
- <p>Searches all directories in the code path for module names with
- identical names and writes a report to <c>stdout</c>.</p>
+ <p>Returns the list of all currently loaded modules for which
+ <seemfa marker="#module_status/1"><c>module_status/1</c></seemfa>
+ returns <c>modified</c>. See also <seemfa marker="#all_loaded/0"><c>all_loaded/0</c></seemfa>.</p>
</desc>
</func>
<func>
@@ -1049,25 +887,187 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
</desc>
</func>
<func>
- <name name="modified_modules" arity="0" since="OTP 20.0"/>
- <fsummary>Return a list of all modules modified on disk.</fsummary>
+ <name name="objfile_extension" arity="0" since=""/>
+ <fsummary>Object code file extension.</fsummary>
<desc>
- <p>Returns the list of all currently loaded modules for which
- <seemfa marker="#module_status/1"><c>module_status/1</c></seemfa>
- returns <c>modified</c>. See also <seemfa marker="#all_loaded/0"><c>all_loaded/0</c></seemfa>.</p>
+ <p>Returns the object code file extension corresponding to
+ the Erlang machine used, namely <c>.beam</c>.</p>
</desc>
</func>
<func>
- <name name="get_mode" arity="0" since="OTP R16B"/>
- <fsummary>The mode of the code server.</fsummary>
+ <name name="prepare_loading" arity="1" since="OTP 19.0"/>
+ <fsummary>Prepare a list of modules atomically</fsummary>
<desc>
- <p>Returns an atom describing the mode of the code server:
- <c>interactive</c> or <c>embedded</c>.</p>
- <p>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
- <seemfa marker="#load_binary/3"><c>load_binary/3</c></seemfa>.</p>
+ <p>Prepares to load the modules in the list
+ <c><anno>Modules</anno></c>.
+ Finish the loading by calling
+ <seemfa marker="#finish_loading/1">finish_loading(Prepared)</seemfa>.</p>
+ <p>This function can fail with one of the following error reasons:</p>
+ <taglist>
+ <tag><c>badfile</c></tag>
+ <item>
+ <p>The object code has an incorrect format or the module
+ name in the object code is not the expected module name.</p>
+ </item>
+ <tag><c>nofile</c></tag>
+ <item>
+ <p>No file with object code exists.</p>
+ </item>
+ <tag><c>on_load_not_allowed</c></tag>
+ <item>
+ <p>A module contains an
+ <seeguide marker="system/reference_manual:code_loading#on_load">-on_load function</seeguide>.</p>
+ </item>
+ <tag><c>duplicated</c></tag>
+ <item>
+ <p>A module is included more than once in
+ <c><anno>Modules</anno></c>.</p>
+ </item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name name="priv_dir" arity="1" since=""/>
+ <fsummary>Priv directory for an application.</fsummary>
+ <desc>
+ <p>Returns the path to the <c>priv</c> directory in an
+ application. Equivalent to <c>code:lib_dir(<anno>Name</anno>, priv)</c>.</p>
+
+ <warning><p>For backward compatibility, <c><anno>Name</anno></c> is also allowed to
+ be a string. That will probably change in a future release.</p></warning>
+ </desc>
+ </func>
+ <func>
+ <name name="purge" arity="1" since=""/>
+ <fsummary>Remove old code for a module.</fsummary>
+ <desc>
+ <p>Purges the code for <c><anno>Module</anno></c>, 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.</p>
+ <note><p>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
+ <seemfa marker="erts:erlang#check_process_code/3"><c>erlang:check_process_code/3</c></seemfa>,
+ which is used in order to determine this.</p></note>
+ <p>Returns <c>true</c> if successful and any process is needed to
+ be killed, otherwise <c>false</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name name="replace_path" arity="2" since=""/>
+ <name name="replace_path" arity="3" since="OTP 26.0"/>
+ <fsummary>Replace a directory with another in the code path.</fsummary>
+ <desc>
+ <p>Replaces an old occurrence of a directory
+ named <c>.../<anno>Name</anno>[-Vsn][/ebin]</c> in the code path, with
+ <c><anno>Dir</anno></c>. If <c><anno>Name</anno></c> does not exist, it adds
+ the new directory <c><anno>Dir</anno></c> last in the code path. The new
+ directory must also be named <c>.../<anno>Name</anno>[-Vsn][/ebin]</c>.
+ This function is to be used if a new version of the directory (library) is
+ added to a running system.</p>
+ <p>An optional third argument may be set to the atom <c>cache</c> to
+ control if the contents of the directory must be cached on first traversal.
+ Defaults to <c>nocache</c>.</p>
+ <p>Returns:</p>
+ <taglist>
+ <tag><c>true</c></tag>
+ <item><p>If successful</p></item>
+ <tag><c>{error, bad_name}</c></tag>
+ <item><p>If <c><anno>Name</anno></c> is not found</p></item>
+ <tag><c>{error, bad_directory}</c></tag>
+ <item><p>If <c><anno>Dir</anno></c> does not exist</p></item>
+ <tag><c>{error, {badarg, [<anno>Name</anno>, <anno>Dir</anno>]}}</c></tag>
+ <item><p>If <c><anno>Name</anno></c> or <c><anno>Dir</anno></c> is invalid</p></item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name name="root_dir" arity="0" since=""/>
+ <fsummary>Root directory of Erlang/OTP.</fsummary>
+ <desc>
+ <p>Returns the root directory of Erlang/OTP, which is
+ the directory where it is installed.</p>
+ <p><em>Example:</em></p>
+ <pre>
+> <input>code:root_dir().</input>
+"/usr/local/otp"</pre>
+ </desc>
+ </func>
+ <func>
+ <name name="set_path" arity="1" since=""/>
+ <name name="set_path" arity="2" since="OTP 26.0"/>
+ <fsummary>Set the code server search path.</fsummary>
+ <desc>
+ <p>Sets the code path to the list of directories <c><anno>Path</anno></c>.</p>
+ <p>An optional second argument may be set to the atom <c>cache</c> to
+ control if the contents of the directory must be cached on first traversal.
+ Defaults to <c>nocache</c>.</p>
+ <p>Returns:</p>
+ <taglist>
+ <tag><c>true</c></tag>
+ <item><p>If successful</p></item>
+ <tag><c>{error, bad_directory}</c></tag>
+ <item><p>If any <c><anno>Dir</anno></c> is not a directory name</p></item>
+ </taglist>
+ </desc>
+ </func>
+ <func>
+ <name name="soft_purge" arity="1" since=""/>
+ <fsummary>Remove old code for a module, unless no process uses it.</fsummary>
+ <desc>
+ <p>Purges the code for <c><anno>Module</anno></c>, that is, removes code
+ marked as old, but only if no processes linger in it.</p>
+ <note><p>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
+ <seemfa marker="erts:erlang#check_process_code/3"><c>erlang:check_process_code/3</c></seemfa>,
+ which is used in order to determine this.</p></note>
+ <p>Returns <c>false</c> if the module cannot be purged because
+ of processes lingering in old code, otherwise <c>true</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name name="stick_dir" arity="1" since=""/>
+ <fsummary>Mark a directory as sticky.</fsummary>
+ <desc>
+ <p>Marks <c><anno>Dir</anno></c> as sticky.</p>
+ <p>Returns <c>ok</c> if successful, otherwise <c>error</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name name="unstick_dir" arity="1" since=""/>
+ <fsummary>Remove a sticky directory mark.</fsummary>
+ <desc>
+ <p>Unsticks a directory that is marked as
+ sticky.</p>
+ <p>Returns <c>ok</c> if successful, otherwise <c>error</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name name="where_is_file" arity="1" since=""/>
+ <fsummary>Full name of a file located in the code path.</fsummary>
+ <desc>
+ <p>Searches the code path for <c><anno>Filename</anno></c>, a file of
+ arbitrary type. If found, the full name is returned.
+ <c>non_existing</c> is returned if the file cannot be found.
+ The function can be useful, for example, to locate
+ application resource files.</p>
+ </desc>
+ </func>
+ <func>
+ <name name="which" arity="1" since=""/>
+ <fsummary>The object code file of a module.</fsummary>
+ <type name="loaded_filename"/>
+ <type name="loaded_ret_atoms"/>
+ <desc>
+ <p>If the module is not loaded, this function searches the code
+ path for the first file containing object code for
+ <c><anno>Module</anno></c> and returns the absolute filename.</p>
+ <p>If the module is loaded, it returns the name of the file
+ containing the loaded object code.</p>
+ <p>If the module is preloaded, <c>preloaded</c> is returned.</p>
+ <p>If the module is Cover-compiled, <c>cover_compiled</c> is returned.</p>
+ <p>If the module cannot be found, <c>non_existing</c> is returned.</p>
</desc>
</func>
</funcs>
--
2.35.3
