aboutsummaryrefslogtreecommitdiffstats
path: root/lib/kernel/doc/src/code.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/kernel/doc/src/code.xml')
-rw-r--r--lib/kernel/doc/src/code.xml571
1 files changed, 299 insertions, 272 deletions
diff --git a/lib/kernel/doc/src/code.xml b/lib/kernel/doc/src/code.xml
index 819da544c3..7598b22d79 100644
--- a/lib/kernel/doc/src/code.xml
+++ b/lib/kernel/doc/src/code.xml
@@ -29,238 +29,240 @@
<rev></rev>
</header>
<module>code</module>
- <modulesummary>Erlang Code Server</modulesummary>
+ <modulesummary>Erlang code server.</modulesummary>
<description>
<p>This module contains the interface to the Erlang
<em>code server</em>, which deals with the loading of compiled
code into a running Erlang runtime system.</p>
- <p>The runtime system can be started in either <em>embedded</em> or
- <em>interactive</em> mode. Which one is decided by the command
- line flag <c>-mode</c>.</p>
+ <p>The runtime system can be started in <em>embedded</em> or
+ <em>interactive</em> mode. Which one is decided by command-line
+ flag <c>-mode</c>:</p>
<pre>
% <input>erl -mode interactive</input></pre>
- <p>Default mode is <c>interactive</c>.</p>
+ <p>The modes are as follows:</p>
<list type="bulleted">
<item>
- <p>In embedded mode, all code is loaded during system start-up
+ <p>In embedded mode, all code is loaded during system startup
according to the boot script. (Code can also be loaded later
by explicitly ordering the code server to do so).</p>
</item>
<item>
- <p>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
+ <p>In interactive mode, which is default, only some code is loaded
+ during system startup, basically the modules needed by the runtime
+ system. 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.</p>
</item>
</list>
- <p>To prevent accidentally reloading modules affecting the Erlang
- runtime system itself, the <c>kernel</c>, <c>stdlib</c> and
- <c>compiler</c> directories are considered <em>sticky</em>. This
+ <p>To prevent accidentally reloading of modules affecting the Erlang
+ runtime system, directories <c>kernel</c>, <c>stdlib</c>,
+ and <c>compiler</c> are considered <em>sticky</em>. 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
+ The feature can be disabled by using command-line flag
<c>-nostick</c>.</p>
</description>
<section>
<title>Code Path</title>
- <p>In interactive mode, the code server maintains a search path --
- usually called the <em>code path</em> -- consisting of a list of
+ <p>In interactive mode, the code server maintains a search path,
+ usually called the <em>code path</em>, consisting of a list of
directories, which it searches sequentially when trying to load a
module.</p>
<p>Initially, the code path consists of the current working
- directory and all Erlang object code directories under the library
+ directory and all Erlang object code directories under library
directory <c>$OTPROOT/lib</c>, where <c>$OTPROOT</c> is
the installation directory of Erlang/OTP, <c>code:root_dir()</c>.
Directories can be named <c>Name[-Vsn]</c> and the code server,
by default, chooses the directory with the highest version number
- among those which have the same <c>Name</c>. The <c>-Vsn</c>
- suffix is optional. If an <c>ebin</c> directory exists under
- <c>Name[-Vsn]</c>, it is this directory which is added to
- the code path.</p>
- <p>The environment variable <c>ERL_LIBS</c> (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 <c>ebin</c> directory will be ignored.</p>
+ among those having the same <c>Name</c>. Suffix <c>-Vsn</c>
+ is optional. If an <c>ebin</c> directory exists under
+ <c>Name[-Vsn]</c>, this directory is added to the code path.</p>
+ <p>Environment variable <c>ERL_LIBS</c> (defined in the operating
+ system) can be used to define more library directories to
+ be handled in the same way as the standard OTP library
+ directory described above, except that directories without
+ an <c>ebin</c> directory are ignored.</p>
<p>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.</p>
- <p>The environment variable <c>ERL_LIBS</c> (if defined) should contain
+ appears before the standard OTP applications, except for the
+ <c>Kernel</c> and <c>STDLIB</c> applications, which are placed before
+ any additional applications. In other words, modules found in any
+ of the additional library directories override modules with
+ the same name in OTP, except for modules in <c>Kernel</c> and
+ <c>STDLIB</c>.</p>
+ <p>Environment variable <c>ERL_LIBS</c> (if defined) is to contain
a colon-separated (for Unix-like systems) or semicolon-separated
(for Windows) list of additional libraries.</p>
- <p>Example: On an Unix-like system, <c>ERL_LIBS</c> could be set to
- <c>/usr/local/jungerl:/home/some_user/my_erlang_lib</c>. (On Windows,
- use semi-colon as separator.)</p>
+ <p><em>Example:</em></p>
+ <p>On a Unix-like system, <c>ERL_LIBS</c> can be set to the following</p>
+ <code>
+/usr/local/jungerl:/home/some_user/my_erlang_lib</code>
+ <p>On Windows, use semi-colon as separator.</p>
</section>
<section>
<title>Loading of Code From Archive Files</title>
- <warning><p>The support for loading of code from archive files is
- experimental. The sole purpose of releasing it before it is ready
+ <warning><p>The support for loading code from archive files is
+ experimental. The purpose of releasing it before it is ready
is to obtain early feedback. The file format, semantics,
- interfaces etc. may be changed in a future release. The function
- <c>lib_dir/2</c> and the flag <c>-code_path_choice</c> are also
+ interfaces, and so on, can be changed in a future release. The function
+ <seealso marker="#lib_dir/2"><c>lib_dir/2</c></seealso>
+ and flag <c>-code_path_choice</c> are also
experimental.</p></warning>
- <p>In the current implementation, Erlang archives are <c>ZIP</c>
- files with <c>.ez</c> extension. Erlang archives may also be
+ <p>The Erlang archives are <c>ZIP</c>
+ files with extension <c>.ez</c>. Erlang archives can also be
enclosed in <c>escript</c> files whose file extension is arbitrary.</p>
- <p>Erlang archive files may contain entire Erlang applications or
+ <p>Erlang archive files can contain entire Erlang applications or
parts of applications. The structure in an archive file is the
- same as the directory structure for an application. If you for
- example would create an archive of <c>mnesia-4.4.7</c>, the
+ same as the directory structure for an application. If you, for
+ example, create an archive of <c>mnesia-4.4.7</c>, the
archive file must be named <c>mnesia-4.4.7.ez</c> and it must
- contain a top directory with the name <c>mnesia-4.4.7</c>. If the
+ contain a top directory named <c>mnesia-4.4.7</c>. If the
version part of the name is omitted, it must also be omitted in
the archive. That is, a <c>mnesia.ez</c> archive must contain a
<c>mnesia</c> top directory.</p>
- <p>An archive file for an application may for example be
+ <p>An archive file for an application can, for example, be
created like this:</p>
<pre>
- zip:create("mnesia-4.4.7.ez",
- ["mnesia-4.4.7"],
- [{cwd, code:lib_dir()},
- {compress, all},
- {uncompress,[".beam",".app"]}]).</pre>
-
- <p>Any file in the archive may be compressed, but in order to
- speed up the access of frequently read files, it may be a good
+zip:create("mnesia-4.4.7.ez",
+ ["mnesia-4.4.7"],
+ [{cwd, code:lib_dir()},
+ {compress, all},
+ {uncompress,[".beam",".app"]}]).</pre>
+
+ <p>Any file in the archive can be compressed, but to
+ speed up the access of frequently read files, it can be a good
idea to store <c>beam</c> and <c>app</c> files uncompressed in
the archive.</p>
- <p>Normally the top directory of an application is located either
- in the library directory <c>$OTPROOT/lib</c> or in a directory
- referred to by the environment variable <c>ERL_LIBS</c>. At
- startup when the initial code path is computed, the code server
- will also look for archive files in these directories and
- possibly add <c>ebin</c> directories in archives to the code path. The
- code path will then contain paths to directories that looks like
+ <p>Normally the top directory of an application is located
+ in library directory <c>$OTPROOT/lib</c> or in a directory
+ referred to by environment variable <c>ERL_LIBS</c>. At
+ startup, when the initial code path is computed, the code server
+ also looks for archive files in these directories and
+ possibly adds <c>ebin</c> directories in archives to the code path. The
+ code path then contains paths to directories that look like
<c>$OTPROOT/lib/mnesia.ez/mnesia/ebin</c> or
<c>$OTPROOT/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin</c>.</p>
- <p>The code server uses the module <c>erl_prim_loader</c>
- (possibly via the <c>erl_boot_server</c>) to read code files from
- archives. But the functions in <c>erl_prim_loader</c> may also be
+ <p>The code server uses module <c>erl_prim_loader</c> in <c>ERTS</c>
+ (possibly through <c>erl_boot_server</c>) to read code files from
+ archives. However, the functions in <c>erl_prim_loader</c> can also be
used by other applications to read files from archives. For
example, the call
<c>erl_prim_loader:list_dir( "/otp/root/lib/mnesia-4.4.7.ez/mnesia-4.4.7/examples/bench)"</c>
would list the contents of a directory inside an archive.
- See <seealso marker="erts:erl_prim_loader">erl_prim_loader(3)</seealso>.</p>
+ See <seealso marker="erts:erl_prim_loader"><c>erl_prim_loader(3)</c></seealso>.</p>
<p>An application archive file and a regular application directory
- may coexist. This may be useful when there is a need of having
+ can coexist. This can be useful when it is needed to have
parts of the application as regular files. A typical case is the
- <c>priv</c> directory which must reside as a regular directory in
- order to be able to dynamically link in drivers and start port
- programs. For other applications that do not have this need, the
- <c>priv</c> directory may reside in the archive and the files
- under the <c>priv</c> directory may be read via the
+ <c>priv</c> directory, which must reside as a regular directory
+ to link in drivers dynamically and start port programs.
+ For other applications that do not need this, directory
+ <c>priv</c> can reside in the archive and the files
+ under the directory <c>priv</c> can be read through
<c>erl_prim_loader</c>.</p>
- <p>At the time point when a directory is added to the code path as
- well as when the entire code path is (re)set, the code server
- will decide which subdirectories in an application that shall be
- read from the archive and which that shall be read as regular
+ <p>When a directory is added to the code path and
+ when the entire code path is (re)set, the code server
+ decides which subdirectories in an application that are to be
+ read from the archive and which that are to be read as regular
files. If directories are added or removed afterwards, the file
- access may fail if the code path is not updated (possibly to the
- same path as before in order to trigger the directory resolution
- update). For each directory on the second level (ebin, priv, src
- etc.) in the application archive, the code server will firstly
- choose the regular directory if it exists and secondly from the
- archive. The function
- <c>code:lib_dir/2</c> returns the path to the subdirectory. For
- example <c>code:lib_dir(megaco,ebin)</c> may return
+ access can fail if the code path is not updated (possibly to the
+ same path as before, to trigger the directory resolution
+ update).</p>
+
+ <p>For each directory on the second level in the application archive
+ (<c>ebin</c>, <c>priv</c>, <c>src</c>, and so on), the code server first
+ chooses the regular directory if it exists and second from the
+ archive. Function <c>code:lib_dir/2</c> returns the path to the
+ subdirectory. For example, <c>code:lib_dir(megaco,ebin)</c> can return
<c>/otp/root/lib/megaco-3.9.1.1.ez/megaco-3.9.1.1/ebin</c> while
- <c>code:lib_dir(megaco,priv)</c> may return
+ <c>code:lib_dir(megaco,priv)</c> can return
<c>/otp/root/lib/megaco-3.9.1.1/priv</c>.</p>
<p>When an <c>escript</c> file contains an archive, there are
- neither restrictions on the name of the <c>escript</c> nor on how
- many applications that may be stored in the embedded
- archive. Single <c>beam</c> files may also reside on the top
- level in the archive. At startup, both the top directory in the
- embedded archive as well as all (second level) <c>ebin</c>
+ no restrictions on the name of the <c>escript</c> and no restrictions
+ on how many applications that can be stored in the embedded
+ archive. Single Beam files can also reside on the top
+ level in the archive. At startup, the top directory in the
+ embedded archive and all (second level) <c>ebin</c>
directories in the embedded archive are added to the code path.
- See <seealso marker="erts:escript">escript(1)</seealso></p>
+ See <seealso marker="erts:escript"><c>erts:escript(1)</c></seealso>.</p>
<p>When the choice of directories in the code path is
- <c>strict</c>, the directory that ends up in the code path will
- be exactly the stated one. This means that if for example the
+ <c>strict</c>, the directory that ends up in the code path is
+ exactly the stated one. This means that if, for example, the
directory <c>$OTPROOT/lib/mnesia-4.4.7/ebin</c> is explicitly
- added to the code path, the code server will not load files from
- <c>$OTPROOT/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin</c> and vice
- versa. </p>
+ added to the code path, the code server does not load files from
+ <c>$OTPROOT/lib/mnesia-4.4.7.ez/mnesia-4.4.7/ebin</c>.</p>
- <p>This behavior can be controlled via the command line flag
+ <p>This behavior can be controlled through command-line flag
<c>-code_path_choice Choice</c>. If the flag is set to <c>relaxed</c>,
- the code server will instead choose a suitable directory
- depending on the actual file structure. If there exists a regular
- application ebin directory, it will be chosen. But if it does
- not exist, the ebin directory in the archive is chosen if it
- exists. If neither of them exists the original directory will be
+ the code server instead chooses a suitable directory
+ depending on the actual file structure. If a regular
+ application <c>ebin</c> directory exists, it is chosen. Otherwise,
+ the directory <c>ebin</c> in the archive is chosen if it
+ exists. If neither of them exists, the original directory is
chosen.</p>
- <p>The command line flag <c>-code_path_choice Choice</c> does also
- affect how <c>init</c> interprets the <c>boot script</c>. The
- interpretation of the explicit code paths in the <c>boot
- script</c> may be <c>strict</c> or <c>relaxed</c>. It is
- particular useful to set the flag to <c>relaxed</c> when you want
- to elaborate with code loading from archives without editing the
+ <p>Command-line flag <c>-code_path_choice Choice</c> also
+ affects how module <c>init</c> interprets the <c>boot script</c>.
+ The interpretation of the explicit code paths in the <c>boot
+ script</c> can be <c>strict</c> or <c>relaxed</c>. It is
+ particularly useful to set the flag to <c>relaxed</c> when
+ elaborating with code loading from archives without editing the
<c>boot script</c>. The default is <c>relaxed</c>. See <seealso
- marker="erts:init">init(3)</seealso></p></section>
+ marker="erts:init"><c>erts:init(3)</c></seealso>.</p></section>
<section>
<title>Current and Old Code</title>
- <p>The code of a module can exists in two variants in a system:
+ <p>The code for a module can exist in two variants in a system:
<em>current code</em> and <em>old code</em>. When a module is
- loaded into the system for the first time, the code of the module
+ loaded into the system for the first time, the module code
becomes 'current' and the global <em>export table</em> is updated
with references to all functions exported from the module.</p>
- <p>If then a new instance of the module is loaded (perhaps because
- of the correction of an error), then the code of the previous
+ <p>If then a new instance of the module is loaded (for example, because of
+ error correction), 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'.</p>
- <p>Both old and current code for a module are valid, and may even be
+ the previous instance are removed. After that, the new instance is
+ loaded as for the first time, and becomes 'current'.</p>
+ <p>Both old and current code for a module are valid, and can 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
+ in old code are unavailable. Hence, a global call cannot be made
+ to an exported function in old code, but old code can
still be evaluated because of processes lingering in it.</p>
- <p>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
+ <p>If a third instance of the module is loaded, the code server
+ removes (purges) the old code and any processes lingering in it
+ are terminated. Then the third instance becomes 'current' and
the previously current code becomes 'old'.</p>
<p>For more information about old and current code, and how to
- make a process switch from old to current code, refer to
+ make a process switch from old to current code, see section
+ Compilation and Code Loading in the
<seealso marker="doc/reference_manual:code_loading">Erlang Reference Manual</seealso>.</p>
</section>
<section>
<title>Argument Types and Invalid Arguments</title>
- <p>Generally, module and application names are atoms, while file and directory
+ <p>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.</p>
- <p>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 the type of the argument
- was correct, but there was some other error (for instance, a non-existing directory
- was given to <c>set_path/1</c>).</p>
+ <p>As from Erlang/OTP R12B, functions in this module generally fail with an
+ exception if they are passed an incorrect type (for example, an integer or a tuple
+ where an atom is expected). An error tuple is returned if the argument type
+ is correct, but there are some other errors (for example, a non-existing directory
+ is specified to <c>set_path/1</c>).</p>
</section>
<section>
@@ -312,33 +314,36 @@
</datatype>
<datatype>
<name name="prepared_code"/>
- <desc>An opaque term holding prepared code.</desc>
+ <desc><p>An opaque term holding prepared code.</p></desc>
</datatype>
</datatypes>
<funcs>
<func>
<name name="set_path" arity="1"/>
- <fsummary>Set the code server search path</fsummary>
+ <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>Returns <c>true</c> if successful, or
- <c>{error, bad_directory}</c> if any <c><anno>Dir</anno></c> is not
- the name of a directory, or <c>{error, bad_path}</c> if
- the argument is invalid.</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"/>
- <fsummary>Return the code server search path</fsummary>
+ <fsummary>Return the code server search path.</fsummary>
<desc>
- <p>Returns the code path</p>
+ <p>Returns the code path.</p>
</desc>
</func>
<func>
<name name="add_path" arity="1"/>
<name name="add_pathz" arity="1"/>
- <fsummary>Add a directory to the end of the code path</fsummary>
+ <fsummary>Add a directory to the end of the code path.</fsummary>
<type name="add_path_ret"/>
<desc>
<p>Adds <c><anno>Dir</anno></c> to the code path. The directory is added as
@@ -351,11 +356,11 @@
</func>
<func>
<name name="add_patha" arity="1"/>
- <fsummary>Add a directory to the beginning of the code path</fsummary>
+ <fsummary>Add a directory to the beginning of the code path.</fsummary>
<type name="add_path_ret"/>
<desc>
<p>Adds <c><anno>Dir</anno></c> to the beginning of the code path. If
- <c><anno>Dir</anno></c> already exists, it is removed from the old
+ <c><anno>Dir</anno></c> exists, it is removed from the old
position in the code path.</p>
<p>Returns <c>true</c> if successful, or
<c>{error, bad_directory}</c> if <c><anno>Dir</anno></c> is not the name
@@ -365,69 +370,81 @@
<func>
<name name="add_paths" arity="1"/>
<name name="add_pathsz" arity="1"/>
- <fsummary>Add directories to the end of the code path</fsummary>
+ <fsummary>Add directories to the end of the code path.</fsummary>
<desc>
<p>Adds the directories in <c><anno>Dirs</anno></c> to the end of the code
- path. If a <c><anno>Dir</anno></c> already exists, it is not added. This
- function always returns <c>ok</c>, regardless of the validity
+ path. If a <c><anno>Dir</anno></c> exists, it is not added.</p>
+ <p>Always returns <c>ok</c>, regardless of the validity
of each individual <c><anno>Dir</anno></c>.</p>
</desc>
</func>
<func>
<name name="add_pathsa" arity="1"/>
- <fsummary>Add directories to the beginning of the code path</fsummary>
+ <fsummary>Add directories to the beginning of the code path.</fsummary>
<desc>
<p>Adds the directories in <c><anno>Dirs</anno></c> to the beginning of
- the code path. If a <c><anno>Dir</anno></c> already exists, it is removed
- from the old position in the code path. This function always
- returns <c>ok</c>, regardless of the validity of each
+ the code path. If a <c><anno>Dir</anno></c> exists, it is removed
+ from the old position in the code path.</p>
+ <p>Always returns <c>ok</c>, regardless of the validity of each
individual <c><anno>Dir</anno></c>.</p>
</desc>
</func>
<func>
<name name="del_path" arity="1"/>
- <fsummary>Delete a directory from the code path</fsummary>
+ <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. It is also possible to give the complete directory name
- <c><anno>Dir</anno></c> as argument.</p>
- <p>Returns <c>true</c> if successful, or <c>false</c> if
- the directory is not found, or <c>{error, bad_name}</c> if
- the argument is invalid.</p>
+ 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="replace_path" arity="2"/>
- <fsummary>Replace a directory with another in the code path</fsummary>
- <desc>
- <p>This function 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
- should be used if a new version of the directory (library) is
+ <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>Returns <c>true</c> if successful, or
- <c>{error, bad_name}</c> if <c><anno>Name</anno></c> is not found, or
- <c>{error, bad_directory}</c> if <c><anno>Dir</anno></c> does not exist, or
- <c>{error, {badarg, [<anno>Name</anno>, <anno>Dir</anno>]}}</c> if <c><anno>Name</anno></c> or
- <c><anno>Dir</anno></c> is invalid.</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"/>
- <fsummary>Load a module</fsummary>
+ <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 that corresponds to the Erlang machine used, for
- example <c><anno>Module</anno>.beam</c>. The loading fails if the module
+ 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>.
- <seealso marker="#load_binary/3">load_binary/3</seealso> must
+ <seealso marker="#load_binary/3"><c>load_binary/3</c></seealso> 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
@@ -437,45 +454,45 @@
</func>
<func>
<name name="load_abs" arity="1"/>
- <fsummary>Load a module, residing in a given file</fsummary>
+ <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>Does the same as <c>load_file(<anno>Module</anno>)</c>, but
- <c><anno>Filename</anno></c> is either an absolute file name, or a
- relative file name. The code path is not searched. It returns
+ <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
- <seealso marker="#load_file/1">load_file/1</seealso>. Note
- that <c><anno>Filename</anno></c> should not contain the extension (for
- example <c>".beam"</c>); <c>load_abs/1</c> adds the correct
- extension itself.</p>
+ <seealso marker="#load_file/1"><c>load_file/1</c></seealso>. 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"/>
- <fsummary>Ensure that a module is loaded</fsummary>
+ <fsummary>Ensure that a module is loaded.</fsummary>
<desc>
- <p>Tries to to load a module in the same way as
- <seealso marker="#load_file/1">load_file/1</seealso>,
+ <p>Tries to load a module in the same way as
+ <seealso marker="#load_file/1"><c>load_file/1</c></seealso>,
unless the module is already loaded.
- In embedded mode, however, it does not load a module which is not
+ However, in embedded mode it does not load a module that is not
already loaded, but returns <c>{error, embedded}</c> instead.
See <seealso marker="#error_reasons">Error Reasons for Code-Loading Functions</seealso> for a description of other possible error reasons.</p>
</desc>
</func>
<func>
<name name="load_binary" arity="3"/>
- <fsummary>Load object code for a module</fsummary>
+ <fsummary>Load object code for a module.</fsummary>
<type name="loaded_filename"/>
<type name="loaded_ret_atoms"/>
<desc>
<p>This function can be used to load object code on remote
- Erlang nodes. The argument <c><anno>Binary</anno></c> must contain
+ 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. Accordingly, <c><anno>Filename</anno></c> is not opened and read by
+ 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.
@@ -616,92 +633,94 @@ ok = code:finish_loading(Prepared),
</func>
<func>
<name name="delete" arity="1"/>
- <fsummary>Removes current code for a module</fsummary>
+ <fsummary>Remove current code for a module.</fsummary>
<desc>
<p>Removes the current code for <c><anno>Module</anno></c>, that is,
the current code for <c><anno>Module</anno></c> 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.</p>
+ but no external function calls can be made to it.</p>
<p>Returns <c>true</c> if successful, or <c>false</c> if there
- is old code for <c><anno>Module</anno></c> which must be purged first, or
+ is old code for <c><anno>Module</anno></c> that must be purged first, or
if <c><anno>Module</anno></c> is not a (loaded) module.</p>
</desc>
</func>
<func>
<name name="purge" arity="1"/>
- <fsummary>Removes old code for a module</fsummary>
+ <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>
- <p>Returns <c>true</c> if successful and any process needed to
+ <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"/>
- <fsummary>Removes old code for a module, unless no process uses it</fsummary>
+ <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>
- <p>Returns <c>false</c> if the module could not be purged due
- to processes lingering in old code, otherwise <c>true</c>.</p>
+ <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="is_loaded" arity="1"/>
- <fsummary>Check if a module is loaded</fsummary>
+ <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>
+ <type_desc name="loaded_filename"><c><anno>Filename</anno></c> is an absolute
+ filename.</type_desc>
<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 file name
- <c>Filename</c> from which the code was obtained. If the module
+ <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
- <seealso marker="sasl:script">script(4)</seealso>),
- <c>Loaded==preloaded</c>. If the module is Cover compiled (see
- <seealso marker="tools:cover">cover(3)</seealso>),
+ <seealso marker="sasl:script"><c>sasl:script(4)</c></seealso>),
+ <c>Loaded==preloaded</c>. If the module is Cover-compiled (see
+ <seealso marker="tools:cover"><c>tools:cover(3)</c></seealso>),
<c>Loaded==cover_compiled</c>.</p>
</desc>
</func>
<func>
<name name="all_loaded" arity="0"/>
- <fsummary>Get all loaded modules</fsummary>
+ <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>
+ <type_desc name="loaded_filename"><c><anno>Filename</anno></c> is an absolute
+ filename.</type_desc>
<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 file
- name, as described for
- <seealso marker="#is_loaded/1">is_loaded/1</seealso>.</p>
+ loaded modules. <c><anno>Loaded</anno></c> is normally the absolute filename,
+ as described for
+ <seealso marker="#is_loaded/1"><c>is_loaded/1</c></seealso>.</p>
</desc>
</func>
<func>
<name name="which" arity="1"/>
- <fsummary>The object code file of a module</fsummary>
+ <fsummary>The object code file of a module.</fsummary>
<type name="loaded_ret_atoms"/>
<desc>
<p>If the module is not loaded, this function searches the code
- path for the first file which contains object code for
- <c><anno>Module</anno></c> 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,
- <c>preloaded</c> is returned. If the module is Cover compiled,
- <c>cover_compiled</c> is returned. <c>non_existing</c> is
- returned if the module cannot be found.</p>
+ 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>
<func>
<name name="get_object_code" arity="1"/>
- <fsummary>Get the object code for a module</fsummary>
+ <fsummary>Gets the object code for a module.</fsummary>
<desc>
- <p>Searches the code path for the object code of the module
- <c><anno>Module</anno></c>. It returns <c>{<anno>Module</anno>, <anno>Binary</anno>, <anno>Filename</anno>}</c>
- if successful, and <c>error</c> if not. <c><anno>Binary</anno></c> is a
- binary data object which contains the object code for
+ <p>Searches the code path for the object code of module
+ <c><anno>Module</anno></c>. Returns <c>{<anno>Module</anno>, <anno>Binary</anno>, <anno>Filename</anno>}</c>
+ if successful, otherwise <c>error</c>. <c><anno>Binary</anno></c> 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 <c><anno>Module</anno></c> on a node <c>Node</c> is done as
@@ -715,10 +734,11 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
</func>
<func>
<name name="root_dir" arity="0"/>
- <fsummary>Root directory of Erlang/OTP</fsummary>
+ <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>
@@ -726,10 +746,11 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
</func>
<func>
<name name="lib_dir" arity="0"/>
- <fsummary>Library directory of Erlang/OTP</fsummary>
+ <fsummary>Library directory of Erlang/OTP.</fsummary>
<desc>
<p>Returns the library directory, <c>$OTPROOT/lib</c>, where
<c>$OTPROOT</c> is the root directory of Erlang/OTP.</p>
+ <p><em>Example:</em></p>
<pre>
> <input>code:lib_dir().</input>
"/usr/local/otp/lib"</pre>
@@ -737,50 +758,49 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
</func>
<func>
<name name="lib_dir" arity="1"/>
- <fsummary>Library directory for an application</fsummary>
+ <fsummary>Library directory for an application.</fsummary>
<desc>
- <p>This function is mainly intended for finding out the path
+ <p>Returns the path
for the "library directory", the top directory, for an
application <c><anno>Name</anno></c> located under <c>$OTPROOT/lib</c> or
- on a directory referred to via the <c>ERL_LIBS</c>
- environment variable.</p>
- <p>If there is a regular directory called <c><anno>Name</anno></c> or
- <c><anno>Name</anno>-Vsn</c> in the code path with an <c>ebin</c>
+ on a directory referred to with environment variable <c>ERL_LIBS</c>.</p>
+ <p>If a regular directory called <c><anno>Name</anno></c> or
+ <c><anno>Name</anno>-Vsn</c> exists in the code path with an <c>ebin</c>
subdirectory, the path to this directory is returned (not
- the <c>ebin</c> 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 the directory
+ the <c>ebin</c> directory).</p>
+ <p>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
<c>/usr/local/otp/lib/mnesia-4.2.2.ez/mnesia-4.2.2/ebin</c>
is in the path, <c>/usr/local/otp/lib/mnesia-4.2.2/ebin</c>
- will be returned. This means that the library directory for
- an application is the same, regardless of whether the
+ is returned. This means that the library directory for
+ an application is the same, regardless if the
application resides in an archive or not.</p>
-
+ <p><em>Example:</em></p>
<pre>
> <input>code:lib_dir(mnesia).</input>
"/usr/local/otp/lib/mnesia-4.2.2"</pre>
<p>Returns <c>{error, bad_name}</c> if <c><anno>Name</anno></c>
is not the name of an application under <c>$OTPROOT/lib</c> or
- on a directory referred to via the <c>ERL_LIBS</c>
- environment variable. Fails with an exception if <c>Name</c>
- has the wrong type.</p>
+ on a directory referred to through environment variable <c>ERL_LIBS</c>.
+ Fails with an exception if <c>Name</c> has the wrong type.</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>
+ <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="lib_dir" arity="2"/>
- <fsummary>subdirectory for an application</fsummary>
+ <fsummary>Subdirectory for an application.</fsummary>
<desc>
<p>Returns the path to a subdirectory directly under the top
directory of an application. Normally the subdirectories
- resides under the top directory for the application, but when
- applications at least partly resides in an archive the
- situation is different. Some of the subdirectories may reside
- as regular directories while other resides in an archive
- file. It is not checked if this directory really exists.</p>
-
+ reside under the top directory for the application, but when
+ applications at least partly resides in an archive, the
+ situation is different. Some of the subdirectories can reside
+ as regular directories while other reside in an archive
+ file. It is not checked whether this directory exists.</p>
+ <p><em>Example:</em></p>
<pre>
> <input>code:lib_dir(megaco, priv).</input>
"/usr/local/otp/lib/megaco-3.9.1.1/priv"</pre>
@@ -791,7 +811,7 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
</func>
<func>
<name name="compiler_dir" arity="0"/>
- <fsummary>Library directory for the compiler</fsummary>
+ <fsummary>Library directory for the compiler.</fsummary>
<desc>
<p>Returns the compiler library directory. Equivalent to
<c>code:lib_dir(compiler)</c>.</p>
@@ -799,10 +819,10 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
</func>
<func>
<name name="priv_dir" arity="1"/>
- <fsummary>Priv directory for an application</fsummary>
+ <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>
+ 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>
@@ -810,43 +830,43 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
</func>
<func>
<name name="objfile_extension" arity="0"/>
- <fsummary>Object code file extension</fsummary>
+ <fsummary>Object code file extension.</fsummary>
<desc>
- <p>Returns the object code file extension that corresponds to
- the Erlang machine used, namely <c>".beam"</c>.</p>
+ <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"/>
- <fsummary>Mark a directory as sticky</fsummary>
+ <fsummary>Mark a directory as sticky.</fsummary>
<desc>
- <p>This function marks <c><anno>Dir</anno></c> as sticky.</p>
- <p>Returns <c>ok</c> if successful or <c>error</c> if not.</p>
+ <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"/>
- <fsummary>Remove a sticky directory mark</fsummary>
+ <fsummary>Remove a sticky directory mark.</fsummary>
<desc>
- <p>This function unsticks a directory which has been marked as
+ <p>Unsticks a directory that is marked as
sticky.</p>
- <p>Returns <c>ok</c> if successful or <c>error</c> if not.</p>
+ <p>Returns <c>ok</c> if successful, otherwise <c>error</c>.</p>
</desc>
</func>
<func>
<name name="is_sticky" arity="1"/>
- <fsummary>Test whether a module is sticky</fsummary>
+ <fsummary>Test if a module is sticky.</fsummary>
<desc>
- <p>This function returns <c>true</c> if <c><anno>Module</anno></c> is the
+ <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
- (or in other words: an attempt to reload the module will fail),
+ (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>
<name name="where_is_file" arity="1"/>
- <fsummary>Full name of a file located in the code path</fsummary>
+ <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.
@@ -859,32 +879,39 @@ rpc:call(Node, code, load_binary, [Module, Filename, Binary]),
<name name="clash" arity="0"/>
<fsummary>Search for modules with identical names.</fsummary>
<desc>
- <p>Searches the entire code space for module names with
+ <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="is_module_native" arity="1"/>
- <fsummary>Test whether a module has native code</fsummary>
+ <fsummary>Test if a module has native code.</fsummary>
<desc>
- <p>This function returns <c>true</c> if <c><anno>Module</anno></c> is
- name of a loaded module that has native code loaded, and
- <c>false</c> if <c><anno>Module</anno></c> is loaded but does not have
- native. If <c><anno>Module</anno></c> is not loaded, this function returns
- <c>undefined</c>.</p>
+ <p>Returns:</p>
+ <taglist>
+ <tag><c>true</c></tag>
+ <item><p>If <c><anno>Module</anno></c> is the
+ name of a loaded module that has native code loaded</p></item>
+ <tag><c>false</c></tag>
+ <item><p>If <c><anno>Module</anno></c> is loaded but does not have
+ native code</p></item>
+ <tag><c>undefined</c></tag>
+ <item><p>If <c><anno>Module</anno></c> is not loaded</p></item>
+ </taglist>
</desc>
</func>
<func>
<name name="get_mode" arity="0"/>
- <fsummary>The code_server's mode.</fsummary>
+ <fsummary>The mode of the code server.</fsummary>
<desc>
- <p>This function returns an atom describing the code_server's mode:
- <c>interactive</c> or <c>embedded</c>. </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 in interactive
- mode, it only needs to add to the code path. If in embedded mode,
- the code has to be loaded with <c>load_binary/3</c></p>
+ 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
+ <seealso marker="#load_binary/3"><c>load_binary/3</c></seealso>.</p>
</desc>
</func>
</funcs>