The R13B03 release.OTP_R13B03

1 files changed, 697 insertions, 0 deletions

diff --git a/lib/sasl/doc/src/release_handler.xml b/lib/sasl/doc/src/release_handler.xml
new file mode 100644
index 0000000000..4a973bc5ed
--- /dev/null
+++ b/lib/sasl/doc/src/release_handler.xml
@@ -0,0 +1,697 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+  <header>
+    <copyright>
+      <year>1996</year><year>2009</year>
+      <holder>Ericsson AB. All Rights Reserved.</holder>
+    </copyright>
+    <legalnotice>
+      The contents of this file are subject to the Erlang Public License,
+      Version 1.1, (the "License"); you may not use this file except in
+      compliance with the License. You should have received a copy of the
+      Erlang Public License along with this software. If not, it can be
+      retrieved online at http://www.erlang.org/.
+    
+      Software distributed under the License is distributed on an "AS IS"
+      basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
+      the License for the specific language governing rights and limitations
+      under the License.
+    
+    </legalnotice>
+
+    <title>release_handler</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+  </header>
+  <module>release_handler</module>
+  <modulesummary>Unpacking and Installation of Release Packages</modulesummary>
+  <description>
+    <p>The <em>release handler</em> is a process belonging to the SASL
+      application which is responsible for <em>release handling</em>,
+      that is, unpacking, installation, and removal of release packages.</p>
+    <p>An introduction to release handling and a usage example can be
+      found in
+      <seealso marker="doc/design_principles:release_handling">Design Principles</seealso>.
+      </p>
+    <p>A <em>release package</em> is a compressed tar file containing
+      code for a certain version of a release, created by calling
+      <seealso marker="systools#make_tar/1">systools:make_tar/1,2</seealso>.
+      The release package should be placed in the <c>$ROOT/releases</c>
+      directory of the previous version of the release where
+      <c>$ROOT</c> is the installation root directory,
+      <c>code:root_dir()</c>.
+      Another <c>releases</c> directory can be specified using the SASL
+      configuration parameter <c>releases_dir</c>, or the OS environment
+      variable <c>RELDIR</c>. The release handler must have write access
+      to this directory in order to install the new release.
+      The persistent state of the release handler is stored there in a
+      file called <c>RELEASES</c>.</p>
+    <p>A release package should always contain the release resource file
+      <c>Name.rel</c> and a boot script <c>Name.boot</c>. It may contain
+      a release upgrade file <c>relup</c> and a system configuration
+      file <c>sys.config</c>. The <c>.rel</c> file contains information
+      about the release: its name, version, and which ERTS and
+      application versions it uses. The <c>relup</c> file contains
+      scripts for how to upgrade to, or downgrade from, this version of
+      the release.</p>
+    <p>The release package can be <em>unpacked</em>, which extracts
+      the files. An unpacked release can be <em>installed</em>.
+      The currently used version of the release is then upgraded or
+      downgraded to the specified version by evaluating the instructions
+      in <c>relup</c>. An installed release can be made
+      <em>permanent</em>. There can only be one permanent release in
+      the system, and this is the release that is used if the system is
+      restarted. An installed release, except the permanent one, can be
+      <em>removed</em>. When a release is removed, all files that
+      belong to that release only are deleted.</p>
+    <p>Each version of the release has a status. The status can be
+      <c>unpacked</c>, <c>current</c>, <c>permanent</c>, or <c>old</c>.
+      There is always one latest release which either has status
+      <c>permanent</c> (normal case), or <c>current</c> (installed, but
+      not yet made permanent). The following table illustrates
+      the meaning of the status values:</p>
+    <pre>
+Status     Action                NextStatus
+-------------------------------------------
+  -        unpack                unpacked
+unpacked   install               current
+           remove                  -
+current    make_permanent        permanent
+           install other         old
+           remove                  -
+permanent  make other permanent  old
+           install               permanent
+old        reboot_old            permanent
+           install               current
+           remove                  -
+    </pre>
+    <p>The release handler process is a locally registered process on
+      each node. When a release is installed in a distributed system,
+      the release handler on each node must be called. The release
+      installation may be synchronized between nodes. From an operator
+      view, it may be unsatisfactory to specify each node.  The aim is
+      to install one release package in the system, no matter how many
+      nodes there are. If this is the case, it is recommended that
+      software management functions are written which take care of
+      this problem. Such a function may have knowledge of the system
+      architecture, so it can contact each individual release handler
+      to install the package.</p>
+    <p>For release handling to work properly, the runtime system needs
+      to have knowledge about which release it is currently running. It
+      must also be able to change (in run-time) which boot script and
+      system configuration file should be used if the system is
+      restarted. This is taken care of automatically if Erlang is
+      started as an embedded system. Read about this in <em>Embedded System</em>. In this case, the system configuration file
+      <c>sys.config</c> is mandatory.</p>
+    <p>A new release may restart the system. Which program to use is
+      specified by the SASL configuration parameter <c>start_prg</c>
+      which defaults to <c>$ROOT/bin/start</c>.</p>
+    <p>The emulator restart on Windows NT expects that the system is
+      started using the <c>erlsrv</c> program (as a service).
+      Furthermore the release handler expects that the service is named 
+      <em>NodeName</em>_<em>Release</em>, where <em>NodeName</em> is
+      the first part of the Erlang nodename (up to, but not including
+      the "@") and <em>Release</em> is the current release of
+      the application. The release handler furthermore expects that a
+      program like <c>start_erl.exe</c> is specified as "machine" to
+      <c>erlsrv</c>. During upgrading with restart, a new service will
+      be registered and started. The new service will be set to
+      automatic and the old service removed as soon as the new release
+      is made permanent.</p>
+    <p>The release handler at a node which runs on a diskless machine,
+      or with a read-only file system, must be configured accordingly
+      using the following <c>sasl</c> configuration parameters (see
+      <seealso marker="sasl_app">sasl(6)</seealso> for details):</p>
+    <taglist>
+      <tag><c>masters</c></tag>
+      <item>
+        <p>This node uses a number of master nodes in order to store
+          and fetch release information. All master nodes must be up
+          and running whenever release information is written by this
+          node.</p>
+      </item>
+      <tag><c>client_directory</c></tag>
+      <item>
+        <p>The <c>client_directory</c> in the directory structure of
+          the master nodes must be specified.</p>
+      </item>
+      <tag><c>static_emulator</c></tag>
+      <item>
+        <p>This parameter specifies if the Erlang emulator is
+          statically installed at the client node. A node with a static
+          emulator cannot dynamically switch to a new emulator because
+          the executable files are statically written into memory.</p>
+      </item>
+    </taglist>
+    <p>It is also possible to use the release handler to unpack and
+      install release packages when not running Erlang as an embedded
+      system, but in this case the user must somehow make sure that
+      correct boot scripts and configuration files are used if
+      the system needs to be restarted.</p>
+    <p>There are additional functions for using another file structure
+      than the structure defined in OTP. These functions can be used
+      to test a release upgrade locally.</p>
+  </description>
+  <funcs>
+    <func>
+      <name>check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}</name>
+      <fsummary>Check installation of a release in the system.</fsummary>
+      <type>
+        <v>Vsn = OtherVsn = string()</v>
+        <v>Descr = term()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Checks if the specified version <c>Vsn</c> of the release
+          can be installed. The release must not have status
+          <c>current</c>. Issues warnings if <c>relup</c> or
+          <c>sys.config</c> are not present. If <c>relup</c> is present,
+          its contents are checked and <c>{error,Reason}</c> is
+          returned if an error is found. Also checks that all required
+          applications are present and that all new code can be loaded,
+          or <c>{error,Reason}</c> is returned.</p>
+        <p>This function evaluates all instructions that occur before
+          the <c>point_of_no_return</c> instruction in the release
+          upgrade script.</p>
+        <p>Returns the same as <c>install_release/1</c>. <c>Descr</c>
+          defaults to "" if no <c>relup</c> file is found.</p>
+      </desc>
+    </func>
+    <func>
+      <name>create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}</name>
+      <fsummary>Create an initial RELEASES file.</fsummary>
+      <type>
+        <v>Root = RelDir = RelFile = string()</v>
+        <v>AppDirs = [{App, Vsn, Dir}]</v>
+        <v>&nbsp;App = atom()</v>
+        <v>&nbsp;Vsn = Dir = string()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Creates an initial RELEASES file to be used by the release
+          handler. This file must exist in order to install new
+          releases.</p>
+        <p><c>Root</c> is the root of the installation (<c>$ROOT</c>) as
+          described above. <c>RelDir</c> is the the directory where
+          the <c>RELEASES</c> file should be created (normally
+          <c>$ROOT/releases</c>). <c>RelFile</c> is the name
+          of the <c>.rel</c> file that describes the initial release,
+          including the extension <c>.rel</c>.</p>
+        <p><c>AppDirs</c> can be used to specify from where the modules
+          for the specified applications should be loaded. <c>App</c> is
+          the name of an application, <c>Vsn</c> is the version, and
+          <c>Dir</c> is the name of the directory where <c>App-Vsn</c>
+          is located. The corresponding modules should be located under
+          <c>Dir/App-Vsn/ebin</c>. The directories for applications not
+          specified in <c>AppDirs</c> are assumed to be located in
+          <c>$ROOT/lib</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>install_file(Vsn, File) -> ok | {error, Reason}</name>
+      <fsummary>Install a release file in the release structure.</fsummary>
+      <type>
+        <v>Vsn = File = string()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Installs a release dependent file in the release structure.
+          A release dependent file is a file that must be in
+          the release structure when a new release is installed:
+          <c>start.boot</c>, <c>relup</c> and <c>sys.config</c>.</p>
+        <p>The function can be called, for example, when these files
+          are generated at the target. It should be called after
+          <c>set_unpacked/2</c> has been called.</p>
+      </desc>
+    </func>
+    <func>
+      <name>install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}</name>
+      <name>install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {error, Reason}</name>
+      <fsummary>Install a release in the system.</fsummary>
+      <type>
+        <v>Vsn = OtherVsn = string()</v>
+        <v>Opt = {error_action, Action} | {code_change_timeout, Timeout}</v>
+        <v>&nbsp;&nbsp;&nbsp;| {suspend_timeout, Timeout} | {update_paths, Bool}</v>
+        <v>&nbsp;Action = restart | reboot</v>
+        <v>&nbsp;Timeout = default | infinity | int()>0</v>
+        <v>&nbsp;Bool = boolean()</v>
+        <v>Descr = term()</v>
+        <v>Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | term()</v>
+      </type>
+      <desc>
+        <p>Installs the specified version <c>Vsn</c> of the release.
+          Looks first for a <c>relup</c> file for <c>Vsn</c> and a
+          script <c>{UpFromVsn,Descr1,Instructions1}</c> in this file
+          for upgrading from the current version. If not found,
+          the function looks for a <c>relup</c> file for the current
+          version and a script <c>{Vsn,Descr2,Instructions2}</c> in this
+          file for downgrading to <c>Vsn</c>.</p>
+        <p>If a script is found, the first thing that happens is that
+          the applications specifications are updated according to
+          the <c>.app</c> files and <c>sys.config</c> belonging to
+          the release version <c>Vsn</c>.</p>
+        <p>After the application specifications have been updated,
+          the instructions in the script are evaluated and the function
+          returns <c>{ok,OtherVsn,Descr}</c> if successful.
+          <c>OtherVsn</c> and <c>Descr</c> are the version
+          (<c>UpFromVsn</c> or <c>Vsn</c>) and description
+          (<c>Descr1</c> or <c>Descr2</c>) as specified in the script.</p>
+        <p>If a recoverable error occurs, the function returns
+          <c>{error,Reason}</c> and the original application
+          specifications are restored. If a non-recoverable error
+          occurs, the system is restarted.</p>
+        <p>The option <c>error_action</c> defines if the node should be
+          restarted (<c>init:restart()</c>) or rebooted
+          (<c>init:reboot()</c>) in case of an error during
+          the installation. Default is <c>restart</c>.</p>
+        <p>The option <c>code_change_timeout</c> defines the timeout
+          for all calls to <c>sys:change_code</c>. If no value is
+          specified or <c>default</c> is given, the default value
+          defined in <c>sys</c> is used.</p>
+        <p>The option <c>suspend_timeout</c> defines the timeout for 
+          all calls to <c>sys:suspend</c>. If no value is specified,
+          the values defined by the <c>Timeout</c> parameter of
+          the <c>upgrade</c> or <c>suspend</c> instructions are used.
+          If <c>default</c> is specified, the default value defined in
+          <c>sys</c> is used.</p>
+        <p>The option <c>{update_paths,Bool}</c> indicates if all
+          application code paths should be updated (<c>Bool==true</c>),
+          or if only code paths for modified applications should be
+          updated (<c>Bool==false</c>, default). This option only has
+          effect for other application directories than the default
+          <c>$ROOT/lib/App-Vsn</c>, that is, application directories
+          provided in the <c>AppDirs</c> argument in a call to
+          <c>create_RELEASES/4</c> or <c>set_unpacked/2</c>.</p>
+        <p>Example: In the current version <c>CurVsn</c> of a release,
+          the application directory of <c>myapp</c> is
+          <c>$ROOT/lib/myapp-1.0</c>. A new version <c>NewVsn</c> is
+          unpacked outside the release handler, and the release handler
+          is informed about this with a call to:</p>
+        <code type="none">
+release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
+=> {ok,NewVsn}
+        </code>
+        <p>If <c>NewVsn</c> is installed with the option
+          <c>{update_paths,true}</c>, afterwards
+          <c>code:lib_dir(myapp)</c> will return
+          <c>/home/user/myapp-1.0</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>make_permanent(Vsn) -> ok | {error, Reason}</name>
+      <fsummary>Make the specified release version permanent.</fsummary>
+      <type>
+        <v>Vsn = string()</v>
+        <v>Reason = {bad_status, Status} | term()</v>
+      </type>
+      <desc>
+        <p>Makes the specified version <c>Vsn</c> of the release
+          permanent.</p>
+      </desc>
+    </func>
+    <func>
+      <name>remove_release(Vsn) -> ok | {error, Reason}</name>
+      <fsummary>Remove a release from the system.</fsummary>
+      <type>
+        <v>Vsn = string()</v>
+        <v>Reason = {permanent, Vsn} | client_node | term()</v>
+      </type>
+      <desc>
+        <p>Removes a release and its files from the system.
+          The release must not be the permanent release. Removes only
+          the files and directories not in use by another release.</p>
+      </desc>
+    </func>
+    <func>
+      <name>reboot_old_release(Vsn) -> ok | {error, Reason}</name>
+      <fsummary>Reboot the system from an old release.</fsummary>
+      <type>
+        <v>Vsn = string()</v>
+        <v>Reason = {bad_status, Status} | term()</v>
+      </type>
+      <desc>
+        <p>Reboots the system by making the old release permanent, and
+          calls <c>init:reboot()</c> directly. The release must have
+          status <c>old</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>set_removed(Vsn) -> ok | {error, Reason}</name>
+      <fsummary>Mark a release as removed.</fsummary>
+      <type>
+        <v>Vsn = string()</v>
+        <v>Reason = {permanent, Vsn} | term()</v>
+      </type>
+      <desc>
+        <p>Makes it possible to handle removal of releases outside
+          the release handler. Tells the release handler that
+          the release is removed from the system. This function does
+          not delete any files.</p>
+      </desc>
+    </func>
+    <func>
+      <name>set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}</name>
+      <fsummary>Mark a release as unpacked.</fsummary>
+      <type>
+        <v>RelFile = string()</v>
+        <v>AppDirs = [{App, Vsn, Dir}]</v>
+        <v>&nbsp;App = atom()</v>
+        <v>&nbsp;Vsn = Dir = string()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Makes it possible to handle unpacking of releases outside
+          the release handler. Tells the release handler that
+          the release is unpacked. <c>Vsn</c> is extracted from
+          the release resource file <c>RelFile</c>.</p>
+        <p><c>AppDirs</c> can be used to specify from where the modules
+          for the specified applications should be loaded. <c>App</c> is
+          the name of an application, <c>Vsn</c> is the version, and
+          <c>Dir</c> is the name of the directory where <c>App-Vsn</c>
+          is located. The corresponding modules should be located under
+          <c>Dir/App-Vsn/ebin</c>. The directories for applications not
+          specified in <c>AppDirs</c> are assumed to be located in
+          <c>$ROOT/lib</c>.</p>
+      </desc>
+    </func>
+    <func>
+      <name>unpack_release(Name) -> {ok, Vsn} | {error, Reason}</name>
+      <fsummary>Unpack a release package.</fsummary>
+      <type>
+        <v>Name = Vsn = string()</v>
+        <v>Reason = client_node | term()</v>
+      </type>
+      <desc>
+        <p>Unpacks a release package <c>Name.tar.gz</c> located in
+          the <c>releases</c> directory.</p>
+        <p>Performs some checks on the package - for example checks
+          that all mandatory files are present - and extracts its
+          contents.</p>
+      </desc>
+    </func>
+    <func>
+      <name>which_releases() -> [{Name, Vsn, Apps, Status}]</name>
+      <fsummary>Return all known releases</fsummary>
+      <type>
+        <v>Name = Vsn = string()</v>
+        <v>Apps = ["App-Vsn"]</v>
+        <v>Status = unpacked | current | permanent | old</v>
+      </type>
+      <desc>
+        <p>Returns all releases known to the release handler.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>Application Upgrade/Downgrade</title>
+    <p>The following functions can be used to test upgrade and downgrade
+      of single applications (instead of upgrading/downgrading an entire
+      release). A script corresponding to <c>relup</c> is created
+      on-the-fly, based on the <c>.appup</c> file for the application,
+      and evaluated exactly in the same way as <c>release_handler</c>
+      does.</p>
+    <warning>
+      <p>These function is primarily intended for simplified testing of
+        of <c>.appup</c> files. They are not run within the context of
+        the <c>release_handler</c> process. They must therefore
+        <em>not</em> be used together with calls to
+        <c>install_release/1,2</c>, as this will cause
+        <c>release_handler</c> to end up in an inconsistent state.</p>
+      <p>No persistent information is updated, why these functions can
+        be used on any Erlang node, embedded or not. Also, using these
+        functions does not effect which code will be loaded in case of
+        a reboot.</p>
+      <p>If the upgrade or downgrade fails, the application may end up
+        in an inconsistent state.</p>
+    </warning>
+  </section>
+  <funcs>
+    <func>
+      <name>upgrade_app(App, Dir) -> {ok, Unpurged} | restart_new_emulator | {error, Reason}</name>
+      <fsummary>Upgrade to a new application version</fsummary>
+      <type>
+        <v>App = atom()</v>
+        <v>Dir = string()</v>
+        <v>Unpurged = [Module]</v>
+        <v>&nbsp;Module = atom()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Upgrades an application <c>App</c> from the current
+          version to a new version located in <c>Dir</c> according to
+          the <c>.appup</c> script.</p>
+        <p><c>App</c> is the name of the application, which must be
+          started. <c>Dir</c> is the new library directory of
+          <c>App</c>, the corresponding modules as well as
+          the <c>.app</c> and <c>.appup</c> files should be located
+          under <c>Dir/ebin</c>.</p>
+        <p>The function looks in the <c>.appup</c> file and tries to
+          find an upgrade script from the current version of
+          the application using
+          <seealso marker="#upgrade_script/2">upgrade_script/2</seealso>.
+          This script is evaluated using
+          <seealso marker="#eval_appup_script/4">eval_appup_script/4</seealso>,
+          exactly in the same way as
+          <seealso marker="#install_release/1">install_release/1,2</seealso>
+          does.</p>
+        <p>Returns <c>{ok, Unpurged}</c> if evaluating the script is
+          successful, where <c>Unpurged</c> is a list of unpurged
+          modules, or <c>restart_new_emulator</c> if this instruction is
+          encountered in the script, or <c>{error, Reason}</c> if
+          an error occurred when finding or evaluating the script.</p>
+      </desc>
+    </func>
+    <func>
+      <name>downgrade_app(App, Dir) -></name>
+      <name>downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_new_emulator | {error, Reason}</name>
+      <fsummary>Downgrade to a previous application version</fsummary>
+      <type>
+        <v>App = atom()</v>
+        <v>Dir = OldVsn = string()</v>
+        <v>Unpurged = [Module]</v>
+        <v>&nbsp;Module = atom()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Downgrades an application <c>App</c> from the current
+          version to a previous version <c>OldVsn</c> located in
+          <c>Dir</c> according to the <c>.appup</c> script.</p>
+        <p><c>App</c> is the name of the application, which must be
+          started. <c>OldVsn</c> is the previous version of
+          the application and can be omitted if <c>Dir</c> is of
+          the format <c>"App-OldVsn"</c>. <c>Dir</c> is the library
+          directory of this previous version of <c>App</c>,
+          the corresponding modules as well as the old <c>.app</c> file
+          should be located under <c>Dir/ebin</c>. The <c>.appup</c>
+          file should be located in the <c>ebin</c> directory of
+          the <em>current</em> library directory of the application
+          (<c>code:lib_dir(App)</c>).</p>
+        <p>The function looks in the <c>.appup</c> file and tries to
+          find an downgrade script to the previous version of
+          the application using
+          <seealso marker="#downgrade_script/3">downgrade_script/3</seealso>.
+          This script is evaluated using
+          <seealso marker="#eval_appup_script/4">eval_appup_script/4</seealso>,
+          exactly in the same way as
+          <seealso marker="#install_release/1">install_release/1,2</seealso>
+          does.</p>
+        <p>Returns <c>{ok, Unpurged}</c> if evaluating the script is
+          successful, where <c>Unpurged</c> is a list of unpurged
+          modules, or <c>restart_new_emulator</c> if this instruction is
+          encountered in the script, or <c>{error, Reason}</c> if
+          an error occurred when finding or evaluating the script.</p>
+      </desc>
+    </func>
+    <func>
+      <name>upgrade_script(App, Dir) -> {ok, NewVsn, Script}</name>
+      <fsummary>Find an application upgrade script</fsummary>
+      <type>
+        <v>App = atom()</v>
+        <v>Dir = string()</v>
+        <v>NewVsn = string()</v>
+        <v>Script = Instructions -- see appup(4)</v>
+      </type>
+      <desc>
+        <p>Tries to find an application upgrade script for <c>App</c>
+          from the current version to a new version located in
+          <c>Dir</c>.</p>
+        <p>The upgrade script can then be evaluated using
+          <seealso marker="#eval_appup_script/4">eval_appup_script/4</seealso>.
+          It is recommended to use
+          <seealso marker="#upgrade_app/2">upgrade_app/2</seealso>
+          instead, but this function is useful in order to inspect
+          the contents of the script.</p>
+        <p><c>App</c> is the name of the application, which must be
+          started. <c>Dir</c> is the new library directory of
+          <c>App</c>, the corresponding modules as well as
+          the <c>.app</c> and <c>.appup</c> files should be located
+          under <c>Dir/ebin</c>.</p>
+        <p>The function looks in the <c>.appup</c> file and tries to
+          find an upgrade script from the current version of
+          the application. High-level instructions are translated to
+          low-level instructions and the instructions are sorted in
+          the same manner as when generating a <c>relup</c> script.</p>
+        <p>Returns <c>{ok, NewVsn, Script}</c> if successful, where
+          <c>NewVsn</c> is the new application version.</p>
+        <p>Failure: If a script cannot be found, the function fails
+          with an appropriate error reason.</p>
+      </desc>
+    </func>
+    <func>
+      <name>downgrade_script(App, OldVsn, Dir) -> {ok, Script}</name>
+      <fsummary>Find an application downgrade script</fsummary>
+      <type>
+        <v>App = atom()</v>
+        <v>OldVsn = Dir = string()</v>
+        <v>Script = Instructions -- see appup(4)</v>
+      </type>
+      <desc>
+        <p>Tries to find an application downgrade script for <c>App</c>
+          from the current version to a previous version <c>OldVsn</c>
+          located in <c>Dir</c>.</p>
+        <p>The downgrade script can then be evaluated using
+          <seealso marker="#eval_appup_script/4">eval_appup_script/4</seealso>.
+          It is recommended to use
+          <seealso marker="#downgrade_app/2">downgrade_app/2,3</seealso>
+          instead, but this function is useful in order to inspect
+          the contents of the script.</p>
+        <p><c>App</c> is the name of the application, which must be
+          started. <c>Dir</c> is the previous library directory of
+          <c>App</c>, the corresponding modules as well as
+          the old <c>.app</c> file should be located under
+          <c>Dir/ebin</c>. The <c>.appup</c> file should be located in
+          the <c>ebin</c> directory of the <em>current</em> library
+          directory of the application (<c>code:lib_dir(App)</c>).</p>
+        <p>The function looks in the <c>.appup</c> file and tries to
+          find an downgrade script from the current version of
+          the application. High-level instructions are translated to
+          low-level instructions and the instructions are sorted in
+          the same manner as when generating a <c>relup</c> script.</p>
+        <p>Returns <c>{ok, Script}</c> if successful.</p>
+        <p>Failure: If a script cannot be found, the function fails
+          with an appropriate error reason.</p>
+      </desc>
+    </func>
+    <func>
+      <name>eval_appup_script(App, ToVsn, ToDir, Script) -> {ok, Unpurged} | restart_new_emulator | {error, Reason}</name>
+      <fsummary>Evaluate an application upgrade or downgrade script</fsummary>
+      <type>
+        <v>App = atom()</v>
+        <v>ToVsn = ToDir = string()</v>
+        <v>Script -- see upgrade_script/2, downgrade_script/3</v>
+        <v>Unpurged = [Module]</v>
+        <v>&nbsp;Module = atom()</v>
+        <v>Reason = term()</v>
+      </type>
+      <desc>
+        <p>Evaluates an application upgrade or downgrade script
+          <c>Script</c>, the result from calling
+          <seealso marker="#upgrade_app/2">upgrade_app/2</seealso> or
+          <seealso marker="#downgrade_app/3">downgrade_app/2,3</seealso>,
+          exactly in the same way as
+          <seealso marker="#install_release/1">install_release/1,2</seealso>
+          does.</p>
+        <p><c>App</c> is the name of the application, which must be
+          started. <c>ToVsn</c> is the version to be upgraded/downgraded
+          to, and <c>ToDir</c> is the library directory of this version.
+          The corresponding modules as well as the <c>.app</c> and
+          <c>.appup</c> files should be located under <c>Dir/ebin</c>.</p>
+        <p>Returns <c>{ok, Unpurged}</c> if evaluating the script is
+          successful, where <c>Unpurged</c> is a list of unpurged
+          modules, or <c>restart_new_emulator</c> if this instruction is
+          encountered in the script, or <c>{error, Reason}</c> if
+          an error occurred when evaluating the script.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>Typical Error Reasons</title>
+    <list type="bulleted">
+      <item>
+        <p><c>{bad_masters, Masters}</c> - The master nodes
+          <c>Masters</c> are not alive.</p>
+      </item>
+      <item>
+        <p><c>{bad_rel_file, File}</c> - Specified <c>.rel</c> file
+          <c>File</c> can not be read, or does not contain a single
+          term.</p>
+      </item>
+      <item>
+        <p><c>{bad_rel_data, Data}</c> - Specified <c>.rel</c> file
+          does not contain a recognized release specification, but
+          another term <c>Data</c>.</p>
+      </item>
+      <item>
+        <p><c>{bad_relup_file, File}</c> - Specified <c>relup</c> file
+          <c>Relup</c> contains bad data.</p>
+      </item>
+      <item>
+        <p><c>{cannot_extract_file, Name, Reason}</c> - Problems when
+          extracting from a tar file, <c>erl_tar:extract/2</c> returned
+          <c>{error, {Name, Reason}}</c>.</p>
+      </item>
+      <item>
+        <p><c>{existing_release, Vsn}</c> - Specified release version
+          <c>Vsn</c> is already in use.</p>
+      </item>
+      <item>
+        <p><c>{Master, Reason, When}</c> - Some operation, indicated by
+          the term <c>When</c>, failed on the master node <c>Master</c>
+          with the specified error reason <c>Reason</c>.</p>
+      </item>
+      <item>
+        <p><c>{no_matching_relup, Vsn, CurrentVsn}</c> - Cannot find a
+          script for up/downgrading between <c>CurrentVsn</c> and
+          <c>Vsn</c>.</p>
+      </item>
+      <item>
+        <p><c>{no_such_directory, Path}</c> - The directory <c>Path</c>
+          does not exist.</p>
+      </item>
+      <item>
+        <p><c>{no_such_file, Path}</c> - The path <c>Path</c> (file or
+          directory) does not exist.</p>
+      </item>
+      <item>
+        <p><c>{no_such_file, {Master, Path}}</c> - The path <c>Path</c>
+          (file or directory) does not exist at the master node
+          <c>Master</c>.</p>
+      </item>
+      <item>
+        <p><c>{no_such_release, Vsn}</c> - The specified version
+          <c>Vsn</c> of the release does not exist.</p>
+      </item>
+      <item>
+        <p><c>{not_a_directory, Path}</c> - <c>Path</c> exists, but is
+          not a directory.</p>
+      </item>
+      <item>
+        <p><c>{Posix, File}</c> - Some file operation failed for
+          <c>File</c>. <c>Posix</c> is an atom named from the Posix
+          error codes, such as <c>enoent</c>, <c>eacces</c> or
+          <c>eisdir</c>. See <c>file(3)</c>.</p>
+      </item>
+      <item>
+        <p><c>Posix</c> - Some file operation failed, as above.</p>
+      </item>
+    </list>
+  </section>
+
+  <section>
+    <title>SEE ALSO</title>
+    <p><seealso marker="doc/design_principles:release_handling">OTP Design Principles</seealso>,
+      <seealso marker="kernel:config">config(4)</seealso>,
+      <seealso marker="relup">relup(4)</seealso>,
+      <seealso marker="rel">rel(4)</seealso>,
+      <seealso marker="script">script(4)</seealso>,
+      <seealso marker="stdlib:sys">sys(3)</seealso>,
+      <seealso marker="systools">systools(3)</seealso></p>
+  </section>
+</erlref>
+