<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html xmlns:fn="http://www.w3.org/2005/02/xpath-functions">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../../../doc/otp_doc.css" type="text/css">
<title>Erlang -- release_handler</title>
</head>
<body bgcolor="white" text="#000000" link="#0000ff" vlink="#ff00ff" alink="#ff0000"><div id="container">
<script id="js" type="text/javascript" language="JavaScript" src="../../../../doc/js/flipmenu/flipmenu.js"></script><script id="js2" type="text/javascript" src="../../../../doc/js/erlresolvelinks.js"></script><script language="JavaScript" type="text/javascript">
<!--
function getWinHeight() {
var myHeight = 0;
if( typeof( window.innerHeight ) == 'number' ) {
//Non-IE
myHeight = window.innerHeight;
} else if( document.documentElement && ( document.documentElement.clientWidth ||
document.documentElement.clientHeight ) ) {
//IE 6+ in 'standards compliant mode'
myHeight = document.documentElement.clientHeight;
} else if( document.body && ( document.body.clientWidth || document.body.clientHeight ) ) {
//IE 4 compatible
myHeight = document.body.clientHeight;
}
return myHeight;
}
function setscrollpos() {
var objf=document.getElementById('loadscrollpos');
document.getElementById("leftnav").scrollTop = objf.offsetTop - getWinHeight()/2;
}
function addEvent(obj, evType, fn){
if (obj.addEventListener){
obj.addEventListener(evType, fn, true);
return true;
} else if (obj.attachEvent){
var r = obj.attachEvent("on"+evType, fn);
return r;
} else {
return false;
}
}
addEvent(window, 'load', setscrollpos);
//--></script><div id="leftnav"><div class="innertube">
<img alt="Erlang logo" src="../../../../doc/erlang-logo.png"><br><small><a href="users_guide.html">User's Guide</a><br><a href="index.html">Reference Manual</a><br><a href="release_notes.html">Release Notes</a><br><a href="../pdf/sasl-2.2.1.pdf">PDF</a><br><a href="../../../../doc/index.html">Top</a></small><p><strong>System Application Support Libraries (SASL)</strong><br><strong>Reference Manual</strong><br><small>Version 2.2.1</small></p>
<br><a href="javascript:openAllFlips()">Expand All</a><br><a href="javascript:closeAllFlips()">Contract All</a><p><small><strong>Table of Contents</strong></small></p>
<ul class="flipMenu">
<li title="sasl (App)"><a href="sasl_app.html">sasl (App)
</a></li>
<li id="no" title="alarm_handler " expanded="false">alarm_handler<ul>
<li><a href="alarm_handler.html">
Top of manual page
</a></li>
<li title="clear_alarm-1"><a href="alarm_handler.html#clear_alarm-1">clear_alarm/1</a></li>
<li title="get_alarms-0"><a href="alarm_handler.html#get_alarms-0">get_alarms/0</a></li>
<li title="set_alarm-1"><a href="alarm_handler.html#set_alarm-1">set_alarm/1</a></li>
</ul>
</li>
<li id="no" title="overload " expanded="false">overload<ul>
<li><a href="overload.html">
Top of manual page
</a></li>
<li title="request-0"><a href="overload.html#request-0">request/0</a></li>
<li title="get_overload_info-0"><a href="overload.html#get_overload_info-0">get_overload_info/0</a></li>
</ul>
</li>
<li id="no" title="rb " expanded="false">rb<ul>
<li><a href="rb.html">
Top of manual page
</a></li>
<li title="filter-1"><a href="rb.html#filter-1">filter/1</a></li>
<li title="filter-2"><a href="rb.html#filter-2">filter/2</a></li>
<li title="grep-1"><a href="rb.html#grep-1">grep/1</a></li>
<li title="h-0"><a href="rb.html#h-0">h/0</a></li>
<li title="help-0"><a href="rb.html#help-0">help/0</a></li>
<li title="list-0"><a href="rb.html#list-0">list/0</a></li>
<li title="list-1"><a href="rb.html#list-1">list/1</a></li>
<li title="rescan-0"><a href="rb.html#rescan-0">rescan/0</a></li>
<li title="rescan-1"><a href="rb.html#rescan-1">rescan/1</a></li>
<li title="show-0"><a href="rb.html#show-0">show/0</a></li>
<li title="show-1"><a href="rb.html#show-1">show/1</a></li>
<li title="start-0"><a href="rb.html#start-0">start/0</a></li>
<li title="start-1"><a href="rb.html#start-1">start/1</a></li>
<li title="start_log-1"><a href="rb.html#start_log-1">start_log/1</a></li>
<li title="stop-0"><a href="rb.html#stop-0">stop/0</a></li>
<li title="stop_log-0"><a href="rb.html#stop_log-0">stop_log/0</a></li>
</ul>
</li>
<li id="loadscrollpos" title="release_handler " expanded="true">release_handler<ul>
<li><a href="release_handler.html">
Top of manual page
</a></li>
<li title="check_install_release-1"><a href="release_handler.html#check_install_release-1">check_install_release/1</a></li>
<li title="check_install_release-2"><a href="release_handler.html#check_install_release-2">check_install_release/2</a></li>
<li title="create_RELEASES-4"><a href="release_handler.html#create_RELEASES-4">create_RELEASES/4</a></li>
<li title="install_file-2"><a href="release_handler.html#install_file-2">install_file/2</a></li>
<li title="install_release-1"><a href="release_handler.html#install_release-1">install_release/1</a></li>
<li title="install_release-2"><a href="release_handler.html#install_release-2">install_release/2</a></li>
<li title="make_permanent-1"><a href="release_handler.html#make_permanent-1">make_permanent/1</a></li>
<li title="remove_release-1"><a href="release_handler.html#remove_release-1">remove_release/1</a></li>
<li title="reboot_old_release-1"><a href="release_handler.html#reboot_old_release-1">reboot_old_release/1</a></li>
<li title="set_removed-1"><a href="release_handler.html#set_removed-1">set_removed/1</a></li>
<li title="set_unpacked-2"><a href="release_handler.html#set_unpacked-2">set_unpacked/2</a></li>
<li title="unpack_release-1"><a href="release_handler.html#unpack_release-1">unpack_release/1</a></li>
<li title="which_releases-0"><a href="release_handler.html#which_releases-0">which_releases/0</a></li>
<li title="which_releases-1"><a href="release_handler.html#which_releases-1">which_releases/1</a></li>
<li title="upgrade_app-2"><a href="release_handler.html#upgrade_app-2">upgrade_app/2</a></li>
<li title="downgrade_app-2"><a href="release_handler.html#downgrade_app-2">downgrade_app/2</a></li>
<li title="downgrade_app-3"><a href="release_handler.html#downgrade_app-3">downgrade_app/3</a></li>
<li title="upgrade_script-2"><a href="release_handler.html#upgrade_script-2">upgrade_script/2</a></li>
<li title="downgrade_script-3"><a href="release_handler.html#downgrade_script-3">downgrade_script/3</a></li>
<li title="eval_appup_script-4"><a href="release_handler.html#eval_appup_script-4">eval_appup_script/4</a></li>
</ul>
</li>
<li id="no" title="systools " expanded="false">systools<ul>
<li><a href="systools.html">
Top of manual page
</a></li>
<li title="make_relup-3"><a href="systools.html#make_relup-3">make_relup/3</a></li>
<li title="make_relup-4"><a href="systools.html#make_relup-4">make_relup/4</a></li>
<li title="make_script-1"><a href="systools.html#make_script-1">make_script/1</a></li>
<li title="make_script-2"><a href="systools.html#make_script-2">make_script/2</a></li>
<li title="make_tar-1"><a href="systools.html#make_tar-1">make_tar/1</a></li>
<li title="make_tar-2"><a href="systools.html#make_tar-2">make_tar/2</a></li>
<li title="script2boot-1"><a href="systools.html#script2boot-1">script2boot/1</a></li>
</ul>
</li>
<li title="appup"><a href="appup.html">appup</a></li>
<li title="rel"><a href="rel.html">rel</a></li>
<li title="relup"><a href="relup.html">relup</a></li>
<li title="script"><a href="script.html">script</a></li>
</ul>
</div></div>
<div id="content">
<div class="innertube">
<!-- refpage --><center><h1>release_handler</h1></center>
<h3>MODULE</h3>
<div class="REFBODY">release_handler</div>
<h3>MODULE SUMMARY</h3>
<div class="REFBODY">Unpacking and Installation of Release Packages</div>
<h3>DESCRIPTION</h3>
<div class="REFBODY"><p>
<p>The <strong>release handler</strong> is a process belonging to the SASL
application which is responsible for <strong>release handling</strong>,
that is, unpacking, installation, and removal of release packages.</p>
<p>An introduction to release handling and a usage example can be
found in
<span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','doc/design_principles','release_handling.html');">Design Principles</a></span>.
</p>
<p>A <strong>release package</strong> is a compressed tar file containing
code for a certain version of a release, created by calling
<span class="bold_code"><a href="systools.html#make_tar-1">systools:make_tar/1,2</a></span>.
The release package should be placed in the <span class="code">$ROOT/releases</span>
directory of the previous version of the release where
<span class="code">$ROOT</span> is the installation root directory,
<span class="code">code:root_dir()</span>.
Another <span class="code">releases</span> directory can be specified using the SASL
configuration parameter <span class="code">releases_dir</span>, or the OS environment
variable <span class="code">RELDIR</span>. 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 <span class="code">RELEASES</span>.</p>
<p>A release package should always contain the release resource file
<span class="code">Name.rel</span> and a boot script <span class="code">Name.boot</span>. It may contain
a release upgrade file <span class="code">relup</span> and a system configuration
file <span class="code">sys.config</span>. The <span class="code">.rel</span> file contains information
about the release: its name, version, and which ERTS and
application versions it uses. The <span class="code">relup</span> file contains
scripts for how to upgrade to, or downgrade from, this version of
the release.</p>
<p>The release package can be <strong>unpacked</strong>, which extracts
the files. An unpacked release can be <strong>installed</strong>.
The currently used version of the release is then upgraded or
downgraded to the specified version by evaluating the instructions
in <span class="code">relup</span>. An installed release can be made
<strong>permanent</strong>. 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 <strong>removed</strong>. 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
<span class="code">unpacked</span>, <span class="code">current</span>, <span class="code">permanent</span>, or <span class="code">old</span>.
There is always one latest release which either has status
<span class="code">permanent</span> (normal case), or <span class="code">current</span> (installed, but
not yet made permanent). The following table illustrates
the meaning of the status values:</p>
<div class="example"><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></div>
<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 <strong>Embedded System</strong>. In this case, the system configuration file
<span class="code">sys.config</span> is mandatory.</p>
<p>The installation of a new release may restart the system. Which
program to use is specified by the SASL configuration
parameter <span class="code">start_prg</span> which defaults
to <span class="code">$ROOT/bin/start</span>.</p>
<p>The emulator restart on Windows NT expects that the system is
started using the <span class="code">erlsrv</span> program (as a service).
Furthermore the release handler expects that the service is named
<strong>NodeName</strong>_<strong>Release</strong>, where <strong>NodeName</strong> is
the first part of the Erlang nodename (up to, but not including
the "@") and <strong>Release</strong> is the current version of
the release. The release handler furthermore expects that a
program like <span class="code">start_erl.exe</span> is specified as "machine" to
<span class="code">erlsrv</span>. 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 <span class="code">sasl</span> configuration parameters (see
<span class="bold_code"><a href="sasl_app.html">sasl(6)</a></span> for details):</p>
<dl>
<dt><strong><span class="code">masters</span></strong></dt>
<dd>
<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>
</dd>
<dt><strong><span class="code">client_directory</span></strong></dt>
<dd>
<p>The <span class="code">client_directory</span> in the directory structure of
the master nodes must be specified.</p>
</dd>
<dt><strong><span class="code">static_emulator</span></strong></dt>
<dd>
<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>
</dd>
</dl>
<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>
</p></div>
<h3>EXPORTS</h3>
<p><a name="check_install_release-1"><span class="bold_code">check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}</span></a><br><a name="check_install_release-2"><span class="bold_code">check_install_release(Vsn,Opts) -> {ok, OtherVsn, Descr} | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Vsn = OtherVsn = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Opts = [Opt]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Opt = purge</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Descr = term()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Reason = term()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Checks if the specified version <span class="code">Vsn</span> of the release
can be installed. The release must not have status
<span class="code">current</span>. Issues warnings if <span class="code">relup</span> or
<span class="code">sys.config</span> are not present. If <span class="code">relup</span> is present,
its contents are checked and <span class="code">{error,Reason}</span> is
returned if an error is found. Also checks that all required
applications are present and that all new code can be loaded,
or <span class="code">{error,Reason}</span> is returned.</p>
<p>This function evaluates all instructions that occur before
the <span class="code">point_of_no_return</span> instruction in the release
upgrade script.</p>
<p>Returns the same as <span class="code">install_release/1</span>. <span class="code">Descr</span>
defaults to "" if no <span class="code">relup</span> file is found.</p>
<p>If the option <span class="code">purge</span> is given, all old code that can
be soft purged will be purged after all other checks are
successfully completed. This can be useful in order to
reduce the time needed by <span class="bold_code"><a href="#install_release-1">install_release</a></span>.</p>
</p></div>
<p><a name="create_RELEASES-4"><span class="bold_code">create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Root = RelDir = RelFile = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">AppDirs = [{App, Vsn, Dir}]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code"> App = atom()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code"> Vsn = Dir = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Reason = term()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<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><span class="code">Root</span> is the root of the installation (<span class="code">$ROOT</span>) as
described above. <span class="code">RelDir</span> is the the directory where
the <span class="code">RELEASES</span> file should be created (normally
<span class="code">$ROOT/releases</span>). <span class="code">RelFile</span> is the name
of the <span class="code">.rel</span> file that describes the initial release,
including the extension <span class="code">.rel</span>.</p>
<p><span class="code">AppDirs</span> can be used to specify from where the modules
for the specified applications should be loaded. <span class="code">App</span> is
the name of an application, <span class="code">Vsn</span> is the version, and
<span class="code">Dir</span> is the name of the directory where <span class="code">App-Vsn</span>
is located. The corresponding modules should be located under
<span class="code">Dir/App-Vsn/ebin</span>. The directories for applications not
specified in <span class="code">AppDirs</span> are assumed to be located in
<span class="code">$ROOT/lib</span>.</p>
</p></div>
<p><a name="install_file-2"><span class="bold_code">install_file(Vsn, File) -> ok | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Vsn = File = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Reason = term()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<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:
<span class="code">start.boot</span>, <span class="code">relup</span> and <span class="code">sys.config</span>.</p>
<p>The function can be called, for example, when these files
are generated at the target. It should be called after
<span class="code">set_unpacked/2</span> has been called.</p>
</p></div>
<p><a name="install_release-1"><span class="bold_code">install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}</span></a><br><a name="install_release-2"><span class="bold_code">install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_after_restart, OtherVsn, Descr} | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Vsn = OtherVsn = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Opt = {error_action, Action} | {code_change_timeout, Timeout}</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code"> | {suspend_timeout, Timeout} | {update_paths, Bool}</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code"> Action = restart | reboot</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code"> Timeout = default | infinity | int()>0</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code"> Bool = boolean()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Descr = term()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | {missing_base_app, OtherVsn, App} | {could_not_create_hybrid_boot, term()} | term()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">App = atom()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Installs the specified version <span class="code">Vsn</span> of the release.
Looks first for a <span class="code">relup</span> file for <span class="code">Vsn</span> and a
script <span class="code">{UpFromVsn,Descr1,Instructions1}</span> in this file
for upgrading from the current version. If not found,
the function looks for a <span class="code">relup</span> file for the current
version and a script <span class="code">{Vsn,Descr2,Instructions2}</span> in this
file for downgrading to <span class="code">Vsn</span>.</p>
<p>If a script is found, the first thing that happens is that
the applications specifications are updated according to
the <span class="code">.app</span> files and <span class="code">sys.config</span> belonging to
the release version <span class="code">Vsn</span>.</p>
<p>After the application specifications have been updated,
the instructions in the script are evaluated and the function
returns <span class="code">{ok,OtherVsn,Descr}</span> if successful.
<span class="code">OtherVsn</span> and <span class="code">Descr</span> are the version
(<span class="code">UpFromVsn</span> or <span class="code">Vsn</span>) and description
(<span class="code">Descr1</span> or <span class="code">Descr2</span>) as specified in the script.</p>
<p>If <span class="code">{continue_after_restart,OtherVsn,Descr}</span> is
returned, it means that the emulator will be restarted
before the upgrade instructions are executed. This will
happen if the emulator or any of the applications kernel,
stdlib or sasl are updated. The new version of the emulator
and these core applications will execute after the restart,
but for all other applications the old versions will be
started and the upgrade will be performed as normal by
executing the upgrade instructions.</p>
<p>If a recoverable error occurs, the function returns
<span class="code">{error,Reason}</span> and the original application
specifications are restored. If a non-recoverable error
occurs, the system is restarted.</p>
<p>The option <span class="code">error_action</span> defines if the node should be
restarted (<span class="code">init:restart()</span>) or rebooted
(<span class="code">init:reboot()</span>) in case of an error during
the installation. Default is <span class="code">restart</span>.</p>
<p>The option <span class="code">code_change_timeout</span> defines the timeout
for all calls to <span class="code">sys:change_code</span>. If no value is
specified or <span class="code">default</span> is given, the default value
defined in <span class="code">sys</span> is used.</p>
<p>The option <span class="code">suspend_timeout</span> defines the timeout for
all calls to <span class="code">sys:suspend</span>. If no value is specified,
the values defined by the <span class="code">Timeout</span> parameter of
the <span class="code">upgrade</span> or <span class="code">suspend</span> instructions are used.
If <span class="code">default</span> is specified, the default value defined in
<span class="code">sys</span> is used.</p>
<p>The option <span class="code">{update_paths,Bool}</span> indicates if all
application code paths should be updated (<span class="code">Bool==true</span>),
or if only code paths for modified applications should be
updated (<span class="code">Bool==false</span>, default). This option only has
effect for other application directories than the default
<span class="code">$ROOT/lib/App-Vsn</span>, that is, application directories
provided in the <span class="code">AppDirs</span> argument in a call to
<span class="code">create_RELEASES/4</span> or <span class="code">set_unpacked/2</span>.</p>
<p>Example: In the current version <span class="code">CurVsn</span> of a release,
the application directory of <span class="code">myapp</span> is
<span class="code">$ROOT/lib/myapp-1.0</span>. A new version <span class="code">NewVsn</span> is
unpacked outside the release handler, and the release handler
is informed about this with a call to:</p>
<div class="example"><pre>
release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).
=> {ok,NewVsn}
</pre></div>
<p>If <span class="code">NewVsn</span> is installed with the option
<span class="code">{update_paths,true}</span>, afterwards
<span class="code">code:lib_dir(myapp)</span> will return
<span class="code">/home/user/myapp-1.0</span>.</p>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>Installing a new release might be quite time consuming if
there are many processes in the system. The reason is that
each process must be checked for references to old code
before a module can be purged. This check might lead to
garbage collections and copying of data.</p>
<p>If you wish to speed up the execution of
<span class="code">install_release</span>, then you may call <span class="bold_code"><a href="#check_install_release-1">check_install_release</a></span>
first, using the option <span class="code">purge</span>. This will do the same
check for old code, and then purge all modules that can be
soft purged. The purged modules will then no longer have any
old code, and <span class="code">install_release</span> will not need to do the
checks.</p>
<p>Obviously, this will not reduce the overall time for the
upgrade, but it will allow checks and purge to be executed
in the background before the real upgrade is started.</p>
</p></div>
</div>
<div class="note">
<div class="label">Note</div>
<div class="content"><p>
<p>When upgrading the emulator from a version older than OTP
R15, there will be an attempt to load new application beam
code into the old emulator. In some cases, the new beam
format can not be read by the old emulator, and so the code
loading will fail and terminate the complete upgrade. To
overcome this problem, the new application code should be
compiled with the old emulator. See <span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','doc/design_principles','appup_cookbook.html');">Design
Principles</a></span> for more information about emulator
upgrade from pre OTP R15 versions.</p>
</p></div>
</div>
</p></div>
<p><a name="make_permanent-1"><span class="bold_code">make_permanent(Vsn) -> ok | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Vsn = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Reason = {bad_status, Status} | term()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Makes the specified version <span class="code">Vsn</span> of the release
permanent.</p>
</p></div>
<p><a name="remove_release-1"><span class="bold_code">remove_release(Vsn) -> ok | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Vsn = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Reason = {permanent, Vsn} | client_node | term()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<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>
</p></div>
<p><a name="reboot_old_release-1"><span class="bold_code">reboot_old_release(Vsn) -> ok | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Vsn = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Reason = {bad_status, Status} | term()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Reboots the system by making the old release permanent, and
calls <span class="code">init:reboot()</span> directly. The release must have
status <span class="code">old</span>.</p>
</p></div>
<p><a name="set_removed-1"><span class="bold_code">set_removed(Vsn) -> ok | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Vsn = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Reason = {permanent, Vsn} | term()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<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>
</p></div>
<p><a name="set_unpacked-2"><span class="bold_code">set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">RelFile = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">AppDirs = [{App, Vsn, Dir}]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code"> App = atom()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code"> Vsn = Dir = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Reason = term()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Makes it possible to handle unpacking of releases outside
the release handler. Tells the release handler that
the release is unpacked. <span class="code">Vsn</span> is extracted from
the release resource file <span class="code">RelFile</span>.</p>
<p><span class="code">AppDirs</span> can be used to specify from where the modules
for the specified applications should be loaded. <span class="code">App</span> is
the name of an application, <span class="code">Vsn</span> is the version, and
<span class="code">Dir</span> is the name of the directory where <span class="code">App-Vsn</span>
is located. The corresponding modules should be located under
<span class="code">Dir/App-Vsn/ebin</span>. The directories for applications not
specified in <span class="code">AppDirs</span> are assumed to be located in
<span class="code">$ROOT/lib</span>.</p>
</p></div>
<p><a name="unpack_release-1"><span class="bold_code">unpack_release(Name) -> {ok, Vsn} | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Name = Vsn = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Reason = client_node | term()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Unpacks a release package <span class="code">Name.tar.gz</span> located in
the <span class="code">releases</span> directory.</p>
<p>Performs some checks on the package - for example checks
that all mandatory files are present - and extracts its
contents.</p>
</p></div>
<p><a name="which_releases-0"><span class="bold_code">which_releases() -> [{Name, Vsn, Apps, Status}]</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Name = Vsn = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Apps = ["App-Vsn"]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Status = unpacked | current | permanent | old</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Returns all releases known to the release handler.</p>
</p></div>
<p><a name="which_releases-1"><span class="bold_code">which_releases(Status) -> [{Name, Vsn, Apps, Status}]</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">Name = Vsn = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Apps = ["App-Vsn"]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Status = unpacked | current | permanent | old</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Returns all releases known to the release handler of a specific status.</p>
</p></div>
<h3><a name="id70513">Application Upgrade/Downgrade</a></h3>
<div class="REFBODY">
<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 <span class="code">relup</span> is created
on-the-fly, based on the <span class="code">.appup</span> file for the application,
and evaluated exactly in the same way as <span class="code">release_handler</span>
does.</p>
<div class="warning">
<div class="label">Warning</div>
<div class="content"><p>
<p>These functions are primarily intended for simplified testing
of <span class="code">.appup</span> files. They are not run within the context of
the <span class="code">release_handler</span> process. They must therefore
<strong>not</strong> be used together with calls to
<span class="code">install_release/1,2</span>, as this will cause
<span class="code">release_handler</span> 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 affect 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>
</p></div>
</div>
</div>
<h3>EXPORTS</h3>
<p><a name="upgrade_app-2"><span class="bold_code">upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">App = atom()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Dir = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Unpurged = [Module]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code"> Module = atom()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Reason = term()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Upgrades an application <span class="code">App</span> from the current
version to a new version located in <span class="code">Dir</span> according to
the <span class="code">.appup</span> script.</p>
<p><span class="code">App</span> is the name of the application, which must be
started. <span class="code">Dir</span> is the new library directory of
<span class="code">App</span>, the corresponding modules as well as
the <span class="code">.app</span> and <span class="code">.appup</span> files should be located
under <span class="code">Dir/ebin</span>.</p>
<p>The function looks in the <span class="code">.appup</span> file and tries to
find an upgrade script from the current version of
the application using
<span class="bold_code"><a href="#upgrade_script-2">upgrade_script/2</a></span>.
This script is evaluated using
<span class="bold_code"><a href="#eval_appup_script-4">eval_appup_script/4</a></span>,
exactly in the same way as
<span class="bold_code"><a href="#install_release-1">install_release/1,2</a></span>
does.</p>
<p>Returns <span class="code">{ok, Unpurged}</span> if evaluating the script is
successful, where <span class="code">Unpurged</span> is a list of unpurged
modules, or <span class="code">restart_emulator</span> if this instruction is
encountered in the script, or <span class="code">{error, Reason}</span> if
an error occurred when finding or evaluating the script.</p>
<p>If the <span class="code">restart_new_emulator</span> instruction is found in
the script, <span class="code">upgrade_app/2</span> will return
<span class="code">{error,restart_new_emulator}</span>. The reason for this is
that this instruction requires that a new version of the
emulator is started before the rest of the upgrade
instructions can be executed, and this can only be done by
<span class="code">install_release/1,2</span>.</p>
</p></div>
<p><a name="downgrade_app-2"><span class="bold_code">downgrade_app(App, Dir) -></span></a><br><a name="downgrade_app-3"><span class="bold_code">downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">App = atom()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Dir = OldVsn = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Unpurged = [Module]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code"> Module = atom()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Reason = term()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Downgrades an application <span class="code">App</span> from the current
version to a previous version <span class="code">OldVsn</span> located in
<span class="code">Dir</span> according to the <span class="code">.appup</span> script.</p>
<p><span class="code">App</span> is the name of the application, which must be
started. <span class="code">OldVsn</span> is the previous version of
the application and can be omitted if <span class="code">Dir</span> is of
the format <span class="code">"App-OldVsn"</span>. <span class="code">Dir</span> is the library
directory of this previous version of <span class="code">App</span>,
the corresponding modules as well as the old <span class="code">.app</span> file
should be located under <span class="code">Dir/ebin</span>. The <span class="code">.appup</span>
file should be located in the <span class="code">ebin</span> directory of
the <strong>current</strong> library directory of the application
(<span class="code">code:lib_dir(App)</span>).</p>
<p>The function looks in the <span class="code">.appup</span> file and tries to
find an downgrade script to the previous version of
the application using
<span class="bold_code"><a href="#downgrade_script-3">downgrade_script/3</a></span>.
This script is evaluated using
<span class="bold_code"><a href="#eval_appup_script-4">eval_appup_script/4</a></span>,
exactly in the same way as
<span class="bold_code"><a href="#install_release-1">install_release/1,2</a></span>
does.</p>
<p>Returns <span class="code">{ok, Unpurged}</span> if evaluating the script is
successful, where <span class="code">Unpurged</span> is a list of unpurged
modules, or <span class="code">restart_emulator</span> if this instruction is
encountered in the script, or <span class="code">{error, Reason}</span> if
an error occurred when finding or evaluating the script.</p>
</p></div>
<p><a name="upgrade_script-2"><span class="bold_code">upgrade_script(App, Dir) -> {ok, NewVsn, Script}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">App = atom()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Dir = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">NewVsn = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Script = Instructions -- see appup(4)</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Tries to find an application upgrade script for <span class="code">App</span>
from the current version to a new version located in
<span class="code">Dir</span>.</p>
<p>The upgrade script can then be evaluated using
<span class="bold_code"><a href="#eval_appup_script-4">eval_appup_script/4</a></span>.
It is recommended to use
<span class="bold_code"><a href="#upgrade_app-2">upgrade_app/2</a></span>
instead, but this function is useful in order to inspect
the contents of the script.</p>
<p><span class="code">App</span> is the name of the application, which must be
started. <span class="code">Dir</span> is the new library directory of
<span class="code">App</span>, the corresponding modules as well as
the <span class="code">.app</span> and <span class="code">.appup</span> files should be located
under <span class="code">Dir/ebin</span>.</p>
<p>The function looks in the <span class="code">.appup</span> 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 <span class="code">relup</span> script.</p>
<p>Returns <span class="code">{ok, NewVsn, Script}</span> if successful, where
<span class="code">NewVsn</span> is the new application version.</p>
<p>Failure: If a script cannot be found, the function fails
with an appropriate error reason.</p>
</p></div>
<p><a name="downgrade_script-3"><span class="bold_code">downgrade_script(App, OldVsn, Dir) -> {ok, Script}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">App = atom()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">OldVsn = Dir = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Script = Instructions -- see appup(4)</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Tries to find an application downgrade script for <span class="code">App</span>
from the current version to a previous version <span class="code">OldVsn</span>
located in <span class="code">Dir</span>.</p>
<p>The downgrade script can then be evaluated using
<span class="bold_code"><a href="#eval_appup_script-4">eval_appup_script/4</a></span>.
It is recommended to use
<span class="bold_code"><a href="#downgrade_app-2">downgrade_app/2,3</a></span>
instead, but this function is useful in order to inspect
the contents of the script.</p>
<p><span class="code">App</span> is the name of the application, which must be
started. <span class="code">Dir</span> is the previous library directory of
<span class="code">App</span>, the corresponding modules as well as
the old <span class="code">.app</span> file should be located under
<span class="code">Dir/ebin</span>. The <span class="code">.appup</span> file should be located in
the <span class="code">ebin</span> directory of the <strong>current</strong> library
directory of the application (<span class="code">code:lib_dir(App)</span>).</p>
<p>The function looks in the <span class="code">.appup</span> 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 <span class="code">relup</span> script.</p>
<p>Returns <span class="code">{ok, Script}</span> if successful.</p>
<p>Failure: If a script cannot be found, the function fails
with an appropriate error reason.</p>
</p></div>
<p><a name="eval_appup_script-4"><span class="bold_code">eval_appup_script(App, ToVsn, ToDir, Script) -> {ok, Unpurged} | restart_emulator | {error, Reason}</span></a><br></p>
<div class="REFBODY">
<p>Types:</p>
<div class="REFTYPES">
<span class="bold_code">App = atom()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">ToVsn = ToDir = string()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Script -- see upgrade_script/2, downgrade_script/3</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Unpurged = [Module]</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code"> Module = atom()</span><br>
</div>
<div class="REFTYPES">
<span class="bold_code">Reason = term()</span><br>
</div>
</div>
<div class="REFBODY"><p>
<p>Evaluates an application upgrade or downgrade script
<span class="code">Script</span>, the result from calling
<span class="bold_code"><a href="#upgrade_app-2">upgrade_script/2</a></span> or
<span class="bold_code"><a href="#downgrade_app-3">downgrade_script/3</a></span>,
exactly in the same way as
<span class="bold_code"><a href="#install_release-1">install_release/1,2</a></span>
does.</p>
<p><span class="code">App</span> is the name of the application, which must be
started. <span class="code">ToVsn</span> is the version to be upgraded/downgraded
to, and <span class="code">ToDir</span> is the library directory of this version.
The corresponding modules as well as the <span class="code">.app</span> and
<span class="code">.appup</span> files should be located under <span class="code">Dir/ebin</span>.</p>
<p>Returns <span class="code">{ok, Unpurged}</span> if evaluating the script is
successful, where <span class="code">Unpurged</span> is a list of unpurged
modules, or <span class="code">restart_emulator</span> if this instruction is
encountered in the script, or <span class="code">{error, Reason}</span> if
an error occurred when evaluating the script.</p>
<p>If the <span class="code">restart_new_emulator</span> instruction is found in
the script, <span class="code">eval_appup_script/4</span> will return
<span class="code">{error,restart_new_emulator}</span>. The reason for this is
that this instruction requires that a new version of the
emulator is started before the rest of the upgrade
instructions can be executed, and this can only be done by
<span class="code">install_release/1,2</span>.</p>
</p></div>
<h3><a name="id71266">Typical Error Reasons</a></h3>
<div class="REFBODY">
<ul>
<li>
<p><span class="code">{bad_masters, Masters}</span> - The master nodes
<span class="code">Masters</span> are not alive.</p>
</li>
<li>
<p><span class="code">{bad_rel_file, File}</span> - Specified <span class="code">.rel</span> file
<span class="code">File</span> can not be read, or does not contain a single
term.</p>
</li>
<li>
<p><span class="code">{bad_rel_data, Data}</span> - Specified <span class="code">.rel</span> file
does not contain a recognized release specification, but
another term <span class="code">Data</span>.</p>
</li>
<li>
<p><span class="code">{bad_relup_file, File}</span> - Specified <span class="code">relup</span> file
<span class="code">Relup</span> contains bad data.</p>
</li>
<li>
<p><span class="code">{cannot_extract_file, Name, Reason}</span> - Problems when
extracting from a tar file, <span class="code">erl_tar:extract/2</span> returned
<span class="code">{error, {Name, Reason}}</span>.</p>
</li>
<li>
<p><span class="code">{existing_release, Vsn}</span> - Specified release version
<span class="code">Vsn</span> is already in use.</p>
</li>
<li>
<p><span class="code">{Master, Reason, When}</span> - Some operation, indicated by
the term <span class="code">When</span>, failed on the master node <span class="code">Master</span>
with the specified error reason <span class="code">Reason</span>.</p>
</li>
<li>
<p><span class="code">{no_matching_relup, Vsn, CurrentVsn}</span> - Cannot find a
script for up/downgrading between <span class="code">CurrentVsn</span> and
<span class="code">Vsn</span>.</p>
</li>
<li>
<p><span class="code">{no_such_directory, Path}</span> - The directory <span class="code">Path</span>
does not exist.</p>
</li>
<li>
<p><span class="code">{no_such_file, Path}</span> - The path <span class="code">Path</span> (file or
directory) does not exist.</p>
</li>
<li>
<p><span class="code">{no_such_file, {Master, Path}}</span> - The path <span class="code">Path</span>
(file or directory) does not exist at the master node
<span class="code">Master</span>.</p>
</li>
<li>
<p><span class="code">{no_such_release, Vsn}</span> - The specified version
<span class="code">Vsn</span> of the release does not exist.</p>
</li>
<li>
<p><span class="code">{not_a_directory, Path}</span> - <span class="code">Path</span> exists, but is
not a directory.</p>
</li>
<li>
<p><span class="code">{Posix, File}</span> - Some file operation failed for
<span class="code">File</span>. <span class="code">Posix</span> is an atom named from the Posix
error codes, such as <span class="code">enoent</span>, <span class="code">eacces</span> or
<span class="code">eisdir</span>. See <span class="code">file(3)</span>.</p>
</li>
<li>
<p><span class="code">Posix</span> - Some file operation failed, as above.</p>
</li>
</ul>
</div>
<h3><a name="id71533">SEE ALSO</a></h3>
<div class="REFBODY">
<p><span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','doc/design_principles','release_handling.html');">OTP Design Principles</a></span>,
<span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','kernel','config.html');">config(4)</a></span>,
<span class="bold_code"><a href="relup.html">relup(4)</a></span>,
<span class="bold_code"><a href="rel.html">rel(4)</a></span>,
<span class="bold_code"><a href="script.html">script(4)</a></span>,
<span class="bold_code"><a href="javascript:erlhref('../../../../doc/../','stdlib','sys.html');">sys(3)</a></span>,
<span class="bold_code"><a href="systools.html">systools(3)</a></span></p>
</div>
</div>
<div class="footer">
<hr>
<p>Copyright © 1997-2012 Ericsson AB. All Rights Reserved.</p>
</div>
</div>
</div></body>
</html>
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
675c8c8167236dfcf8d66da674f931e8
>
files
>
1259
