aboutsummaryrefslogtreecommitdiffstats
path: root/lib/sasl/doc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/sasl/doc')
-rw-r--r--lib/sasl/doc/html/.gitignore0
-rw-r--r--lib/sasl/doc/man3/.gitignore0
-rw-r--r--lib/sasl/doc/man4/.gitignore0
-rw-r--r--lib/sasl/doc/man6/.gitignore0
-rw-r--r--lib/sasl/doc/pdf/.gitignore0
-rw-r--r--lib/sasl/doc/src/Makefile133
-rw-r--r--lib/sasl/doc/src/alarm_handler.xml125
-rw-r--r--lib/sasl/doc/src/appup.xml330
-rw-r--r--lib/sasl/doc/src/book.xml49
-rw-r--r--lib/sasl/doc/src/error_logging.xml385
-rw-r--r--lib/sasl/doc/src/fascicules.xml18
-rw-r--r--lib/sasl/doc/src/make.dep22
-rw-r--r--lib/sasl/doc/src/note.gifbin0 -> 1539 bytes
-rw-r--r--lib/sasl/doc/src/notes.xml319
-rw-r--r--lib/sasl/doc/src/notes_history.xml128
-rw-r--r--lib/sasl/doc/src/overload.xml151
-rw-r--r--lib/sasl/doc/src/part.xml38
-rw-r--r--lib/sasl/doc/src/part_notes.xml38
-rw-r--r--lib/sasl/doc/src/part_notes_history.xml38
-rw-r--r--lib/sasl/doc/src/rb.xml206
-rw-r--r--lib/sasl/doc/src/ref_man.xml46
-rw-r--r--lib/sasl/doc/src/rel.xml105
-rw-r--r--lib/sasl/doc/src/rel/bar.1.erl17
-rw-r--r--lib/sasl/doc/src/rel/bar.2.erl13
-rw-r--r--lib/sasl/doc/src/rel/ge_h.1.erl28
-rw-r--r--lib/sasl/doc/src/rel/ge_h.2.erl31
-rw-r--r--lib/sasl/doc/src/rel/gs1.1.erl30
-rw-r--r--lib/sasl/doc/src/rel/gs1.2.erl35
-rw-r--r--lib/sasl/doc/src/rel/gs1.3.erl36
-rw-r--r--lib/sasl/doc/src/rel/gs2.1.erl31
-rw-r--r--lib/sasl/doc/src/rel/gs2.2.erl38
-rw-r--r--lib/sasl/doc/src/rel/lists2.1.erl8
-rw-r--r--lib/sasl/doc/src/rel/lists2.2.erl13
-rw-r--r--lib/sasl/doc/src/rel/portc.1.erl31
-rw-r--r--lib/sasl/doc/src/rel/portc.2.erl34
-rw-r--r--lib/sasl/doc/src/rel/sp.1.erl46
-rw-r--r--lib/sasl/doc/src/rel/sp.2.erl58
-rw-r--r--lib/sasl/doc/src/rel/sup.1.erl11
-rw-r--r--lib/sasl/doc/src/rel/sup.2.erl10
-rw-r--r--lib/sasl/doc/src/release_handler.xml697
-rw-r--r--lib/sasl/doc/src/relup.xml93
-rw-r--r--lib/sasl/doc/src/sasl_app.xml182
-rw-r--r--lib/sasl/doc/src/sasl_intro.xml51
-rw-r--r--lib/sasl/doc/src/script.xml168
-rw-r--r--lib/sasl/doc/src/systools.xml362
-rw-r--r--lib/sasl/doc/src/warning.gifbin0 -> 1498 bytes
46 files changed, 4154 insertions, 0 deletions
diff --git a/lib/sasl/doc/html/.gitignore b/lib/sasl/doc/html/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/sasl/doc/html/.gitignore
diff --git a/lib/sasl/doc/man3/.gitignore b/lib/sasl/doc/man3/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/sasl/doc/man3/.gitignore
diff --git a/lib/sasl/doc/man4/.gitignore b/lib/sasl/doc/man4/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/sasl/doc/man4/.gitignore
diff --git a/lib/sasl/doc/man6/.gitignore b/lib/sasl/doc/man6/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/sasl/doc/man6/.gitignore
diff --git a/lib/sasl/doc/pdf/.gitignore b/lib/sasl/doc/pdf/.gitignore
new file mode 100644
index 0000000000..e69de29bb2
--- /dev/null
+++ b/lib/sasl/doc/pdf/.gitignore
diff --git a/lib/sasl/doc/src/Makefile b/lib/sasl/doc/src/Makefile
new file mode 100644
index 0000000000..eb880ccb78
--- /dev/null
+++ b/lib/sasl/doc/src/Makefile
@@ -0,0 +1,133 @@
+# ``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 via the world wide web 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.
+#
+# The Initial Developer of the Original Code is Ericsson Utvecklings AB.
+# Portions created by Ericsson are Copyright 1999, Ericsson Utvecklings
+# AB. All Rights Reserved.''
+#
+# $Id$
+#
+include $(ERL_TOP)/make/target.mk
+include $(ERL_TOP)/make/$(TARGET)/otp.mk
+
+# ----------------------------------------------------
+# Application version
+# ----------------------------------------------------
+include ../../vsn.mk
+VSN=$(SASL_VSN)
+APPLICATION=sasl
+
+# ----------------------------------------------------
+# Release directory specification
+# ----------------------------------------------------
+RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN)
+
+# ----------------------------------------------------
+# Target Specs
+# ----------------------------------------------------
+XML_APPLICATION_FILES = ref_man.xml
+XML_REF3_FILES = alarm_handler.xml \
+ overload.xml \
+ rb.xml \
+ release_handler.xml \
+ systools.xml
+
+XML_REF4_FILES = appup.xml rel.xml relup.xml script.xml
+
+XML_REF6_FILES = sasl_app.xml
+
+XML_PART_FILES = part.xml part_notes.xml part_notes_history.xml
+XML_CHAPTER_FILES = sasl_intro.xml \
+ error_logging.xml \
+ notes.xml \
+ notes_history.xml
+
+BOOK_FILES = book.xml
+
+GIF_FILES = \
+ note.gif \
+ warning.gif
+
+XML_FILES = \
+ $(BOOK_FILES) $(XML_CHAPTER_FILES) \
+ $(XML_PART_FILES) $(XML_REF3_FILES) $(XML_REF4_FILES) \
+ $(XML_REF6_FILES) $(XML_APPLICATION_FILES)
+
+
+# ----------------------------------------------------
+
+HTML_FILES = $(XML_APPLICATION_FILES:%.xml=$(HTMLDIR)/%.html) \
+ $(XML_PART_FILES:%.xml=$(HTMLDIR)/%.html)
+
+INFO_FILE = ../../info
+
+MAN3_FILES = $(XML_REF3_FILES:%.xml=$(MAN3DIR)/%.3)
+MAN4_FILES = $(XML_REF4_FILES:%.xml=$(MAN4DIR)/%.4)
+MAN6_FILES = $(XML_REF6_FILES:%_app.xml=$(MAN6DIR)/%.6)
+
+HTML_REF_MAN_FILE = $(HTMLDIR)/index.html
+
+TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf
+
+# ----------------------------------------------------
+# FLAGS
+# ----------------------------------------------------
+XML_FLAGS +=
+
+# ----------------------------------------------------
+# Targets
+# ----------------------------------------------------
+$(HTMLDIR)/%.gif: %.gif
+ $(INSTALL_DATA) $< $@
+
+docs: pdf html man
+
+$(TOP_PDF_FILE): $(XML_FILES)
+
+pdf: $(TOP_PDF_FILE)
+
+html: gifs $(HTML_REF_MAN_FILE)
+
+man: $(MAN3_FILES) $(MAN4_FILES) $(MAN6_FILES)
+
+gifs: $(GIF_FILES:%=$(HTMLDIR)/%) # We depend just to copy them to ../html
+
+debug opt:
+
+clean clean_docs:
+ rm -rf $(HTMLDIR)/*
+ rm -f $(MAN3DIR)/*
+ rm -f $(MAN4DIR)/*
+ rm -f $(MAN6DIR)/*
+ rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo)
+ rm -f errs core *~
+
+# ----------------------------------------------------
+# Release Target
+# ----------------------------------------------------
+include $(ERL_TOP)/make/otp_release_targets.mk
+
+release_docs_spec: docs
+ $(INSTALL_DIR) $(RELSYSDIR)/doc/pdf
+ $(INSTALL_DATA) $(TOP_PDF_FILE) $(RELSYSDIR)/doc/pdf
+ $(INSTALL_DIR) $(RELSYSDIR)/doc/html
+ $(INSTALL_DATA) $(HTMLDIR)/* \
+ $(RELSYSDIR)/doc/html
+ $(INSTALL_DATA) $(INFO_FILE) $(RELSYSDIR)
+ $(INSTALL_DIR) $(RELEASE_PATH)/man/man3
+ $(INSTALL_DATA) $(MAN3DIR)/* $(RELEASE_PATH)/man/man3
+ $(INSTALL_DIR) $(RELEASE_PATH)/man/man4
+ $(INSTALL_DATA) $(MAN4_FILES) $(RELEASE_PATH)/man/man4
+ $(INSTALL_DIR) $(RELEASE_PATH)/man/man6
+ $(INSTALL_DATA) $(MAN6_FILES) $(RELEASE_PATH)/man/man6
+
+release_spec:
+
diff --git a/lib/sasl/doc/src/alarm_handler.xml b/lib/sasl/doc/src/alarm_handler.xml
new file mode 100644
index 0000000000..e4501ce5f0
--- /dev/null
+++ b/lib/sasl/doc/src/alarm_handler.xml
@@ -0,0 +1,125 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1996</year>
+ <year>2007</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.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>alarm_handler</title>
+ <prepared>Martin Bj&ouml;rklund</prepared>
+ <responsible>Bjarne Dacker</responsible>
+ <docno></docno>
+ <approved>Bjarne D&auml;cker</approved>
+ <checked>Martin Bj&ouml;rklund</checked>
+ <date>1996-09-10</date>
+ <rev>A</rev>
+ <file>alarm_handler.sgml.t1</file>
+ </header>
+ <module>alarm_handler</module>
+ <modulesummary>An Alarm Handling Process</modulesummary>
+ <description>
+ <p>The alarm handler process is a <c>gen_event</c> event manager
+ process which receives alarms in the system. This process is not
+ intended to be a complete alarm handler. It defines a
+ place to which alarms can be sent. One simple event handler is
+ installed in the alarm handler at start-up, but users are
+ encouraged to write and install their own handlers.
+ </p>
+ <p>The simple event handler sends all alarms as info reports to
+ the error logger, and saves all of them in a list which can be
+ passed to a user defined event handler, which may be installed at
+ a later stage. The list can grow large if many alarms are
+ generated. So it is a good reason to install a better user defined
+ handler.
+ </p>
+ <p>There are functions to set and clear alarms. The format of
+ alarms are defined by the user. For example, an event handler
+ for SNMP could be defined, together with an alarm MIB.
+ </p>
+ <p>The alarm handler is part of the SASL application.
+ </p>
+ <p>When writing new event handlers for the alarm handler, the
+ following events must be handled:
+ </p>
+ <taglist>
+ <tag><c>{set_alarm, {AlarmId, AlarmDescr}}</c></tag>
+ <item>
+ <p>This event is generated by
+ <c>alarm_handler:set_alarm({AlarmId, AlarmDecsr})</c>.
+ </p>
+ </item>
+ <tag><c>{clear_alarm, AlarmId}</c></tag>
+ <item>
+ <p>This event is
+ generated by <c>alarm_handler:clear_alarm(AlarmId)</c>.
+ </p>
+ </item>
+ </taglist>
+ <p>The default simple handler is called <c>alarm_handler</c> and
+ it may be exchanged by calling <c>gen_event:swap_handler/3</c>
+ as <c>gen_event:swap_handler(alarm_handler, {alarm_handler, swap}, {NewHandler, Args})</c>. <c>NewHandler:init({Args, {alarm_handler, Alarms}})</c> is called. Refer to gen_event(3)
+ for further details.
+ </p>
+ </description>
+ <funcs>
+ <func>
+ <name>clear_alarm(AlarmId) -> void()</name>
+ <fsummary>Clear the specified alarms</fsummary>
+ <type>
+ <v>AlarmId = term()</v>
+ </type>
+ <desc>
+ <p>Clears all alarms with id <c>AlarmId</c>.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>get_alarms() -> [alarm()]</name>
+ <fsummary>Get all active alarms</fsummary>
+ <desc>
+ <p>Returns a list of all active alarms. This function can only
+ be used when the simple handler is installed.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>set_alarm(alarm())</name>
+ <fsummary>Set an alarm with an id</fsummary>
+ <type>
+ <v>alarm() = {AlarmId, AlarmDescription}</v>
+ <v>AlarmId = term()</v>
+ <v>AlarmDescription = term()</v>
+ </type>
+ <desc>
+ <p>Sets an alarm with id <c>AlarmId</c>. This id is used at a
+ later stage when the alarm is cleared.
+ </p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>See Also</title>
+ <p>error_logger(3), gen_event(3)
+ </p>
+ </section>
+</erlref>
+
diff --git a/lib/sasl/doc/src/appup.xml b/lib/sasl/doc/src/appup.xml
new file mode 100644
index 0000000000..5182889710
--- /dev/null
+++ b/lib/sasl/doc/src/appup.xml
@@ -0,0 +1,330 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE fileref SYSTEM "fileref.dtd">
+
+<fileref>
+ <header>
+ <copyright>
+ <year>1997</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>appup</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <file>appup</file>
+ <filesummary>Application upgrade file.</filesummary>
+ <description>
+ <p>The <em>application upgrade file</em> defines how an application
+ is upgraded or downgraded in a running system.</p>
+ <p>This file is used by the functions in <c>systools</c> when
+ generating a release upgrade file <c>relup</c>.</p>
+ </description>
+
+ <section>
+ <title>FILE SYNTAX</title>
+ <p>The application upgrade file should be called
+ <c>Application.appup</c> where <c>Application</c> is the name of
+ the application. The file should be located in the <c>ebin</c>
+ directory for the application.</p>
+ <p>The <c>.appup</c> file contains one single Erlang term, which
+ defines the instructions used to upgrade or downgrade
+ the application. The file has the following syntax:</p>
+ <code type="none">
+{Vsn,
+ [{UpFromVsn, Instructions}, ...],
+ [{DownToVsn, Instructions}, ...]}.
+ </code>
+ <list type="bulleted">
+ <item>
+ <p><c>Vsn = string()</c> is the current version of
+ the application.</p>
+ </item>
+ <item>
+ <p><c>UpFromVsn = string()</c> is an earlier version of
+ the application to upgrade from.</p>
+ </item>
+ <item>
+ <p><c>DownToVsn = string()</c> is an earlier version of
+ the application to downgrade to.</p>
+ </item>
+ <item>
+ <p><c>Instructions</c> is a list of <em>release upgrade instructions</em>, see below. It is recommended to use
+ high-level instructions only. These are automatically
+ translated to low-level instructions by <c>systools</c> when
+ creating the <c>relup</c> file.</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>RELEASE UPGRADE INSTRUCTIONS</title>
+ <p>Release upgrade instructions are interpreted by the release
+ handler when an upgrade or downgrade is made. For more
+ information about release handling, refer to <em>OTP Design Principles</em>.</p>
+ <p>A process is said to <em>use</em> a module <c>Mod</c>, if
+ <c>Mod</c> is listed in the <c>Modules</c> part of the child
+ specification used to start the process, see <c>supervisor(3)</c>.
+ In the case of gen_event, an event manager process is said to use
+ <c>Mod</c> if <c>Mod</c> is an installed event handler.</p>
+ <p><em>High-level instructions</em></p>
+ <pre>
+{update, Mod}
+{update, Mod, supervisor}
+{update, Mod, Change}
+{update, Mod, DepMods}
+{update, Mod, Change, DepMods}
+{update, Mod, Change, PrePurge, PostPurge, DepMods}
+{update, Mod, Timeout, Change, PrePurge, PostPurge, DepMods}
+{update, Mod, ModType, Timeout, Change, PrePurge, PostPurge, DepMods}
+ Mod = atom()
+ ModType = static | dynamic
+ Timeout = int()>0 | default | infinity
+ Change = soft | {advanced,Extra}
+ Extra = term()
+ PrePurge = PostPurge = soft_purge | brutal_purge
+ DepMods = [Mod]
+ </pre>
+ <p>Synchronized code replacement of processes using the module
+ <c>Mod</c>. All those processes are suspended using
+ <c>sys:suspend</c>, the new version of the module is loaded and
+ then the processes are resumed using <c>sys:resume</c>.</p>
+ <p><c>Change</c> defaults to <c>soft</c> and defines the type of
+ code change. If it is set to <c>{advanced,Extra}</c>, processes
+ implemented using gen_server, gen_fsm or gen_event will transform
+ their internal state by calling the callback function
+ <c>code_change</c>. Special processes will call the callback
+ function <c>system_code_change/4</c>. In both cases, the term
+ <c>Extra</c> is passed as an argument to the callback function.</p>
+ <p><c>PrePurge</c> defaults to <c>brutal_purge</c> and controls
+ what action to take with processes that are executing old code
+ before loading the new version of the module. If the value
+ is <c>brutal_purge</c>, the processes are killed. If the value is
+ <c>soft_purge</c>, <c>release_handler:install_release/1</c>
+ returns <c>{error,{old_processes,Mod}}</c>.</p>
+ <p><c>PostPurge</c> defaults to <c>brutal_purge</c> and controls
+ what action to take with processes that are executing old code
+ when the new version of the module has been loaded. If the value
+ is <c>brutal_purge</c>, the code is purged when the release is
+ made permanent and the processes are killed. If the value is
+ <c>soft_purge</c>, the release handler will purge the old code
+ when no remaining processes execute the code.</p>
+ <p><c>DepMods</c> defaults to [] and defines which other modules
+ <c>Mod</c> is dependent on. In <c>relup</c>, instructions for
+ suspending processes using <c>Mod</c> will come before
+ instructions for suspending processes using modules in
+ <c>DepMods</c> when upgrading, and vice versa when downgrading.
+ In case of circular dependencies, the order of the instructions in
+ the <c>appup</c> script is kept.</p>
+ <p><c>Timeout</c> defines the timeout when suspending processes.
+ If no value or <c>default</c> is given, the default value for
+ <c>sys:suspend</c> is used.</p>
+ <p><c>ModType</c> defaults to <c>dynamic</c> and specifies if
+ the code is "dynamic", that is if a process using the module does
+ spontaneously switch to new code, or if it is "static".
+ When doing an advanced update and upgrading, the new version of a
+ dynamic module is loaded before the process is asked to change
+ code. When downgrading, the process is asked to change code before
+ loading the new version. For static modules, the new version is
+ loaded before the process is asked to change code, both in
+ the case of upgrading and downgrading. Callback modules are
+ dynamic.</p>
+ <p><c>update</c> with argument <c>supervisor</c> is used when
+ changing the start specification of a supervisor.</p>
+ <pre>
+{load_module, Mod}
+{load_module, Mod, DepMods}
+{load_module, Mod, PrePurge, PostPurge, DepMods}
+ Mod = atom()
+ PrePurge = PostPurge = soft_purge | brutal_purge
+ DepMods = [Mod]
+ </pre>
+ <p>Simple code replacement of the module <c>Mod</c>.</p>
+ <p>See <c>update</c> above for a description of <c>PrePurge</c> and
+ <c>PostPurge</c>.</p>
+ <p><c>DepMods</c> defaults to [] and defines which other modules
+ <c>Mod</c> is dependent on. In <c>relup</c>, instructions for
+ loading these modules will come before the instruction for loading
+ <c>Mod</c> when upgrading, and vice versa when downgrading.</p>
+ <pre>
+{add_module, Mod}
+ Mod = atom()
+ </pre>
+ <p>Loads a new module <c>Mod</c>.</p>
+ <pre>
+{delete_module, Mod}
+ Mod = atom()
+ </pre>
+ <p>Deletes a module <c>Mod</c> using the low-level instructions
+ <c>remove</c> and <c>purge</c>.</p>
+ <pre>
+{add_application, Application}
+ Application = atom()
+ </pre>
+ <p>Adding an application means that the modules defined by
+ the <c>modules</c> key in the <c>.app</c> file are loaded using
+ <c>add_module</c>, then the application is started.</p>
+ <pre>
+{remove_application, Application}
+ Application = atom()
+ </pre>
+ <p>Removing an application means that the application is stopped,
+ the modules are unloaded using <c>delete_module</c> and then
+ the application specification is unloaded from the application
+ controller.</p>
+ <pre>
+{restart_application, Application}
+ Application = atom()
+ </pre>
+ <p>Restarting an application means that the application is
+ stopped and then started again similar to using the instructions
+ <c>remove_application</c> and <c>add_application</c> in sequence.</p>
+ <p><em>Low-level instructions</em></p>
+ <pre>
+{load_object_code, {App, Vsn, [Mod]}}
+ App = Mod = atom()
+ Vsn = string()
+ </pre>
+ <p>Reads each <c>Mod</c> from the directory <c>App-Vsn/ebin</c> as
+ a binary. It does not load the modules. The instruction should be
+ placed first in the script in order to read all new code from file
+ to make the suspend-load-resume cycle less time consuming. After
+ this instruction has been executed, the code server with the new
+ version of <c>App</c>.</p>
+ <pre>
+point_of_no_return
+ </pre>
+ <p>If a crash occurs after this instruction, the system cannot
+ recover and is restarted from the old version of the release.
+ The instruction must only occur once in a script. It should be
+ placed after all <c>load_object_code</c> instructions.</p>
+ <pre>
+{load, {Mod, PrePurge, PostPurge}}
+ Mod = atom()
+ PrePurge = PostPurge = soft_purge | brutal_purge
+ </pre>
+ <p>Before this instruction occurs, <c>Mod</c> must have been loaded
+ using <c>load_object_code</c>. This instruction loads the module.
+ <c>PrePurge</c> is ignored. See the high-level instruction
+ <c>update</c> for a description of <c>PostPurge</c>.</p>
+ <pre>
+{remove, {Mod, PrePurge, PostPurge}}
+ Mod = atom()
+ PrePurge = PostPurge = soft_purge | brutal_purge
+ </pre>
+ <p>Makes the current version of <c>Mod</c> old.
+ <c>PrePurge</c> is ignored. See the high-level instruction
+ <c>update</c> for a description of <c>PostPurge</c>.</p>
+ <pre>
+{purge, [Mod]}
+ Mod = atom()
+ </pre>
+ <p>Purges each module <c>Mod</c>, that is removes the old code.
+ Note that any process executing purged code is killed.</p>
+ <pre>
+{suspend, [Mod | {Mod, Timeout}]}
+ Mod = atom()
+ Timeout = int()>0 | default | infinity
+ </pre>
+ <p>Tries to suspend all processes using a module <c>Mod</c>. If a
+ process does not respond, it is ignored. This may cause
+ the process to die, either because it crashes when it
+ spontaneously switches to new code, or as a result of a purge
+ operation. If no <c>Timeout</c> is specified or <c>default</c> is
+ given, the default value for <c>sys:suspend</c> is used.</p>
+ <pre>
+{resume, [Mod]}
+ Mod = atom()
+ </pre>
+ <p>Resumes all suspended processes using a module <c>Mod</c>.</p>
+ <pre>
+{code_change, [{Mod, Extra}]}
+{code_change, Mode, [{Mod, Extra}]}
+ Mod = atom()
+ Mode = up | down
+ Extra = term()
+ </pre>
+ <p><c>Mode</c> defaults to <c>up</c> and specifies if it is an
+ upgrade or downgrade.</p>
+ <p>This instruction sends a <c>code_change</c> system message to
+ all processes using a module <c>Mod</c> by calling the function
+ <c>sys:change_code</c>, passing the term <c>Extra</c> as argument.</p>
+ <pre>
+{stop, [Mod]}
+ Mod = atom()
+ </pre>
+ <p>Stops all processes using a module <c>Mod</c> by calling
+ <c>supervisor:terminate_child/2</c>. The instruction is useful
+ when the simplest way to change code is to stop and restart the
+ processes which run the code.</p>
+ <pre>
+{start, [Mod]}
+ Mod = atom()
+ </pre>
+ <p>Starts all stopped processes using a module <c>Mod</c> by calling
+ <c>supervisor:restart_child/2</c>.</p>
+ <pre>
+{sync_nodes, Id, [Node]}
+{sync_nodes, Id, {M, F, A}}
+ Id = term()
+ Node = node()
+ M = F = atom()
+ A = [term()]
+ </pre>
+ <p><c>apply(M, F, A)</c> must return a list of nodes.</p>
+ <p>The instruction synchronizes the release installation with other
+ nodes. Each <c>Node</c> must evaluate this command, with the same
+ <c>Id</c>. The local node waits for all other nodes to evaluate
+ the instruction before execution continues. In case a node goes
+ down, it is considered to be an unrecoverable error, and
+ the local node is restarted from the old release. There is no
+ timeout for this instruction, which means that it may hang
+ forever.</p>
+ <pre>
+{apply, {M, F, A}}
+ M = F = atom()
+ A = [term()]
+ </pre>
+ <p>Evaluates <c>apply(M, F, A)</c>. If the instruction appears
+ before the <c>point_of_no_return</c> instruction, a failure is
+ caught. <c>release_handler:install_release/1</c> then returns
+ <c>{error,{'EXIT',Reason}}</c>, unless <c>{error,Error}</c> is
+ thrown or returned. Then it returns <c>{error,Error}</c>.</p>
+ <p>If the instruction appears after the <c>point_of_no_return</c>
+ instruction, and the function call fails, the system is
+ restarted.</p>
+ <pre>
+restart_new_emulator
+ </pre>
+ <p>Shuts down the current emulator and starts a ne one. All
+ processes are terminated gracefully. The new release must still
+ be made permanent when the new emulator is up and running.
+ Otherwise, the old emulator is started in case of a emulator
+ restart. This instruction should be used when a new emulator is
+ introduced, or if a complete reboot of the system should be done.</p>
+ </section>
+
+ <section>
+ <title>SEE ALSO</title>
+ <p><seealso marker="relup">relup(4)</seealso>,
+ <seealso marker="release_handler">release_handler(3)</seealso>,
+ supervisor(3),
+ <seealso marker="systools">systools(3)</seealso></p>
+ </section>
+</fileref>
+
diff --git a/lib/sasl/doc/src/book.xml b/lib/sasl/doc/src/book.xml
new file mode 100644
index 0000000000..de6a533636
--- /dev/null
+++ b/lib/sasl/doc/src/book.xml
@@ -0,0 +1,49 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE book SYSTEM "book.dtd">
+
+<book xmlns:xi="http://www.w3.org/2001/XInclude">
+ <header titlestyle="normal">
+ <copyright>
+ <year>1997</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>System Application Support Libraries (SASL)</title>
+ <prepared>OTP Team</prepared>
+ <docno></docno>
+ <date>1999-04-22</date>
+ <rev>B</rev>
+ <file>book.xml</file>
+ </header>
+ <insidecover>
+ </insidecover>
+ <pagetext>System Application Support Libraries (SASL)</pagetext>
+ <preamble>
+ <contents level="2"></contents>
+ </preamble>
+ <parts lift="yes">
+ <xi:include href="part.xml"/>
+ </parts>
+ <applications>
+ <xi:include href="ref_man.xml"/>
+ </applications>
+ <releasenotes>
+ <xi:include href="notes.xml"/>
+ </releasenotes>
+ <listofterms></listofterms>
+ <index></index>
+</book>
+
diff --git a/lib/sasl/doc/src/error_logging.xml b/lib/sasl/doc/src/error_logging.xml
new file mode 100644
index 0000000000..5707bc4d69
--- /dev/null
+++ b/lib/sasl/doc/src/error_logging.xml
@@ -0,0 +1,385 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>1997</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>SASL Error Logging</title>
+ <prepared>Magnus Fr&ouml;berg</prepared>
+ <responsible>Bjarne D&auml;cker</responsible>
+ <docno></docno>
+ <approved></approved>
+ <checked></checked>
+ <date>1999-04-13</date>
+ <rev>B</rev>
+ <file>error_logging.xml</file>
+ </header>
+ <p>The SASL application introduces three types of reports:</p>
+ <list type="bulleted">
+ <item>supervisor report</item>
+ <item>progress report</item>
+ <item>crash report.</item>
+ </list>
+ <p>When the SASL application is started, it adds a handler that
+ formats and writes these reports, as specified in the
+ configuration parameters for sasl, i.e the environment variables
+ in the SASL application specification, which is found in the
+ <c>.app</c> file of SASL. See
+ <seealso marker="sasl_app">sasl(Application)</seealso>, and app(File)
+ in the Kernel Reference Manual
+ for the details.</p>
+
+ <section>
+ <title>Supervisor Report</title>
+ <p>A supervisor report is issued when a supervised child terminates in
+ an unexpected way. A supervisor report contains the following
+ items:</p>
+ <taglist>
+ <tag>Supervisor.</tag>
+ <item>The name of the reporting supervisor.</item>
+ <tag>Context.</tag>
+ <item>Indicates in which phase the child terminated
+ from the supervisor's point of view. This can be
+ <c>start_error</c>, <c>child_terminated</c>, or
+ <c>shutdown_error</c>.</item>
+ <tag>Reason.</tag>
+ <item>The termination reason.</item>
+ <tag>Offender.</tag>
+ <item>The start specification for the child.</item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>Progress Report</title>
+ <p>A progress report is issued whenever a supervisor starts or
+ restarts. A progress report contains the following items:</p>
+ <taglist>
+ <tag>Supervisor.</tag>
+ <item>The name of the reporting supervisor.</item>
+ <tag>Started.</tag>
+ <item>The start specification for the successfully
+ started child.</item>
+ </taglist>
+ <marker id="CRASH"></marker>
+ </section>
+
+ <section>
+ <title>Crash Report</title>
+ <p>Processes started with the <c>proc_lib:spawn</c> or
+ <c>proc_lib:spawn_link</c> functions are wrapped within a
+ <c>catch</c>. A crash report is issued whenever such a process
+ terminates with an unexpected reason, which is any reason other
+ than <c>normal</c> or <c>shutdown</c>. Processes using the
+ <c>gen_server</c> and <c>gen_fsm</c> behaviours are examples of
+ such processes. A crash report contains the following items:</p>
+ <taglist>
+ <tag>Crasher.</tag>
+ <item>Information about the crashing process is reported, such
+ as initial function call, exit reason, and message queue.</item>
+ <tag>Neighbours.</tag>
+ <item>Information about processes which are linked to the crashing
+ process and do not trap exits. These processes are the
+ neighbours which will terminate because of this process
+ crash. The information gathered is the same as the information
+ for Crasher, shown in the previous item.</item>
+ </taglist>
+
+ <section>
+ <title>An Example</title>
+ <p>The following example shows the reports which are generated
+ when a process crashes. The example process is an
+ <c>permanent</c> process supervised by the <c>test_sup</c>
+ supervisor. A division by zero is executed and the error is
+ first reported by the faulty process. A crash report is
+ generated as the process was started using the
+ <c>proc_lib:spawn/3</c> function. The supervisor generates a
+ supervisor report showing the process that has crashed, and then a
+ progress report is generated when the process is finally
+ re-started.</p>
+ <pre>
+ =ERROR REPORT==== 27-May-1996::13:38:56 ===
+ &lt;0.63.0>: Divide by zero !
+
+ =CRASH REPORT==== 27-May-1996::13:38:56 ===
+ crasher:
+ pid: &lt;0.63.0>
+ registered_name: []
+ error_info: {badarith,{test,s,[]}}
+ initial_call: {test,s,[]}
+ ancestors: [test_sup,&lt;0.46.0>]
+ messages: []
+ links: [&lt;0.47.0>]
+ dictionary: []
+ trap_exit: false
+ status: running
+ heap_size: 128
+ stack_size: 128
+ reductions: 348
+ neighbours:
+
+ =SUPERVISOR REPORT==== 27-May-1996::13:38:56 ===
+ Supervisor: {local,test_sup}
+ Context: child_terminated
+ Reason: {badarith,{test,s,[]}}
+ Offender: [{pid,&lt;0.63.0>},
+ {name,test},
+ {mfa,{test,t,[]}},
+ {restart_type,permanent},
+ {shutdown,200},
+ {child_type,worker}]
+
+
+ =PROGRESS REPORT==== 27-May-1996::13:38:56 ===
+ Supervisor: {local,test_sup}
+ Started: [{pid,&lt;0.64.0>},
+ {name,test},
+ {mfa,{test,t,[]}},
+ {restart_type,permanent},
+ {shutdown,200},
+ {child_type,worker}]
+ </pre>
+ </section>
+ </section>
+
+ <section>
+ <title>Multi-File Error Report Logging</title>
+ <p>Multi-file error report logging is used to store error messages,
+ which are received by the <c>error_logger</c>. The error messages
+ are stored in several files and each file is smaller than a
+ specified amount of kilobytes, and no more than a specified number
+ of files exist at the same time. The logging is very fast because
+ each error message is written as a binary term.</p>
+ <p>Refer to
+ <c>sasl</c> application in the Reference Manual for more details.</p>
+ </section>
+
+ <section>
+ <title>Report Browser</title>
+ <p>The report browser is used to browse and format error reports
+ written by the error logger handler <c>error_logger_mf_h</c>.</p>
+ <p>The <c>error_logger_mf_h</c> handler writes all reports to a
+ report logging directory. This directory is specified when
+ configuring the SASL application.</p>
+ <p>If the report browser is
+ used off-line, the reports can be copied to another directory
+ which is specified when starting the browser. If no such directory
+ is specified, the browser reads reports from the SASL
+ <c>error_logger_mf_dir</c>.</p>
+
+ <section>
+ <title>Starting the Report Browser</title>
+ <p>Start the <c>rb_server</c> with the function
+ <c>rb:start([Options])</c> as shown in the following
+ example:</p>
+ <pre>
+
+ 5><input>rb:start([{max, 20}]).</input>
+ rb: reading report...done.
+ rb: reading report...done.
+ rb: reading report...done.
+ rb: reading report...done.
+ </pre>
+ </section>
+
+ <section>
+ <title>On-line Help</title>
+ <p>Enter the command <em>rb:help().</em> to access the report
+ browser on-line help system.</p>
+ </section>
+
+ <section>
+ <title>List Reports in the Server</title>
+ <p>The function <c>rb:list()</c> lists all loaded reports:</p>
+ <pre>
+
+ 4><input>rb:list().</input>
+ No Type Process Date Time
+ == ==== ======= ==== ====
+ 20 progress &lt;0.17.0> 1996-10-16 16:14:54
+ 19 progress &lt;0.14.0> 1996-10-16 16:14:55
+ 18 error &lt;0.15.0> 1996-10-16 16:15:02
+ 17 progress &lt;0.14.0> 1996-10-16 16:15:06
+ 16 progress &lt;0.38.0> 1996-10-16 16:15:12
+ 15 progress &lt;0.17.0> 1996-10-16 16:16:14
+ 14 progress &lt;0.17.0> 1996-10-16 16:16:14
+ 13 progress &lt;0.17.0> 1996-10-16 16:16:14
+ 12 progress &lt;0.14.0> 1996-10-16 16:16:14
+ 11 error &lt;0.17.0> 1996-10-16 16:16:21
+ 10 error &lt;0.17.0> 1996-10-16 16:16:21
+ 9 crash_report release_handler 1996-10-16 16:16:21
+ 8 supervisor_report &lt;0.17.0> 1996-10-16 16:16:21
+ 7 progress &lt;0.17.0> 1996-10-16 16:16:21
+ 6 progress &lt;0.17.0> 1996-10-16 16:16:36
+ 5 progress &lt;0.17.0> 1996-10-16 16:16:36
+ 4 progress &lt;0.17.0> 1996-10-16 16:16:36
+ 3 progress &lt;0.14.0> 1996-10-16 16:16:36
+ 2 error &lt;0.15.0> 1996-10-16 16:17:04
+ 1 progress &lt;0.14.0> 1996-10-16 16:17:09
+ ok
+ </pre>
+ </section>
+
+ <section>
+ <title>Show Reports</title>
+ <p>To show details of a specific report, use the function
+ <c>rb:show(Number)</c>:</p>
+ <pre>
+
+10> <input>rb:show(1).</input>
+7> <input>rb:show(4).</input>
+
+PROGRESS REPORT &lt;0.20.0> 1996-10-16 16:16:36
+===============================================================================
+supervisor {local,sasl_sup}
+started
+[{pid,&lt;0.24.0>},
+{name,release_handler},
+{mfa,{release_handler,start_link,[]}},
+{restart_type,permanent},
+{shutdown,2000},
+{child_type,worker}]
+
+ok
+8> rb:show(9).
+
+CRASH REPORT &lt;0.24.0> 1996-10-16 16:16:21
+===============================================================================
+Crashing process
+pid &lt;0.24.0>
+registered_name release_handler
+error_info {undef,{release_handler,mbj_func,[]}}
+initial_call
+{gen,init_it,
+[gen_server,
+&lt;0.20.0>,
+&lt;0.20.0>,
+{erlang,register},
+release_handler,
+release_handler,
+[],
+[]]}
+ancestors [sasl_sup,&lt;0.18.0>]
+messages []
+links [&lt;0.23.0>,&lt;0.20.0>]
+dictionary []
+trap_exit false
+status running
+heap_size 610
+stack_size 142
+reductions 54
+
+ok
+ </pre>
+ </section>
+
+ <section>
+ <title>Search the Reports</title>
+ <p>It is possible to show all reports which contain a common
+ pattern. Suppose a process crashes because it tries to call a
+ non-existing function <c>release_handler:mbj_func.</c> We could
+ then show reports as follows:</p>
+ <pre>
+
+12><input>rb:grep("mbj_func").</input>
+Found match in report number 11
+
+ERROR REPORT &lt;0.24.0> 1996-10-16 16:16:21
+===============================================================================
+
+** undefined function: release_handler:mbj_func[] **
+Found match in report number 10
+
+ERROR REPORT &lt;0.24.0> 1996-10-16 16:16:21
+===============================================================================
+
+** Generic server release_handler terminating
+** Last message in was {unpack_release,hej}
+** When Server state == {state,[],
+"/home/dup/otp2/otp_beam_sunos5_p1g_7",
+[{release,
+"OTP APN 181 01",
+"P1G",
+undefined,
+[],
+permanent}],
+undefined}
+** Reason for termination ==
+** {undef,{release_handler,mbj_func,[]}}
+Found match in report number 9
+
+CRASH REPORT &lt;0.24.0> 1996-10-16 16:16:21
+===============================================================================
+Crashing process
+pid &lt;0.24.0>
+registered_name release_handler
+error_info {undef,{release_handler,mbj_func,[]}}
+initial_call
+{gen,init_it,
+[gen_server,
+&lt;0.20.0>,
+&lt;0.20.0>,
+{erlang,register},
+release_handler,
+release_handler,
+[],
+[]]}
+ancestors [sasl_sup,&lt;0.18.0>]
+messages []
+links [&lt;0.23.0>,&lt;0.20.0>]
+dictionary []
+trap_exit false
+status running
+heap_size 610
+stack_size 142
+reductions 54
+
+Found match in report number 8
+
+SUPERVISOR REPORT &lt;0.20.0> 1996-10-16 16:16:21
+===============================================================================
+Reporting supervisor {local,sasl_sup}
+
+Child process
+errorContext child_terminated
+reason {undef,{release_handler,mbj_func,[]}}
+pid &lt;0.24.0>
+name release_handler
+start_function {release_handler,start_link,[]}
+restart_type permanent
+shutdown 2000
+child_type worker
+
+ok
+ </pre>
+ </section>
+
+ <section>
+ <title>Stop the Server</title>
+ <p>Stop the <c>rb_server</c> with the function
+ <c>rb:stop()</c>:</p>
+ <pre>
+
+13><input>rb:stop().</input>
+ok
+ </pre>
+ </section>
+ </section>
+</chapter>
+
diff --git a/lib/sasl/doc/src/fascicules.xml b/lib/sasl/doc/src/fascicules.xml
new file mode 100644
index 0000000000..0678195e07
--- /dev/null
+++ b/lib/sasl/doc/src/fascicules.xml
@@ -0,0 +1,18 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE fascicules SYSTEM "fascicules.dtd">
+
+<fascicules>
+ <fascicule file="part" href="part_frame.html" entry="no">
+ User's Guide
+ </fascicule>
+ <fascicule file="ref_man" href="ref_man_frame.html" entry="yes">
+ Reference Manual
+ </fascicule>
+ <fascicule file="part_notes" href="part_notes_frame.html" entry="no">
+ Release Notes
+ </fascicule>
+ <fascicule file="" href="../../../../doc/print.html" entry="no">
+ Off-Print
+ </fascicule>
+</fascicules>
+
diff --git a/lib/sasl/doc/src/make.dep b/lib/sasl/doc/src/make.dep
new file mode 100644
index 0000000000..4843b7934a
--- /dev/null
+++ b/lib/sasl/doc/src/make.dep
@@ -0,0 +1,22 @@
+# ----------------------------------------------------
+# >>>> Do not edit this file <<<<
+# This file was automaticly generated by
+# /home/otp/bin/docdepend
+# ----------------------------------------------------
+
+
+# ----------------------------------------------------
+# TeX files that the DVI file depend on
+# ----------------------------------------------------
+
+book.dvi: alarm_handler.tex appup.tex book.tex error_logging.tex \
+ overload.tex part.tex rb.tex ref_man.tex rel.tex \
+ release_handler.tex relup.tex sasl_app.tex \
+ sasl_intro.tex script.tex systools.tex
+
+# ----------------------------------------------------
+# Source inlined when transforming from source to LaTeX
+# ----------------------------------------------------
+
+book.tex: ref_man.xml
+
diff --git a/lib/sasl/doc/src/note.gif b/lib/sasl/doc/src/note.gif
new file mode 100644
index 0000000000..6fffe30419
--- /dev/null
+++ b/lib/sasl/doc/src/note.gif
Binary files differ
diff --git a/lib/sasl/doc/src/notes.xml b/lib/sasl/doc/src/notes.xml
new file mode 100644
index 0000000000..15387c1232
--- /dev/null
+++ b/lib/sasl/doc/src/notes.xml
@@ -0,0 +1,319 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2004</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>SASL Release Notes</title>
+ <prepared>otp_appnotes</prepared>
+ <docno>nil</docno>
+ <date>nil</date>
+ <rev>nil</rev>
+ <file>notes.xml</file>
+ </header>
+ <p>This document describes the changes made to the SASL application.</p>
+
+<section><title>SASL 2.1.8</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ The documentation is now built with open source tools
+ (xsltproc and fop) that exists on most platforms. One
+ visible change is that the frames are removed.</p>
+ <p>
+ Own Id: OTP-8201</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>SASL 2.1.7</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ The Windows utility Erlsrv, run in interactive mode now
+ accepts options for registering internal service name and
+ description field of Windows registry database.</p>
+ <p>
+ Own Id: OTP-8132</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>SASL 2.1.6</title>
+
+ <section><title>Fixed Bugs and Malfunctions</title>
+ <list>
+ <item>
+ <p>When using the SASL application configuration
+ parameter <c>masters</c> the error tuple
+ <c>{error,{no_such_file,{Master,FileName}}}</c> was
+ sometimes returned even though the file <c>FileName</c>
+ existed.</p>
+ <p>
+ Own Id: OTP-7667</p>
+ </item>
+ </list>
+ </section>
+
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Missing preloaded modules added</p>
+ <p>
+ Own Id: OTP-7820</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>SASL 2.1.5.4</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ A Dialyzer warning was eliminated</p>
+ <p>
+ Own Id: OTP-7635</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>SASL 2.1.5.3</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Minor changes.</p>
+ <p>
+ Own Id: OTP-7388</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+
+<section><title>SASL 2.1.5.2</title>
+
+ <section><title>Improvements and New Features</title>
+ <list>
+ <item>
+ <p>
+ Minor updates.</p>
+ <p>
+ Own Id: OTP-6998</p>
+ </item>
+ </list>
+ </section>
+
+</section>
+ <section>
+ <title>SASL 2.1.5.1</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>Minor Makefile changes.</p>
+ <p>Own Id: OTP-6689</p>
+ </item>
+ <item>
+ <p>Obsolete guard tests (such as list()) have been replaced
+ with the modern guard tests (such as is_list()).</p>
+ <p>Own Id: OTP-6725</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SASL 2.1.5</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Removed some dead code from <c>erlsrv:get_service/2</c>,
+ <c>release_handler:do_write_file/2</c>,
+ <c>systools_relup:foreach_baserel_up/7</c> and
+ <c>systools_relup:foreach_baserel_dn/7</c>.</p>
+ <p>Own Id: OTP-6499</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SASL 2.1.4</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>Added an option <c>{outdir,Dir}</c> to the functions in
+ <c>systools</c>, making it possible to specify in which
+ directory a boot script, relup file or release package
+ file should be placed.</p>
+ <p>Also, when using <c>systools:make_tar/2</c> to create a
+ release package file, the boot script, relup file and
+ <c>sys.config</c> are now searched for also in the current
+ working directory and any directory specified by
+ the <c>path</c> option, not only in the directory of
+ the <c>.rel</c> file.</p>
+ <p>As part of the work some minor bugs have been corrected:</p>
+ <list type="bulleted">
+ <item>
+ <p><c>systools:make_script/1,2</c> now returns
+ <c>error</c> if the <c>.script</c> and/or <c>.boot</c>
+ file could not be opened for writing, not <c>ok</c>.</p>
+ </item>
+ <item>
+ <p><c>systools:make_tar/1,2</c> can now handle a
+ <c>RelName</c> argument which includes a path.
+ Previously this would cause the <c>.rel</c> file to end
+ up in the wrong directory in the resulting tar file.</p>
+ </item>
+ <item>
+ <p>A documentation error for <c>systools:make_tar/1,2</c>:
+ The <c>.rel</c> file is placed in the <c>releases</c>
+ directory in the tar file, not <c>releases/RelVsn</c>.</p>
+ </item>
+ </list>
+ <p>Own Id: OTP-6226</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SASL 2.1.3</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p><c>release_handler:upgrade_app/2</c> and
+ <c>release_handler:downgrade_app/2,3</c> -- used for
+ testing application upgrade and downgrade according to
+ the <c>.appup</c> file -- now update application
+ configuration parameters correctly. (Thanks to Serge
+ Aleynikov)</p>
+ <p>Own Id: OTP-6162</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SASL 2.1.2</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>Fixed some minor bugs in <c>release_handler</c> found by
+ Dialyzer.</p>
+ <p>Own Id: OTP-6039</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SASL 2.1.1</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>Added a number of functions to <c>release_handler</c> which
+ makes it possible to test upgrade and downgrade of
+ applications according to an <c>.appup</c> file "on the
+ fly": <br></br>
+
+ - <c>upgrade_app/2</c> <br></br>
+
+ - <c>upgrade_script/2</c> <br></br>
+
+ - <c>downgrade_app/2,3</c> <br></br>
+
+ - <c>downgrade_script/3</c> <br></br>
+
+ - <c>eval_appup_script/4</c></p>
+ <p>Own Id: OTP-5858</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SASL 2.1</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>A new option <c>{update_paths,Bool}</c> has been added
+ for <c>release_handler:install_release/2</c>. It
+ 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).</p>
+ <p><c>release_handler:set_unpacked/2</c> now returns an
+ error tuple if a specified application directory does not
+ exist.</p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-5761</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SASL 2.0.1</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>A bug that made it impossible to call <c>rb:show(N)</c>
+ (<c>N</c> being an integer) twice without getting an error
+ has been fixed.</p>
+ <p>Own Id: OTP-5287</p>
+ </item>
+ </list>
+ </section>
+ </section>
+</chapter>
+
diff --git a/lib/sasl/doc/src/notes_history.xml b/lib/sasl/doc/src/notes_history.xml
new file mode 100644
index 0000000000..50772ae4e3
--- /dev/null
+++ b/lib/sasl/doc/src/notes_history.xml
@@ -0,0 +1,128 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>2006</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>SASL Release Notes History</title>
+ <prepared>otp_appnotes</prepared>
+ <docno>nil</docno>
+ <date>nil</date>
+ <rev>nil</rev>
+ </header>
+
+ <section>
+ <title>SASL 2.0</title>
+
+ <section>
+ <title>Fixed Bugs and Malfunctions</title>
+ <list type="bulleted">
+ <item>
+ <p>When doing a code replacement in run-time, updating the
+ internal state of a gen_server, gen_event or gen_fsm, it
+ was stated in the documentation that the first argument
+ <c>OldVsn</c> to the callback function
+ <c>Module:code_change</c> was defined by the <c>vsn</c>
+ attribute in the old version of <c>Module</c>.</p>
+ <p>However, this was not true. For downgrades, <c>OldVsn</c>
+ was <c>{down,Vsn}</c>, where <c>Vsn</c> was fetched from
+ the <c>.app</c> file instead.</p>
+ <p>The version is now always fetched from the module using
+ <c>beam_lib:version/1</c> and the man pages for gen_*
+ have been updated accordingly.</p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-3699</p>
+ </item>
+ <item>
+ <p>The release handling instruction
+ <c>restart_application</c> was translated to the
+ low-level instruction <c>application_remove</c> and a set
+ of <c>load_module</c> instructions.</p>
+ <p>However, <c>application_remove</c> caused the modules
+ listed for the new, not the old, version of the
+ application to be unloaded. If the set of modules was
+ changed, this meant the release handler would try to
+ purge non-existent modules and/or forget to unload
+ modules no longer used.</p>
+ <p><c>restart_application</c> is now translated to a correct
+ set of <c>delete_module</c> and <c>add_module</c>
+ instructions instead, and the <c>application_remove</c>
+ instruction is deprecated.</p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-4805</p>
+ </item>
+ <item>
+ <p><c>release_handler:check_install_release/1</c> returned
+ <c>{error,Reason}</c> if <c>sys.config</c> or
+ <c>relup</c> was missing. Since both these files are
+ optional, the behaviour has been changed to write
+ warnings to the terminal but return an <c>ok</c> tuple
+ instead.</p>
+ <p>*** POTENTIAL INCOMPATIBILITY ***</p>
+ <p>Own Id: OTP-4824</p>
+ </item>
+ </list>
+ </section>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>Added a clause to <c>systools:make_script/1</c> which
+ makes it possible to provide (atomic) options when
+ calling the function using <c>erl -s</c>.</p>
+ <p>Example: <c>erl -noinput +B -s systools make_script myrel no_module_tests -s erlang halt</c> is equal to calling
+ <c>systools:make_script("myrel", [no_module_tests])</c>.</p>
+ <p>Own Id: OTP-3384</p>
+ </item>
+ <item>
+ <p>Added simplified versions of the <c>update</c> and
+ <c>load_module</c> release handling instructions.</p>
+ <p>Own Id: OTP-4793</p>
+ </item>
+ <item>
+ <p>Added two new release handling instructions: <c>{update, Module, supervisor}</c> and <c>{delete_module, Module}</c>.</p>
+ <p>Own Id: OTP-4800</p>
+ </item>
+ </list>
+ </section>
+ </section>
+
+ <section>
+ <title>SASL 1.10.1</title>
+
+ <section>
+ <title>Improvements and New Features</title>
+ <list type="bulleted">
+ <item>
+ <p>The option <c>{abort_on_error,Bool}</c> has been added to
+ <c>rb:start/1</c> and <c>rb:rescan/1</c>. With it you can
+ choose whether or not rb should stop logging if it
+ encounters an unprintable report. When <c>abort_on_error</c>
+ is set to <c>false</c>, rb will resume logging after a bad
+ report has been handled. The error messages rb prints when
+ logging fails have been enhanced.</p>
+ <p>Own Id: OTP-5096 Aux Id: seq8930</p>
+ </item>
+ </list>
+ </section>
+ </section>
+</chapter>
+
diff --git a/lib/sasl/doc/src/overload.xml b/lib/sasl/doc/src/overload.xml
new file mode 100644
index 0000000000..80457e75fa
--- /dev/null
+++ b/lib/sasl/doc/src/overload.xml
@@ -0,0 +1,151 @@
+<?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>overload</title>
+ <prepared>Peter H&ouml;gfeldt</prepared>
+ <responsible>Peter H&ouml;gfeldt</responsible>
+ <docno></docno>
+ <approved>(Joe Armstrong)</approved>
+ <checked></checked>
+ <date>1996-10-29</date>
+ <rev>A</rev>
+ <file>overload.sgml</file>
+ </header>
+ <module>overload</module>
+ <modulesummary>An Overload Regulation Process</modulesummary>
+ <description>
+ <p><c>overload</c> is a process which indirectly regulates CPU
+ usage in the system. The idea is that a main application calls
+ the <c>request/0</c> function before starting a major job, and
+ proceeds with the job if the return value is positive; otherwise
+ the job must not be started.
+ </p>
+ <p><c>overload</c> is part of the <c>sasl</c> application, and all
+ configuration parameters are defined there.
+ </p>
+ <p>A set of two intensities are maintained, the <c>total intensity</c> and the <c>accept intensity</c>. For that purpose
+ there are two configuration parameters, the <c>MaxIntensity</c>
+ and the <c>Weight</c> value (both are measured in 1/second).
+ </p>
+ <p>Then total and accept intensities are calculated as
+ follows. Assume that the time of the current call to
+ <c>request/0</c> is <c>T(n)</c>, and that the time of the
+ previous call was <c>T(n-1)</c>.
+ </p>
+ <list type="bulleted">
+ <item>
+ <p>The current <c>total intensity</c>, denoted
+ <c>TI(n)</c>, is calculated according to the formula,
+ </p>
+ <p><c>TI(n) = exp(-Weight*(T(n) - T(n-1)) * TI(n-1) + Weight</c>,
+ </p>
+ <p>where <c>TI(n-1)</c> is the previous total intensity.
+ </p>
+ </item>
+ <item>
+ <p>The current <c>accept intensity</c>, denoted
+ <c>AI(n)</c>, is determined by the formula,
+ </p>
+ <p><c>AI(n) = exp(-Weight*(T(n) - T(n-1)) * AI(n-1) + Weight</c>,
+ </p>
+ <p>where <c>AI(n-1)</c> is the previous accept intensity,
+ provided that the value of <c>exp(-Weight*(T(n) - T(n-1)) * AI(n-1)</c> is less than <c>MaxIntensity</c>; otherwise the
+ value is
+ </p>
+ <p><c>AI(n) = exp(-Weight*(T(n) - T(n-1)) * AI(n-1)</c>.
+ </p>
+ </item>
+ </list>
+ <p>The value of configuration parameter <c>Weight</c> controls the
+ speed with which the calculations of intensities will react to
+ changes in the underlying input intensity. The inverted value of
+ <c>Weight</c>,
+ </p>
+ <p><c>T = 1/Weight</c></p>
+ <p>can be thought of as the "time constant"
+ of the intensity calculation formulas. For example, if <c>Weight = 0.1</c>, then a change in the underlying input intensity will be
+ reflected in the <c>total</c> and <c>accept intensities</c> within
+ approximately 10 seconds.
+ </p>
+ <p>The overload process defines one alarm, which it sets using
+ <c>alarm_handler:set_alarm(Alarm)</c>. <c>Alarm</c> is defined
+ as:
+ </p>
+ <taglist>
+ <tag><c>{overload, []}</c></tag>
+ <item>
+ <p>This alarm is set when the current accept intensity exceeds
+ <c>MaxIntensity</c>.
+ </p>
+ </item>
+ </taglist>
+ <p>A new overload alarm is not set until the current accept
+ intensity has fallen below <c>MaxIntensity</c>. To prevent the
+ overload process from generating a lot of set/reset alarms, the
+ alarm is not reset until the current accept intensity has fallen
+ below 75% of <c>MaxIntensity</c>, and it is not until then that
+ the alarm can be set again.
+ </p>
+ </description>
+ <funcs>
+ <func>
+ <name>request() -> accept | reject</name>
+ <fsummary>Request to proceed with current job</fsummary>
+ <desc>
+ <p>Returns <c>accept</c> or <c>reject</c> depending on the
+ current value of the accept intensity. </p>
+ <p>The application
+ calling this function should be processed with the job in
+ question if the return value is <c>accept</c>; otherwise it
+ should not continue with that job.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>get_overload_info() -> OverloadInfo</name>
+ <fsummary>Return current overload information data</fsummary>
+ <type>
+ <v>OverloadInfo = [{total_intensity, TotalIntensity}, {accept_intensity, AcceptIntensity}, {max_intensity, MaxIntensity}, {weight, Weight}, {total_requests, TotalRequests}, {accepted_requests, AcceptedRequests}].</v>
+ <v>TotalIntensity = float() > 0</v>
+ <v>AcceptIntensity = float() > 0</v>
+ <v>MaxIntensity = float() > 0</v>
+ <v>Weight = float() > 0</v>
+ <v>TotalRequests = integer()</v>
+ <v>AcceptedRequests = integer()</v>
+ </type>
+ <desc>
+ <p>Returns the current total and accept intensities, the
+ configuration parameters, and absolute counts of the total
+ number of requests, and accepted number of requests (since
+ the overload process was started).</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>See Also</title>
+ <p>alarm_handler(3), sasl(3)
+ </p>
+ </section>
+</erlref>
+
diff --git a/lib/sasl/doc/src/part.xml b/lib/sasl/doc/src/part.xml
new file mode 100644
index 0000000000..647380efbd
--- /dev/null
+++ b/lib/sasl/doc/src/part.xml
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part xmlns:xi="http://www.w3.org/2001/XInclude">
+ <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>SASL User's Guide</title>
+ <prepared>OTP Team</prepared>
+ <docno></docno>
+ <date>1997-06-04</date>
+ <rev>1.3.1</rev>
+ <file>part.xml</file>
+ </header>
+ <description>
+ <p>The System Architecture Support Libraries, <em>SASL</em>,
+ provides support for alarm and release handling etc.</p>
+ </description>
+ <xi:include href="sasl_intro.xml"/>
+ <xi:include href="error_logging.xml"/>
+</part>
+
diff --git a/lib/sasl/doc/src/part_notes.xml b/lib/sasl/doc/src/part_notes.xml
new file mode 100644
index 0000000000..1f572ae922
--- /dev/null
+++ b/lib/sasl/doc/src/part_notes.xml
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part xmlns:xi="http://www.w3.org/2001/XInclude">
+ <header>
+ <copyright>
+ <year>2004</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>SASL Release Notes</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <description>
+ <p>The System Architecture Support Libraries, <em>SASL</em>,
+ provides support for alarm and release handling etc.</p>
+ <p>For information about older versions, see
+ <url href="part_notes_history_frame.html">Release Notes History</url>.</p>
+ </description>
+ <xi:include href="notes.xml"/>
+</part>
+
diff --git a/lib/sasl/doc/src/part_notes_history.xml b/lib/sasl/doc/src/part_notes_history.xml
new file mode 100644
index 0000000000..2726d73684
--- /dev/null
+++ b/lib/sasl/doc/src/part_notes_history.xml
@@ -0,0 +1,38 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE part SYSTEM "part.dtd">
+
+<part>
+ <header>
+ <copyright>
+ <year>2006</year>
+ <year>2007</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.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>SASL Release Notes History</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <description>
+ <p>The System Architecture Support Libraries, <em>SASL</em>,
+ provides support for alarm and release handling etc.</p>
+ </description>
+ <include file="notes_history"></include>
+</part>
+
diff --git a/lib/sasl/doc/src/rb.xml b/lib/sasl/doc/src/rb.xml
new file mode 100644
index 0000000000..5b49a7bced
--- /dev/null
+++ b/lib/sasl/doc/src/rb.xml
@@ -0,0 +1,206 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1996</year>
+ <year>2007</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.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>rb</title>
+ <prepared>Martin Bj&ouml;rklund</prepared>
+ <responsible>Martin Bj&ouml;rklund</responsible>
+ <docno></docno>
+ <approved>Bjarne D&auml;cker</approved>
+ <checked></checked>
+ <date>1996-10-16</date>
+ <rev>A</rev>
+ <file>rb.sgml</file>
+ </header>
+ <module>rb</module>
+ <modulesummary>The Report Browser Tool</modulesummary>
+ <description>
+ <p>The Report Browser (RB) tool makes it possible to browse and
+ format error reports written by the error logger handler
+ <c>log_mf_h</c>.
+ </p>
+ </description>
+ <funcs>
+ <func>
+ <name>grep(RegExp)</name>
+ <fsummary>Search the reports for a regular expression</fsummary>
+ <type>
+ <v>RegExp = string()</v>
+ </type>
+ <desc>
+ <p>All reports containing the regular expression <c>RegExp</c>
+ are printed.
+ </p>
+ <p><c>RegExp</c> is a string containing the regular
+ expression. Refer to the module <c>regexp</c> in the STDLIB
+ reference manual
+ for a definition of valid regular expressions. They are
+ essentially the same as the UNIX command <c>egrep</c>.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>h()</name>
+ <name>help()</name>
+ <fsummary>Print help information</fsummary>
+ <desc>
+ <p>Prints the on-line help information.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>list()</name>
+ <name>list(Type)</name>
+ <fsummary>List all reports</fsummary>
+ <type>
+ <v>Type = type()</v>
+ <v>type() = crash_report | supervisor_report | error | progress</v>
+ </type>
+ <desc>
+ <p>This function lists all reports loaded in the
+ <c>rb_server</c>. Each report is given a unique number that
+ can be used as a reference to the report in the
+ <c>show/1</c> function.
+ </p>
+ <p>If no <c>Type</c> is given, all reports are listed.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>rescan()</name>
+ <name>rescan(Options)</name>
+ <fsummary>Rescan the report directory</fsummary>
+ <type>
+ <v>Options = [opt()]</v>
+ </type>
+ <desc>
+ <p>Rescans the report directory. <c>Options</c> is the same as
+ for <c>start()</c>.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>show()</name>
+ <name>show(Report)</name>
+ <fsummary>Show reports</fsummary>
+ <type>
+ <v>Report = int() | type()</v>
+ </type>
+ <desc>
+ <p>If a type argument is given, all loaded reports of this
+ type are printed. If an integer argument is given, the
+ report with this reference number is printed. If no argument
+ is given, all reports are shown.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>start()</name>
+ <name>start(Options)</name>
+ <fsummary>Start the RB server</fsummary>
+ <type>
+ <v>Options = [opt()]</v>
+ <v>opt() = {start_log, FileName} | {max, MaxNoOfReports} | {report_dir, DirString} | {type, ReportType} | {abort_on_error, Bool}</v>
+ <v>FileName = string() | standard_io</v>
+ <v>MaxNoOfReports = int() | all</v>
+ <v>DirString = string()</v>
+ <v>ReportType = type() | [type()] | all</v>
+ <v>Bool = true | false</v>
+ </type>
+ <desc>
+ <p>The function <c>start/1</c> starts the <c>rb_server</c>
+ with the specified options, while <c>start/0</c> starts with
+ default options. The <c>rb_server</c> must be started before
+ reports can be browsed. When the <c>rb_server</c> is
+ started, the files in the specified directory are
+ scanned. The other functions assume that the server has
+ started.
+ </p>
+ <p><c>{start_log, FileName}</c> starts logging to file. All
+ reports will be printed to the named file. The default is
+ <c>standard_io</c>.
+ </p>
+ <p><c>{max, MaxNoOfReports}</c>. Controls how many reports the
+ <c>rb_server</c> should read on start-up. This option is
+ useful as the directory may contain 20.000 reports. If this
+ option is given, the <c>MaxNoOfReports</c> latest reports
+ will be read. The default is 'all'.
+ </p>
+ <p><c>{report_dir, DirString}</c>. Defines the directory where
+ the error log files are located. The default is <c>{sasl, error_logger_mf_dir}</c>. </p>
+ <p><c>{type, ReportType}</c>. Controls what kind of reports the
+ <c>rb_server</c> should read on start-up. <c>ReportType</c>
+ is a supported type, 'all', or a list of supported
+ types. The default is 'all'.
+ </p>
+ <p><c>{abort_on_error, Bool}</c>. This option specifies whether
+ or not logging should be aborted if rb encounters an unprintable
+ report. (You may get a report on incorrect form if the
+ <c>error_logger</c> function <c>error_msg</c> or
+ <c>info_msg</c> has been called with an invalid format string).
+ If <c>Bool</c> is <c>true</c>, rb will stop logging (and print an
+ error message to stdout) if it encounters a badly formatted report.
+ If logging to file is enabled, an error message will be appended to
+ the log file as well.
+ If <c>Bool</c> is <c>false</c> (which is the default value), rb will
+ print an error message to stdout for every bad report it
+ encounters, but the logging process is never aborted. All printable
+ reports will be written. If logging to file is enabled, rb prints
+ <c>* UNPRINTABLE REPORT *</c> in the log file at the location of an
+ unprintable report.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>start_log(FileName)</name>
+ <fsummary>Redirect all output to <c>FileName</c></fsummary>
+ <type>
+ <v>FileName = string()</v>
+ </type>
+ <desc>
+ <p>Redirects all report output from the RB tool to the
+ specified file.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>stop()</name>
+ <fsummary>Stop the RB server</fsummary>
+ <desc>
+ <p>Stops the <c>rb_server</c>.
+ </p>
+ </desc>
+ </func>
+ <func>
+ <name>stop_log()</name>
+ <fsummary>Stop logging to file</fsummary>
+ <desc>
+ <p>Closes the log file. The output from the RB tool will be
+ directed to <c>standard_io</c>.
+ </p>
+ </desc>
+ </func>
+ </funcs>
+</erlref>
+
diff --git a/lib/sasl/doc/src/ref_man.xml b/lib/sasl/doc/src/ref_man.xml
new file mode 100644
index 0000000000..09b745a705
--- /dev/null
+++ b/lib/sasl/doc/src/ref_man.xml
@@ -0,0 +1,46 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE application SYSTEM "application.dtd">
+
+<application xmlns:xi="http://www.w3.org/2001/XInclude">
+ <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>SASL Reference Manual</title>
+ <prepared>OTP Team</prepared>
+ <docno></docno>
+ <date>1997-11-17</date>
+ <rev>1.4</rev>
+ <file>application.xml</file>
+ </header>
+ <description>
+ <p>The System Architecture Support Libraries application, <em>SASL</em>,
+ provides support for alarm and release handling etc.</p>
+ </description>
+ <xi:include href="sasl_app.xml"/>
+ <xi:include href="alarm_handler.xml"/>
+ <xi:include href="overload.xml"/>
+ <xi:include href="rb.xml"/>
+ <xi:include href="release_handler.xml"/>
+ <xi:include href="systools.xml"/>
+ <xi:include href="appup.xml"/>
+ <xi:include href="rel.xml"/>
+ <xi:include href="relup.xml"/>
+ <xi:include href="script.xml"/>
+</application>
+
diff --git a/lib/sasl/doc/src/rel.xml b/lib/sasl/doc/src/rel.xml
new file mode 100644
index 0000000000..108f5e7f3e
--- /dev/null
+++ b/lib/sasl/doc/src/rel.xml
@@ -0,0 +1,105 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE fileref SYSTEM "fileref.dtd">
+
+<fileref>
+ <header>
+ <copyright>
+ <year>1997</year>
+ <year>2007</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.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>rel</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <file>rel</file>
+ <filesummary>Release resource file</filesummary>
+ <description>
+ <p>The <em>release resource file</em> specifies which applications are
+ are included in a release (system) based on Erlang/OTP.</p>
+ <p>This file is used by the functions in <c>systools</c> when generating
+ start scripts (<c>.script</c>, <c>.boot</c>) and release upgrade
+ files (<c>relup</c>).</p>
+ </description>
+
+ <section>
+ <title>FILE SYNTAX</title>
+ <p>The release resource file should be called <c>Name.rel</c>.</p>
+ <p>The <c>.rel</c> file contains one single Erlang term, which is
+ called a <em>release specification</em>. The file has the
+ following syntax:</p>
+ <code type="none">
+{release, {RelName,Vsn}, {erts, EVsn},
+ [{Application, AppVsn} |
+ {Application, AppVsn, Type} |
+ {Application, AppVsn, IncApps} |
+ {Application, AppVsn, Type, IncApps}]}.
+ </code>
+ <list type="bulleted">
+ <item>
+ <p><c>RelName = string()</c> is the name of the release.</p>
+ </item>
+ <item>
+ <p><c>Vsn = string()</c> is the version of the release.</p>
+ </item>
+ <item>
+ <p><c>EVsn = string()</c> is the version of ERTS the release is
+ intended for.</p>
+ </item>
+ <item>
+ <p><c>Application = atom()</c> is the name of an application
+ included in the release.</p>
+ </item>
+ <item>
+ <p><c>AppVsn = string()</c> is the version of an application
+ included in the release.</p>
+ </item>
+ <item>
+ <p><c>Type = permanent | transient | temporary | load | none</c>
+ is the start type of an application included in the release.</p>
+ <p>If <c>Type = permanent | transient | temporary</c>,
+ the application will be loaded and started in the corresponding
+ way, see <c>application(3)</c>. If <c>Type = load</c>,
+ the application will only be loaded. If <c>Type = none</c>,
+ the application will be neither loaded nor started, although
+ the code for its modules will be loaded.
+ Defaults to <c>permanent</c></p>
+ </item>
+ <item>
+ <p><c>IncApps = [atom()]</c> is a list of applications that are
+ included by an application included in the release.</p>
+ <p>The list must be a subset of the included applications
+ specified in the application resource file
+ (<c>Application.app</c>) and overrides this value. Defaults
+ to the empty list.</p>
+ </item>
+ </list>
+ <note>
+ <p>The list of applications must contain the <c>kernel</c> and
+ <c>stdlib</c> applications.</p>
+ </note>
+ </section>
+
+ <section>
+ <title>SEE ALSO</title>
+ <p>application(3), relup(4), systools(3)</p>
+ </section>
+</fileref>
+
diff --git a/lib/sasl/doc/src/rel/bar.1.erl b/lib/sasl/doc/src/rel/bar.1.erl
new file mode 100644
index 0000000000..610fc4919e
--- /dev/null
+++ b/lib/sasl/doc/src/rel/bar.1.erl
@@ -0,0 +1,17 @@
+-module(bar).
+-vsn(1).
+
+-export([simple/1, complicated_sum/1]).
+
+simple(X) ->
+ case lists2:assoc(simple, X) of
+ {ok, Val} -> Val;
+ false -> false
+ end.
+
+complicated_sum([X, Y, Z]) -> cs(X, Y, Z).
+
+cs([HX | TX], [HY | TY], [HZ | TZ]) ->
+ NewRes = cs(TX, TY, TZ),
+ [HX + HY + HZ | NewRes];
+cs([], [], []) -> [].
diff --git a/lib/sasl/doc/src/rel/bar.2.erl b/lib/sasl/doc/src/rel/bar.2.erl
new file mode 100644
index 0000000000..a831316874
--- /dev/null
+++ b/lib/sasl/doc/src/rel/bar.2.erl
@@ -0,0 +1,13 @@
+-module(bar).
+-vsn(2).
+
+-export([simple/1, complicated_sum/1]).
+
+simple(X) ->
+ case lists2:assoc(simple, X) of
+ {ok, Val} -> Val;
+ false -> false
+ end.
+
+complicated_sum(X) ->
+ lists2:multi_map(fun(A,B,C) -> A+B+C end, X).
diff --git a/lib/sasl/doc/src/rel/ge_h.1.erl b/lib/sasl/doc/src/rel/ge_h.1.erl
new file mode 100644
index 0000000000..ac2d3b3e5f
--- /dev/null
+++ b/lib/sasl/doc/src/rel/ge_h.1.erl
@@ -0,0 +1,28 @@
+-module(ge_h).
+-vsn(1).
+-behaviour(gen_event).
+
+-export([get_events/1]).
+-export([init/1, handle_event/2, handle_call/2, handle_info/2,
+ terminate/2, code_change/3]).
+
+get_events(Mgr) ->
+ gen_event:call(Mgr, ge_h, get_events).
+
+init(_) -> {ok, undefined}.
+
+handle_event(Event, _LastEvent) ->
+ {ok, Event}.
+
+handle_call(get_events, LastEvent) ->
+ {ok, [LastEvent], LastEvent}.
+
+handle_info(Info, LastEvent) ->
+ {ok, LastEvent}.
+
+terminate(Arg, LastEvent) ->
+ ok.
+
+code_change(_OldVsn, LastEvent, _Extra) ->
+ {ok, LastEvent}.
+
diff --git a/lib/sasl/doc/src/rel/ge_h.2.erl b/lib/sasl/doc/src/rel/ge_h.2.erl
new file mode 100644
index 0000000000..837338e399
--- /dev/null
+++ b/lib/sasl/doc/src/rel/ge_h.2.erl
@@ -0,0 +1,31 @@
+-module(ge_h).
+-vsn(2).
+-behaviour(gen_event).
+
+-export([get_events/1]).
+-export([init/1, handle_event/2, handle_call/2, handle_info/2,
+ terminate/2, code_change/3]).
+
+get_events(Mgr) ->
+ gen_event:call(Mgr, ge_h, get_events).
+
+init(_) -> {ok, []}.
+
+handle_event(Event, []) ->
+ {ok, [Event]};
+handle_event(Event, [Event1 | _]) ->
+ {ok, [Event, Event1]}.
+
+handle_call(get_events, Events) ->
+ Events.
+
+handle_info(Info, Events) ->
+ {ok, Events}.
+
+terminate(Arg, Events) ->
+ ok.
+
+code_change(1, undefined, _Extra) ->
+ {ok, []};
+code_change(1, LastEvent, _Extra) ->
+ {ok, [LastEvent]}.
diff --git a/lib/sasl/doc/src/rel/gs1.1.erl b/lib/sasl/doc/src/rel/gs1.1.erl
new file mode 100644
index 0000000000..b85ea45857
--- /dev/null
+++ b/lib/sasl/doc/src/rel/gs1.1.erl
@@ -0,0 +1,30 @@
+-module(gs1).
+-vsn(1).
+-behaviour(gen_server).
+
+-export([get_data/0]).
+-export([init/1, handle_call/3, handle_cast/2, handle_info/2,
+ terminate/2, code_change/3]).
+
+-record(state, {data}).
+
+get_data() ->
+ gen_server:call(gs1, get_data).
+
+init([Data]) ->
+ {ok, #state{data = Data}}.
+
+handle_call(get_data, _From, State) ->
+ {reply, {ok, State#state.data}, State}.
+
+handle_cast(_Request, State) ->
+ {noreply, State}.
+
+handle_info(_Info, State) ->
+ {noreply, State}.
+
+terminate(_Reason, _State) ->
+ ok.
+
+code_change(_OldVsn, State, _Extra) ->
+ {ok, State}.
diff --git a/lib/sasl/doc/src/rel/gs1.2.erl b/lib/sasl/doc/src/rel/gs1.2.erl
new file mode 100644
index 0000000000..8391713c6d
--- /dev/null
+++ b/lib/sasl/doc/src/rel/gs1.2.erl
@@ -0,0 +1,35 @@
+-module(gs1).
+-vsn(2).
+-behaviour(gen_server).
+
+-export([get_data/0, get_time/0]).
+-export([init/1, handle_call/3, handle_cast/2, handle_info/2,
+ terminate/2, code_change/3]).
+
+-record(state, {data, time}).
+
+get_data() ->
+ gen_server:call(gs1, get_data).
+
+get_time() ->
+ gen_server:call(gs1, get_time).
+
+init([Data]) ->
+ {ok, #state{data = Data, time = erlang:time()}}.
+
+handle_call(get_data, _From, State) ->
+ {reply, {ok, State#state.data}, State};
+handle_call(get_time, _From, State) ->
+ {reply, {ok, State#state.time}, State}.
+
+handle_cast(_Request, State) ->
+ {noreply, State}.
+
+handle_info(_Info, State) ->
+ {noreply, State}.
+
+terminate(_Reason, _State) ->
+ ok.
+
+code_change(1, {state, Data}, _Extra) ->
+ {ok, #state{data = Data, time = erlang:time()}}.
diff --git a/lib/sasl/doc/src/rel/gs1.3.erl b/lib/sasl/doc/src/rel/gs1.3.erl
new file mode 100644
index 0000000000..2d4c0870b6
--- /dev/null
+++ b/lib/sasl/doc/src/rel/gs1.3.erl
@@ -0,0 +1,36 @@
+-module(gs1).
+-vsn(2).
+-behaviour(gen_server).
+
+-export([get_data/0, get_time/0]).
+-export([init/1, handle_call/3, handle_cast/2, handle_info/2,
+ terminate/2, code_change/3]).
+
+-record(state, {data, time}).
+
+get_data() ->
+ gen_server:call(gs1, get_data).
+get_time() ->
+ gen_server:call(gs1, get_time).
+
+init([Data]) ->
+ {ok, #state{data = Data, time = erlang:time()}}.
+
+handle_call(get_data, _From, State) ->
+ {reply, {ok, State#state.data}, State};
+handle_call(get_time, _From, State) ->
+ {reply, {ok, State#state.time}, State}.
+
+handle_cast(_Request, State) ->
+ {noreply, State}.
+
+handle_info(_Info, State) ->
+ {noreply, State}.
+
+terminate(_Reason, _State) ->
+ ok.
+
+code_change(1, {state, Data}, _Extra) ->
+ {ok, #state{data = Data, time = erlang:time()}};
+code_change({down, 1}, #state{data = Data}, _Extra) ->
+ {ok, {state, Data}}.
diff --git a/lib/sasl/doc/src/rel/gs2.1.erl b/lib/sasl/doc/src/rel/gs2.1.erl
new file mode 100644
index 0000000000..1b06a9551f
--- /dev/null
+++ b/lib/sasl/doc/src/rel/gs2.1.erl
@@ -0,0 +1,31 @@
+-module(gs2).
+-vsn(1).
+-behaviour(gen_server).
+
+-export([is_operation_ok/1]).
+-export([init/1, handle_call/3, handle_cast/2, handle_info/2,
+ terminate/2, code_change/3]).
+
+is_operation_ok(Op) ->
+ gen_server:call(gs2, {is_operation_ok, Op}).
+
+init([Data]) ->
+ {ok, []}.
+
+handle_call({is_operation_ok, Op}, _From, State) ->
+ Data = gs1:get_data(),
+ Reply = lists2:assoc(Op, Data),
+ {reply, Reply, State}.
+
+handle_cast(_Request, State) ->
+ {noreply, State}.
+
+handle_info(_Info, State) ->
+ {noreply, State}.
+
+terminate(_Reason, _State) ->
+ ok.
+
+code_change(_OldVsn, State, _Extra) ->
+ {ok, State}.
+
diff --git a/lib/sasl/doc/src/rel/gs2.2.erl b/lib/sasl/doc/src/rel/gs2.2.erl
new file mode 100644
index 0000000000..3248ea43bb
--- /dev/null
+++ b/lib/sasl/doc/src/rel/gs2.2.erl
@@ -0,0 +1,38 @@
+-module(gs2).
+-vsn(2).
+-behaviour(gen_server).
+
+-export([is_operation_ok/1]).
+-export([init/1, handle_call/3, handle_cast/2, handle_info/2,
+ terminate/2, code_change/3]).
+
+is_operation_ok(Op) ->
+ gen_server:call(gs2, {is_operation_ok, Op}).
+
+init([Data]) ->
+ {ok, []}.
+
+handle_call({is_operation_ok, Op}, _From, State) ->
+ Data = gs1:get_data(),
+ Time = gs1:get_time(),
+ Reply = do_things(lists2:assoc(Op, Data), Time),
+ {reply, Reply, State}.
+
+handle_cast(_Request, State) ->
+ {noreply, State}.
+
+handle_info(_Info, State) ->
+ {noreply, State}.
+
+terminate(_Reason, _State) ->
+ ok.
+
+code_change(_OldVsn, State, _Extra) ->
+ {ok, State}.
+
+do_things({ok, Val}, Time) ->
+ Val;
+do_things(false, Time) ->
+ {false, Time}.
+
+
diff --git a/lib/sasl/doc/src/rel/lists2.1.erl b/lib/sasl/doc/src/rel/lists2.1.erl
new file mode 100644
index 0000000000..4afe3b5041
--- /dev/null
+++ b/lib/sasl/doc/src/rel/lists2.1.erl
@@ -0,0 +1,8 @@
+-module(lists2).
+-vsn(1).
+
+-export([assoc/2]).
+
+assoc(Key, [{Key, Val} | _]) -> {ok, Val};
+assoc(Key, [H | T]) -> assoc(Key, T);
+assoc(Key, []) -> false.
diff --git a/lib/sasl/doc/src/rel/lists2.2.erl b/lib/sasl/doc/src/rel/lists2.2.erl
new file mode 100644
index 0000000000..734bc36bbb
--- /dev/null
+++ b/lib/sasl/doc/src/rel/lists2.2.erl
@@ -0,0 +1,13 @@
+-module(lists2).
+-vsn(2).
+
+-export([assoc/2, multi_map/2]).
+
+assoc(Key, [{Key, Val} | _]) -> {ok, Val};
+assoc(Key, [H | T]) -> assoc(Key, T);
+assoc(Key, []) -> false.
+
+multi_map(Func, [[] | ListOfLists]) -> [];
+multi_map(Func, ListOfLists) ->
+ [apply(Func, lists:map({erlang, hd}, ListOfLists)) |
+ multi_map(Func, lists:map({erlang, tl}, ListOfLists))].
diff --git a/lib/sasl/doc/src/rel/portc.1.erl b/lib/sasl/doc/src/rel/portc.1.erl
new file mode 100644
index 0000000000..0d387a4e5e
--- /dev/null
+++ b/lib/sasl/doc/src/rel/portc.1.erl
@@ -0,0 +1,31 @@
+-module(portc).
+-vsn(1).
+-behaviour(gen_server).
+
+-export([get_data/0]).
+-export([init/1, handle_call/3, handle_info/2, code_change/3]).
+
+-record(state, {port, data}).
+
+get_data() -> gen_server:call(portc, get_data).
+
+init([]) ->
+ PortProg = code:priv_dir(foo) ++ "/bin/portc",
+ Port = open_port({spawn, PortProg}, [binary, {packet, 2}]),
+ {ok, #state{port = Port}}.
+
+handle_call(get_data, _From, State) ->
+ {reply, {ok, State#state.data}, State}.
+
+handle_info({Port, Cmd}, State) ->
+ NewState = do_cmd(Cmd, State),
+ {noreply, NewState}.
+
+code_change(_, State, change_port_only) ->
+ State#state.port ! close,
+ receive
+ {Port, closed} -> true
+ end,
+ NPortProg = code:priv_dir(foo) ++ "/bin/portc", % get new version
+ NPort = open_port({spawn, NPortProg}, [binary, {packet, 2}]),
+ {ok, State#state{port = NPort}}.
diff --git a/lib/sasl/doc/src/rel/portc.2.erl b/lib/sasl/doc/src/rel/portc.2.erl
new file mode 100644
index 0000000000..6711177f6a
--- /dev/null
+++ b/lib/sasl/doc/src/rel/portc.2.erl
@@ -0,0 +1,34 @@
+-module(portc).
+-vsn(2).
+-behaviour(gen_server).
+
+-export([get_data/0]).
+-export([init/1, handle_call/3, handle_info/2, code_change/3]).
+
+-record(state, {port, data}).
+
+get_data() -> gen_server:call(portc, get_data).
+
+init([]) ->
+ PortProg = code:priv_dir(foo) ++ "/bin/portc",
+ Port = open_port({spawn, PortProg}, [binary, {packet, 2}]),
+ {ok, #state{port = Port}}.
+
+handle_call(get_data, _From, State) ->
+ {reply, {ok, State#state.data}, State}.
+
+handle_info({Port, Cmd}, State) ->
+ NewState = do_cmd(Cmd, State),
+ {noreply, NewState}.
+
+code_change(_, State, change_port_only) ->
+ State#state.port ! close,
+ receive
+ {Port, closed} -> true
+ end,
+ NPortProg = code:priv_dir(foo) ++ "/bin/portc", % get new version
+ NPort = open_port({spawn, NPortProg}, [binary, {packet, 2}]),
+ {ok, State#state{port = NPort}};
+code_change(1, State, change_erl_only) ->
+ NState = transform_state(State),
+ {ok, NState}.
diff --git a/lib/sasl/doc/src/rel/sp.1.erl b/lib/sasl/doc/src/rel/sp.1.erl
new file mode 100644
index 0000000000..deb11286b1
--- /dev/null
+++ b/lib/sasl/doc/src/rel/sp.1.erl
@@ -0,0 +1,46 @@
+-module(sp).
+-vsn(1).
+
+-export([start/0, get_data/0]).
+-export([init/1, system_continue/3, system_terminate/4]).
+
+-record(state, {data}).
+
+start() ->
+ Pid = proc_lib:spawn_link(?MODULE, init, [self()]),
+ {ok, Pid}.
+
+get_data() ->
+ sp_server ! {self(), get_data},
+ receive
+ {sp_server, Data} -> Data
+ end.
+
+init(Parent) ->
+ register(sp_server, self()),
+ process_flag(trap_exit, true),
+ loop(#state{}, Parent).
+
+loop(State, Parent) ->
+ receive
+ {system, From, Request} ->
+ sys:handle_system_msg(Request, From, Parent, ?MODULE, [], State);
+ {'EXIT', Parent, Reason} ->
+ cleanup(State),
+ exit(Reason);
+ {From, get_data} ->
+ From ! {sp_server, State#state.data},
+ loop(State, Parent);
+ _Any ->
+ loop(State, Parent)
+ end.
+
+cleanup(State) -> ok.
+
+%% Here are the sys call back functions
+system_continue(Parent, _, State) ->
+ loop(State, Parent).
+
+system_terminate(Reason, Parent, _, State) ->
+ cleanup(State),
+ exit(Reason).
diff --git a/lib/sasl/doc/src/rel/sp.2.erl b/lib/sasl/doc/src/rel/sp.2.erl
new file mode 100644
index 0000000000..b2282f0610
--- /dev/null
+++ b/lib/sasl/doc/src/rel/sp.2.erl
@@ -0,0 +1,58 @@
+-module(sp).
+-vsn(2).
+
+-export([start/0, get_data/0, set_data/1]).
+-export([init/1, system_continue/3, system_terminate/4,
+ system_code_change/4]).
+
+-record(state, {data, last_pid}).
+
+start() ->
+ Pid = proc_lib:spawn_link(?MODULE, init, [self()]),
+ {ok, Pid}.
+
+get_data() ->
+ sp_server ! {self(), get_data},
+ receive
+ {sp_server, Data} -> Data
+ end.
+
+set_data(Data) ->
+ sp_server ! {self(), set_data, Data}.
+
+init(Parent) ->
+ register(sp_server, self()),
+ process_flag(trap_exit, true),
+ loop(#state{last_pid = no_one}, Parent).
+
+loop(State, Parent) ->
+ receive
+ {system, From, Request} ->
+ sys:handle_system_msg(Request, From, Parent,
+ ?MODULE, [], State);
+ {'EXIT', Parent, Reason} ->
+ cleanup(State),
+ exit(Reason);
+ {From, get_data} ->
+ From ! {sp_server, State#state.data},
+ loop(State, Parent);
+ {From, set_data, Data} ->
+ loop(State#state{data = Data, last_pid = From}, Parent);
+ _Any ->
+ loop(State, Parent)
+ end.
+
+cleanup(State) -> ok.
+
+%% Here are the sys call back functions
+system_continue(Parent, _, State) ->
+ loop(State, Parent).
+
+system_terminate(Reason, Parent, _, State) ->
+ cleanup(State),
+ exit(Reason).
+
+system_code_change({state, Data}, _Mod, 1, _Extra) ->
+ {ok, #state{data = Data, last_pid = no_one}};
+system_code_change(#state{data = Data}, _Mod, {down, 1}, _Extra) ->
+ {ok, {state, Data}}.
diff --git a/lib/sasl/doc/src/rel/sup.1.erl b/lib/sasl/doc/src/rel/sup.1.erl
new file mode 100644
index 0000000000..c73f1161b3
--- /dev/null
+++ b/lib/sasl/doc/src/rel/sup.1.erl
@@ -0,0 +1,11 @@
+-module(sup).
+-vsn(1).
+-behaviour(supervisor).
+-export([init/1]).
+
+init([]) ->
+ SupFlags = {one_for_one, 4, 3600},
+ Server = {my_server, {my_server, start_link, []},
+ permanent, 2000, worker, [my_server]},
+ GS1 = {gs1, {gs1, start_link, []}, permanent, 2000, worker, [gs1]},
+ {ok, {SupFlags, [Server, GS1]}}.
diff --git a/lib/sasl/doc/src/rel/sup.2.erl b/lib/sasl/doc/src/rel/sup.2.erl
new file mode 100644
index 0000000000..783da18f2f
--- /dev/null
+++ b/lib/sasl/doc/src/rel/sup.2.erl
@@ -0,0 +1,10 @@
+-module(sup).
+-vsn(2).
+-behaviour(supervisor).
+-export([init/1]).
+
+init([]) ->
+ SupFlags = {one_for_one, 4, 3600},
+ GS1 = {gs1, {gs1, start_link, []}, permanent, 2000, worker, [gs1]},
+ GS2 = {gs2, {gs2, start_link, []}, permanent, 2000, worker, [gs2]},
+ {ok, {SupFlags, [GS1, GS2]}}.
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>
+
diff --git a/lib/sasl/doc/src/relup.xml b/lib/sasl/doc/src/relup.xml
new file mode 100644
index 0000000000..f7d9fcdd42
--- /dev/null
+++ b/lib/sasl/doc/src/relup.xml
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE fileref SYSTEM "fileref.dtd">
+
+<fileref>
+ <header>
+ <copyright>
+ <year>1997</year>
+ <year>2007</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.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>relup</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <file>relup</file>
+ <filesummary>Release upgrade file</filesummary>
+ <description>
+ <p>The <em>release upgrade file</em> describes how a release is
+ upgraded in a running system.</p>
+ <p>This file is automatically generated by
+ <c>systools:make_relup/3,4</c>, using a release resource file
+ (<c>.rel</c>), application resource files (<c>.app</c>) and
+ application upgrade files (<c>.appup</c>) as input.</p>
+ </description>
+
+ <section>
+ <title>FILE SYNTAX</title>
+ <p>In a target system, the release upgrade file should be located in
+ the <c>OTP_ROOT/erts-EVsn/Vsn</c> directory.</p>
+ <p>The <c>relup</c> file contains one single Erlang term, which
+ defines the instructions used to upgrade the release. The file has
+ the following syntax:</p>
+ <code type="none">
+{Vsn,
+ [{UpFromVsn, Descr, Instructions}, ...],
+ [{DownToVsn, Descr, Instructions}, ...]}.
+ </code>
+ <list type="bulleted">
+ <item>
+ <p><c>Vsn = string()</c> is the current version of the release.</p>
+ </item>
+ <item>
+ <p><c>UpFromVsn = string()</c> is an earlier version of the release
+ to upgrade from.</p>
+ </item>
+ <item>
+ <p><c>Descr = term()</c> is a user defined parameter passed
+ from the <c>systools:make_relup/3,4</c> function. It will
+ be used in the return value of
+ <c>release_handler:install_release/1,2</c>.</p>
+ </item>
+ <item>
+ <p><c>Instructions</c> is a list of low-level release upgrade
+ instructions, see <c>appup(4)</c>.</p>
+ <p>It consists of the release upgrade instructions from
+ the respective application upgrade files (high-level instructions
+ are translated to low-level instructions), in the same order
+ as in the start script.</p>
+ </item>
+ <item>
+ <p><c>DownToVsn = string()</c> is an earlier version of the release
+ to downgrade to.</p>
+ </item>
+ </list>
+ <p>When upgrading from <c>UpFromVsn</c> with
+ <c>release_handler:install_release/1,2</c>, there does not have to be
+ an exact match of versions, but <c>UpFromVsn</c> can be a sub-string
+ of the current release version.</p>
+ </section>
+
+ <section>
+ <title>SEE ALSO</title>
+ <p>app(4), appup(4), rel(4), release_handler(3), systools(3)</p>
+ </section>
+</fileref>
+
diff --git a/lib/sasl/doc/src/sasl_app.xml b/lib/sasl/doc/src/sasl_app.xml
new file mode 100644
index 0000000000..a7fecfc440
--- /dev/null
+++ b/lib/sasl/doc/src/sasl_app.xml
@@ -0,0 +1,182 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE appref SYSTEM "appref.dtd">
+
+<appref>
+ <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>sasl</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <app>sasl</app>
+ <appsummary>The SASL Application</appsummary>
+ <description>
+ <p>This section describes the SASL (System Architecture Support Libraries)
+ application which provides the following services:</p>
+ <list type="bulleted">
+ <item><c>alarm_handler</c></item>
+ <item><c>overload</c></item>
+ <item><c>rb</c></item>
+ <item><c>release_handler</c></item>
+ <item><c>systools</c></item>
+ </list>
+ <p>The SASL application also includes <c>error_logger</c> event
+ handlers for formatting SASL error and crash reports.</p>
+
+ <note>
+ <p>The SASL application in OTP has nothing to do with
+ "Simple Authentication and Security Layer" (RFC 4422).</p>
+ </note>
+
+ </description>
+
+ <section>
+ <title>Error Logger Event Handlers</title>
+ <p>The following error logger event handlers are defined in
+ the SASL application.</p>
+ <taglist>
+ <tag><c>sasl_report_tty_h</c></tag>
+ <item>
+ <p>Formats and writes <em>supervisor reports</em>, <em>crash reports</em> and <em>progress reports</em> to <c>stdio</c>.</p>
+ </item>
+ <tag><c>sasl_report_file_h</c></tag>
+ <item>
+ <p>Formats and writes <em>supervisor reports</em>, <em>crash report</em> and <em>progress report</em> to a single file.</p>
+ </item>
+ <tag><c>error_logger_mf_h</c></tag>
+ <item>
+ <p>This error logger writes <em>all</em> events sent to
+ the error logger to disk. It installs the <c>log_mf_h</c>
+ event handler in the <c>error_logger</c> process.</p>
+ </item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+ <p>The following configuration parameters are defined for the SASL
+ application. See <c>app(4)</c> for more information about
+ configuration parameters:</p>
+ <taglist>
+ <tag><c><![CDATA[sasl_error_logger = Value <optional>]]></c></tag>
+ <item>
+ <p><c>Value</c> is one of:</p>
+ <taglist>
+ <tag><c>tty</c></tag>
+ <item>Installs <c>sasl_report_tty_h</c> in the error logger.
+ This is the default option.</item>
+ <tag><c>{file,FileName}</c></tag>
+ <item>Installs <c>sasl_report_file_h</c> in the error logger.
+ This makes all reports go to the file <c>FileName</c>.
+ <c>FileName</c> is a string.</item>
+ <tag><c>false</c></tag>
+ <item>
+ <p>No SASL error logger handler is installed.</p>
+ </item>
+ </taglist>
+ </item>
+ <tag><c><![CDATA[errlog_type = error | progress | all <optional>]]></c></tag>
+ <item>
+ <p>Restricts the error logging performed by the specified
+ <c>sasl_error_logger</c> to error reports, progress reports,
+ or both. Default is <c>all</c>.</p>
+ </item>
+ <tag><c><![CDATA[error_logger_mf_dir = string() | false<optional>]]></c></tag>
+ <item>
+ <p>Specifies in which directory the files are stored. If this
+ parameter is undefined or <c>false</c>,
+ the <c>error_logger_mf_h</c> is not installed.</p>
+ </item>
+ <tag><c><![CDATA[error_logger_mf_maxbytes = integer() <optional>]]></c></tag>
+ <item>
+ <p>Specifies how large each individual file can be. If this
+ parameter is undefined, the <c>error_logger_mf_h</c> is not
+ installed.</p>
+ </item>
+ <tag><c><![CDATA[error_logger_mf_maxfiles = 0<integer()<256 <optional>]]></c></tag>
+ <item>
+ <p>Specifies how many files are used. If this parameter is
+ undefined, the <c>error_logger_mf_h</c> is not installed.</p>
+ </item>
+ <tag><c><![CDATA[overload_max_intensity = float() > 0 <optional>]]></c></tag>
+ <item>
+ <p>Specifies the maximum intensity for <c>overload</c>. Default
+ is <c>0.8</c>.</p>
+ </item>
+ <tag><c><![CDATA[overload_weight = float() > 0 <optional>]]></c></tag>
+ <item>
+ <p>Specifies the <c>overload</c> weight. Default is <c>0.1</c>.</p>
+ </item>
+ <tag><c><![CDATA[start_prg = string() <optional>]]></c></tag>
+ <item>
+ <p>Specifies which program should be used when restarting
+ the system. Default is <c>$OTP_ROOT/bin/start</c>.</p>
+ </item>
+ <tag><c><![CDATA[masters = [atom()] <optional>]]></c></tag>
+ <item>
+ <p>Specifies which nodes this node uses to read/write release
+ information. This parameter is ignored if
+ the <c>client_directory</c> parameter is not set.</p>
+ </item>
+ <tag><c><![CDATA[client_directory = string() <optional>]]></c></tag>
+ <item>
+ <p>This parameter specifies the client directory at the master
+ nodes. Refer to Release Handling in <em>OTP Design Principles</em> for more information. This parameter is
+ ignored if the <c>masters</c> parameter is not set.</p>
+ </item>
+ <tag><c><![CDATA[static_emulator = true | false <optional>]]></c></tag>
+ <item>
+ <p>Indicates if the Erlang emulator is statically installed. A
+ node with a static emulator cannot switch dynamically to a
+ new emulator as the executable files are written into memory
+ statically. This parameter is ignored if the <c>masters</c>
+ and <c>client_directory</c> parameters are not set.</p>
+ </item>
+ <tag><c><![CDATA[releases_dir = string() <optional>]]></c></tag>
+ <item>
+ <p>Indicates where the <c>releases</c> directory is located.
+ The release handler writes all its files to this directory.
+ If this parameter is not set, the OS environment parameter
+ <c>RELDIR</c> is used. By default, this is
+ <c>$OTP_ROOT/releases</c>.</p>
+ </item>
+ <tag><c><![CDATA[utc_log = true | false <optional>]]></c></tag>
+ <item>
+ <p>If set to <c>true</c>, all dates in textual log outputs are
+ displayed in Universal Coordinated Time with the string
+ <c>UTC</c> appended.</p>
+ </item>
+ </taglist>
+ </section>
+
+ <section>
+ <title>See Also</title>
+ <p><seealso marker="alarm_handler">alarm_handler(3)</seealso>,
+ error_logger(3),
+ log_mf_h(3),
+ <seealso marker="overload">overload(3)</seealso>,
+ <seealso marker="rb">rb(3)</seealso>,
+ <seealso marker="release_handler">release_handler(3)</seealso>,
+ <seealso marker="systools">systools(3)</seealso></p>
+ </section>
+</appref>
+
diff --git a/lib/sasl/doc/src/sasl_intro.xml b/lib/sasl/doc/src/sasl_intro.xml
new file mode 100644
index 0000000000..535f25e044
--- /dev/null
+++ b/lib/sasl/doc/src/sasl_intro.xml
@@ -0,0 +1,51 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE chapter SYSTEM "chapter.dtd">
+
+<chapter>
+ <header>
+ <copyright>
+ <year>1997</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>Introduction</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ <file>sasl_intro.xml</file>
+ </header>
+
+ <section>
+ <title>About This Document</title>
+ <p>The SASL (System Architecture Support Libraries)
+ application provides support for:</p>
+ <list type="bulleted">
+ <item>error logging</item>
+ <item>alarm handling</item>
+ <item>overload regulation</item>
+ <item>release handling</item>
+ <item>report browsing.</item>
+ </list>
+ <p>In this document, "SASL Error Logging" describes the error
+ handler which produces the supervisor, progress, and crash
+ reports which can be written to screen, or to a specified file.
+ It also describes the report browser <c>rb</c>.</p>
+ <p>The chapters about release structure and release handling have
+ been moved to <em>OTP Design Principles</em>.</p>
+ </section>
+</chapter>
+
diff --git a/lib/sasl/doc/src/script.xml b/lib/sasl/doc/src/script.xml
new file mode 100644
index 0000000000..6bac07d106
--- /dev/null
+++ b/lib/sasl/doc/src/script.xml
@@ -0,0 +1,168 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE fileref SYSTEM "fileref.dtd">
+
+<fileref>
+ <header>
+ <copyright>
+ <year>1997</year>
+ <year>2007</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.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>script</title>
+ <prepared>Martin Bj&ouml;rklund</prepared>
+ <responsible>Bjarne D&auml;cker</responsible>
+ <docno></docno>
+ <approved>Bjarne D&auml;cker</approved>
+ <checked></checked>
+ <date>97-06-03</date>
+ <rev>A</rev>
+ <file>script.sgml</file>
+ </header>
+ <file>script</file>
+ <filesummary>Boot script</filesummary>
+ <description>
+ <p>The <em>boot script</em> describes how the Erlang runtime system is
+ started. It contains instructions on which code to load and
+ which processes and applications to start.
+ </p>
+ <p>The command <c>erl -boot Name</c> starts the system with a boot
+ file called <c>Name.boot</c>, which is generated from the
+ <c>Name.script</c> file, using <c>systools:script2boot/1</c>.
+ </p>
+ <p>The <c>.script</c> file is generated by <c>systools</c> from a
+ <c>.rel</c> file and <c>.app</c> files.
+ </p>
+ </description>
+
+ <section>
+ <title>FILE SYNTAX</title>
+ <p>The boot script is stored in a file with the extension
+ <c>.script</c></p>
+ <p>The file has the following syntax:
+ </p>
+ <code type="none">
+{script, {Name, Vsn},
+ [
+ {progress, loading},
+ {preLoaded, [Mod1, Mod2, ...]},
+ {path, [Dir1,"$ROOT/Dir",...]}.
+ {primLoad, [Mod1, Mod2, ...]},
+ ...
+ {kernel_load_completed},
+ {progress, loaded},
+ {kernelProcess, Name, {Mod, Func, Args}},
+ ...
+ {apply, {Mod, Func, Args}},
+ ...
+ {progress, started}]}. </code>
+ <list type="bulleted">
+ <item><c>Name = string()</c> defines the name of the system.
+ </item>
+ <item><c>Vsn = string()</c> defines the version of the system.
+ </item>
+ <item><c>{progress, Term}</c> sets the "progress" of the
+ initialization program. The function <c>init:get_status()</c>
+ returns the current value of the progress, which is
+ <c>{InternalStatus,Term}</c>.
+ </item>
+ <item>
+ <p><c>{path, [Dir]}</c> where <c>Dir</c> is a string. This
+ argument sets the load path of the system to <c>[Dir]</c>. The
+ load path used to load modules is obtained from the initial
+ load path, which is given in the script file, together with
+ any path flags which were supplied in the command line
+ arguments. The command line arguments modify the path as
+ follows:</p>
+ <list type="bulleted">
+ <item><c>-pa Dir1 Dir2 ... DirN</c> adds the directories
+ <c>Dir1, Dir2, ..., DirN</c> to the front of the initial
+ load path.
+ </item>
+ <item><c>-pz Dir1 Dir2 ... DirN</c> adds the directories
+ <c>Dir1, Dir2, ..., DirN</c> to the end of the initial
+ load path.
+ </item>
+ <item>
+ <p><c>-path Dir1 Dir2 ... DirN</c> defines a set of
+ directories <c>Dir1, Dir2, ..., DirN</c> which replaces
+ the search path given in the script file. Directory names
+ in the path are interpreted as follows:</p>
+ <list type="bulleted">
+ <item>Directory names starting with <c>/</c> are assumed
+ to be absolute path names.
+ </item>
+ <item>Directory names not starting with <c>/</c> are
+ assumed to be relative the current working directory.
+ </item>
+ <item>The special <c>$ROOT</c> variable can only be used
+ in the script, not as a command line argument. The
+ given directory is relative the Erlang installation
+ directory.
+ </item>
+ </list>
+ </item>
+ </list>
+ </item>
+ <item><c>{primLoad, [Mod]}</c> loads the modules <c>[Mod]</c>
+ from the directories specified in <c>Path</c>. The script
+ interpreter fetches the appropriate module by calling the
+ function <c>erl_prim_loader:get_file(Mod)</c>. A fatal error
+ which terminates the system will occur if the module cannot be
+ located.
+ </item>
+ <item><c>{kernel_load_completed}</c> indicates that all modules
+ which <em>must</em> be loaded <em>before</em> any processes
+ are started are loaded. In interactive mode, all
+ <c>{primLoad,[Mod]}</c> commands interpreted after this
+ command are ignored, and these modules are loaded on demand.
+ In embedded mode, <c>kernel_load_completed</c> is ignored, and
+ all modules are loaded during system start.
+ </item>
+ <item><c>{kernelProcess, Name, {Mod, Func, Args}}</c> starts a
+ "kernel process". The kernel process <c>Name</c> is started
+ by evaluating <c>apply(Mod, Func, Args)</c> which is expected
+ to return <c>{ok, Pid}</c> or <c>ignore</c>. The <c>init</c>
+ process monitors the behaviour of <c>Pid</c> and terminates
+ the system if <c>Pid</c> dies. Kernel processes are key
+ components of the runtime system. Users do not normally add
+ new kernel processes.
+ </item>
+ <item><c>{apply, {Mod, Func, Args}}</c>. The init process simply
+ evaluates <c>apply(Mod, Func, Args)</c>. The system
+ terminates if this results in an error. The boot procedure
+ hangs if this function never returns.
+ </item>
+ </list>
+ <note>
+ <p>In the <c>interactive</c> system the code loader provides
+ demand driven code loading, but in the <c>embedded</c> system
+ the code loader loads all the code immediately. The same
+ version of <c>code</c> is used in both cases. The code server
+ calls <c>init:get_argument(mode)</c> to find out if it should
+ run in demand mode, or non-demand driven mode.
+ </p>
+ </note>
+ </section>
+
+ <section>
+ <title>SEE ALSO</title>
+ <p>systools(3)
+ </p>
+ </section>
+</fileref>
+
diff --git a/lib/sasl/doc/src/systools.xml b/lib/sasl/doc/src/systools.xml
new file mode 100644
index 0000000000..296553bb12
--- /dev/null
+++ b/lib/sasl/doc/src/systools.xml
@@ -0,0 +1,362 @@
+<?xml version="1.0" encoding="latin1" ?>
+<!DOCTYPE erlref SYSTEM "erlref.dtd">
+
+<erlref>
+ <header>
+ <copyright>
+ <year>1996</year>
+ <year>2007</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.
+
+ The Initial Developer of the Original Code is Ericsson AB.
+ </legalnotice>
+
+ <title>systools</title>
+ <prepared></prepared>
+ <docno></docno>
+ <date></date>
+ <rev></rev>
+ </header>
+ <module>systools</module>
+ <modulesummary>A Set of Release Handling Tools.</modulesummary>
+ <description>
+ <p>This module contains functions to generate boot scripts
+ (<c>.boot</c>, <c>.script</c>), release upgrade scripts
+ (<c>relup</c>), and release packages.</p>
+ </description>
+ <funcs>
+ <func>
+ <name>make_relup(Name, UpFrom, DownTo) -> Result</name>
+ <name>make_relup(Name, UpFrom, DownTo, [Opt]) -> Result</name>
+ <fsummary>Generate a release upgrade file <c>relup</c>.</fsummary>
+ <type>
+ <v>Name = string()</v>
+ <v>UpFrom = DownTo = [Name | {Name,Descr}]</v>
+ <v>&nbsp;Descr = term()</v>
+ <v>Opt = {path,[Dir]} | restart_emulator | silent | noexec | {outdir,Dir}</v>
+ <v>&nbsp;Dir = string()</v>
+ <v>Result = ok | error | {ok,Relup,Module,Warnings} | {error,Module,Error}</v>
+ <v>&nbsp;Relup - see relup(4)</v>
+ <v>&nbsp;Module = atom()</v>
+ <v>&nbsp;Warnings = Error = term()</v>
+ </type>
+ <desc>
+ <p>Generates a release upgrade file <c>relup</c> containing a
+ script which describes how to upgrade the system from a number
+ of previous releases, and how to downgrade to a number of
+ previous releases. The script is used by
+ <c>release_handler</c> when installing a new version of a
+ release in run-time.</p>
+ <p>By default, <c>relup</c> is placed in the current working
+ directory. If the option <c>{outdir,Dir}</c> is provided,
+ <c>relup</c> is placed in <c>Dir</c> instead.</p>
+ <p>The release resource file <c>Name.rel</c> is compared with
+ all release resource files <c>Name2.rel</c> specified in
+ <c>UpFrom</c> and <c>DownTo</c>. For each such pair, it is
+ deducted:</p>
+ <list type="bulleted">
+ <item>
+ <p>Which applications should be deleted, that is
+ applications which are listed in <c>Name.rel</c> but not
+ in <c>Name2.rel</c>.</p>
+ </item>
+ <item>
+ <p>Which applications should be added, that is applications
+ which are listed in <c>Name2.rel</c> but not in
+ <c>Name.rel</c>.</p>
+ </item>
+ <item>
+ <p>Which applications should be upgraded/downgraded, that
+ is applications listed in both <c>Name.rel</c> and
+ <c>Name2.rel</c>, but with different versions.</p>
+ </item>
+ <item>
+ <p>If the emulator needs to be restarted after upgrading or
+ downgrading, that is if the ERTS version differs between
+ <c>Name.rel</c> and <c>Name2.rel</c>.</p>
+ </item>
+ </list>
+ <p>Instructions for this are added to the <c>relup</c> script in
+ the above order. Instructions for upgrading or downgrading
+ between application versions are fetched from the relevant
+ application upgrade files <c>App.appup</c>, sorted in
+ the same order as when generating a boot script, see
+ <c>make_script/1,2</c>. High-level instructions are translated
+ into low-level instructions and the result is printed to
+ <c>relup</c>.</p>
+ <p>The optional <c>Descr</c> parameter is included as-is in
+ the <c>relup</c> script, see <c>relup(4)</c>. Defaults to
+ the empty list.</p>
+ <p>All the files are searched for in the code path. It is
+ assumed that the <c>.app</c> and <c>.appup</c> file for an
+ application is located in the same directory.</p>
+ <p>If the option <c>{path,[Dir]}</c> is provided, this path is
+ appended to the current path. The wildcard <c>*</c> is
+ expanded to all matching directories.
+ Example: <c>lib/*/ebin</c>.</p>
+ <p>If the <c>restart_emulator</c> option is supplied, a
+ low-level instruction to restart the emulator is appended to
+ the relup scripts. This ensures that a complete reboot of
+ the system is done when the system is upgraded or downgraded.</p>
+ <p>By default, errors and warnings are printed to tty and
+ the function returns <c>ok</c> or <c>error</c>. If the option
+ <c>silent</c> is provided, the function instead returns
+ <c>{ok,Relup,Module,Warnings}</c> where <c>Relup</c> is
+ the release upgrade script, or it returns
+ <c>{error,Module,Error}</c>. Warnings and errors can be
+ converted to strings by calling
+ <c>Module:format_warning(Warnings)</c> or
+ <c>Module:format_error(Error)</c>.</p>
+ <p>If the option <c>noexec</c> is provided, the function returns
+ the same values as for <c>silent</c> but no <c>relup</c> file
+ is created.</p>
+ </desc>
+ </func>
+ <func>
+ <name>make_script(Name) -> Result</name>
+ <name>make_script(Name, [Opt]) -> Result</name>
+ <fsummary>Generate a boot script <c>.script/.boot</c>.</fsummary>
+ <type>
+ <v>Name = string()</v>
+ <v>Opt = no_module_tests | {path,[Dir]} | local | {variables,[Var]} | exref | {exref,[App]}] | silent | {outdir,Dir}</v>
+ <v>&nbsp;Dir = string()</v>
+ <v>&nbsp;Var = {VarName,Prefix}</v>
+ <v>&nbsp;&nbsp;VarName = Prefix = string()</v>
+ <v>&nbsp;App = atom()</v>
+ <v>Result = ok | error | {ok,Module,Warnings} | {error,Module,Error}</v>
+ <v>&nbsp;Module = atom()</v>
+ <v>&nbsp;Warnings = Error = term()</v>
+ </type>
+ <desc>
+ <p>Generates a boot script <c>Name.script</c> and its binary
+ version, the boot file <c>Name.boot</c>. The boot file
+ specifies which code should be loaded and which applications
+ should be started when the Erlang runtime system is started.
+ See <c>script(4)</c>.</p>
+ <p>The release resource file <c>Name.rel</c> is read to find
+ out which applications are included in the release. Then
+ the relevant application resource files <c>App.app</c> are
+ read to find out which modules should be loaded and if and
+ how the application should be started. (Keys <c>modules</c>
+ and <c>mod</c>, see <c>app(4)</c>).</p>
+ <p>By default, the boot script and boot file are placed in
+ the same directory as <c>Name.rel</c>. That is, in the current
+ working directory unless <c>Name</c> contains a path. If
+ the option <c>{outdir,Dir}</c> is provided, they are placed
+ in <c>Dir</c> instead.</p>
+ <p>The correctness of each application is checked:</p>
+ <list type="bulleted">
+ <item>
+ <p>The version of an application specified in
+ the <c>.rel</c> file should be the same as the version
+ specified in the <c>.app</c> file.</p>
+ </item>
+ <item>
+ <p>There should be no undefined applications, that is,
+ dependencies to applications which are not included in
+ the release. (Key <c>applications</c> in <c>.app</c>
+ file).</p>
+ </item>
+ <item>
+ <p>There should be no circular dependencies among
+ the applications.</p>
+ </item>
+ <item>
+ <p>There should no duplicated modules, that is, modules with
+ the same name but belonging to different applications.</p>
+ </item>
+ <item>
+ <p>A warning is issued if the source code for a module is
+ missing or newer than the object code. <br></br>
+
+ If the <c>no_module_tests</c> option is specified, this
+ check is omitted.</p>
+ </item>
+ </list>
+ <p>The applications are sorted according to the dependencies
+ between the applications. Where there are no dependencies,
+ the order in the <c>.rel</c> file is kept.</p>
+ <p>All files are searched for in the current path. It is
+ assumed that the <c>.app</c> and <c>.beam</c> files for an
+ application is located in the same directory. The <c>.erl</c>
+ files are also assumed to be located in this directory, unless
+ it is an <c>ebin</c> directory in which case they may be
+ located in the corresponding <c>src</c> directory.</p>
+ <p>If the option <c>{path,[Dir]}</c> is provided, this path is
+ appended to the current path. A directory in the path can be
+ given with a wildcard <c>*</c>, this is expanded to all
+ matching directories. Example: <c>"lib/*/ebin"</c>.</p>
+ <p>In the generated boot script all application directories are
+ structured as <c>App-Vsn/ebin</c> and assumed to be located
+ in <c>$ROOT/lib</c>, where <c>$ROOT</c> is the root directory
+ of the installed release. If the <c>local</c> option is
+ supplied, the actual directories where the applications were
+ found are used instead. This is a useful way to test a
+ generated boot script locally.</p>
+ <p>The <c>variables</c> option can be used to specify an
+ installation directory other than <c>$ROOT/lib</c> for some of
+ the applications. If a variable <c>{VarName,Prefix}</c> is
+ specified and an application is found in a directory
+ <c>Prefix/Rest/App[-Vsn]/ebin</c>, this application will get
+ the path <c>VarName/Rest/App-Vsn/ebin</c> in the boot script.
+ If an application is found in a directory <c>Prefix/Rest</c>,
+ the path will be <c>VarName/Rest/App-Vsn/ebin</c>. When
+ starting Erlang, all variables <c>VarName</c> are given
+ values using the <c>boot_var</c> command line flag.</p>
+ <p>Example: If the option <c>{variables,[{"TEST","lib"}]}</c> is
+ supplied, and <c>myapp.app</c> is found in
+ <c>lib/myapp/ebin</c>, then the path to this application in
+ the boot script will be <c>$TEST/myapp-1/ebin"</c>. If
+ <c>myapp.app</c> is found in <c>lib/test</c>, then the path
+ will be <c>$TEST/test/myapp-1/ebin</c>.</p>
+ <p>The checks performed before the boot script is generated can
+ be extended with some cross reference checks by specifying
+ the <c>exref</c> option. These checks are performed with
+ the Xref tool. All applications, or the applications specified
+ with <c>{exref,[App]}</c>, are checked by Xref and
+ warnings are generated for calls to undefined functions.</p>
+ <p>By default, errors and warnings are printed to tty and
+ the function returns <c>ok</c> or <c>error</c>. If the option
+ <c>silent</c> is provided, the function instead returns
+ <c>{ok,Module,Warnings}</c> or <c>{error,Module,Error}</c>.
+ Warnings and errors can be converted to strings by calling
+ <c>Module:format_warning(Warnings)</c> or
+ <c>Module:format_error(Error)</c>.</p>
+ </desc>
+ </func>
+ <func>
+ <name>make_tar(Name) -> Result</name>
+ <name>make_tar(Name, [Opt]) -> Result</name>
+ <fsummary>Create a release package.</fsummary>
+ <type>
+ <v>Name = string()</v>
+ <v>Opt = {dirs,[IncDir]} | {path,[Dir]} | {variables,[Var]} | {var_tar,VarTar} | {erts,Dir} | no_module_tests | exref | {exref,[App]} | silent | {outdir,Dir}</v>
+ <v>&nbsp;Dir = string()</v>
+ <v>&nbsp;IncDir = src | include | atom()</v>
+ <v>&nbsp;Var = {VarName,PreFix}</v>
+ <v>&nbsp;&nbsp;VarName = Prefix = string()</v>
+ <v>&nbsp;VarTar = include | ownfile | omit</v>
+ <v>&nbsp;Machine = atom()</v>
+ <v>&nbsp;App = atom()</v>
+ <v>Result = ok | error | {ok,Module,Warnings} | {error,Module,Error}</v>
+ <v>&nbsp;Module = atom()</v>
+ <v>&nbsp;Warning = Error = term()</v>
+ </type>
+ <desc>
+ <p>Creates a release package file <c>Name.tar.gz</c>. file.
+ This file must be uncompressed and unpacked on the target
+ system using the <c>release_handler</c>, before the new
+ release can be installed.</p>
+ <p>The release resource file <c>Name.rel</c> is read to find out
+ which applications are included in the release. Then
+ the relevant application resource files <c>App.app</c> are
+ read to find out the version and modules of each application.
+ (Keys <c>vsn</c> and <c>modules</c>, see <c>app(4)</c>).</p>
+ <p>By default, the release package file is placed in the same
+ directory as <c>Name.rel</c>. That is, in the current working
+ directory unless <c>Name</c> contains a path. If the option
+ <c>{outdir,Dir}</c> is provided, it is placed in <c>Dir</c>
+ instead.</p>
+ <p>By default, the release package contains the directories
+ <c>lib/App-Vsn/ebin</c> and <c>lib/App-Vsn/priv</c> for each
+ included application. If more directories, the option
+ <c>dirs</c> is supplied. Example:
+ <c>{dirs,[src,examples]}</c>.</p>
+ <p>All these files are searched for in the current path. If
+ the option <c>{path,[Dir]}</c> is provided, this path is
+ appended to the current path. The wildcard <c>*</c> is
+ expanded to all matching directories.
+ Example: <c>"lib/*/ebin"</c>.</p>
+ <p>The <c>variables</c> option can be used to specify an
+ installation directory other than <c>lib</c> for some of
+ the applications. If a variable <c>{VarName,Prefix}</c> is
+ specified and an application is found in a directory
+ <c>Prefix/Rest/App[-Vsn]/ebin</c>, this application will be
+ packed into a separate <c>VarName.tar.gz</c> file as
+ <c>Rest/App-Vsn/ebin</c>.</p>
+ <p>Example: If the option <c>{variables,[{"TEST","lib"}]}</c> is
+ supplied, and <c>myapp.app</c> is found in
+ <c>lib/myapp-1/ebin</c>, the the application <c>myapp</c> is
+ included in <c>TEST.tar.gz</c>:</p>
+ <pre>
+% <input>tar tf TEST.tar</input>
+myapp-1/ebin/myapp.app
+...
+ </pre>
+ <p>The <c>{var_tar,VarTar}</c> option can be used to specify if
+ and where a separate package should be stored. In this option,
+ <c>VarTar</c> is:</p>
+ <list type="bulleted">
+ <item>
+ <p><c>include</c>. Each separate (variable) package is
+ included in the main <c>ReleaseName.tar.gz</c> file. This
+ is the default.</p>
+ </item>
+ <item>
+ <p><c>ownfile</c>. Each separate (variable) package is
+ generated as separate files in the same directory as
+ the <c>ReleaseName.tar.gz</c> file.</p>
+ </item>
+ <item>
+ <p><c>omit</c>. No separate (variable) packages are
+ generated and applications which are found underneath a
+ variable directory are ignored.</p>
+ </item>
+ </list>
+ <p>A directory called <c>releases</c> is also included in
+ the release package, containing <c>Name.rel</c> and a
+ subdirectory called <c>RelVsn</c>. <c>RelVsn</c> is
+ the release version as specified in <c>Name.rel</c>.</p>
+ <p><c>releases/RelVsn</c> contains the boot script
+ <c>Name.boot</c> renamed to <c>start.boot</c> and, if found,
+ the files <c>relup</c> and <c>sys.config</c>. These files
+ are searched for in the same directory as <c>Name.rel</c>,
+ in the current working directory, and in any directories
+ specified using the <c>path</c> option.</p>
+ <p>If the release package should contain a new Erlang runtime
+ system, the <c>bin</c> directory of the specified runtime
+ system <c>{erts,Dir}</c> is copied to <c>erts-ErtsVsn/bin</c>.</p>
+ <p>All checks performed with the <c>make_script</c> function
+ are performed before the release package is created. The
+ <c>no_module_tests</c> and <c>exref</c> options are also
+ valid here.</p>
+ <p>The return value and the handling of errors and warnings
+ are the same as described for <c>make_script</c> above.</p>
+ </desc>
+ </func>
+ <func>
+ <name>script2boot(File) -> ok | error</name>
+ <fsummary>Generate a binary version of a boot script.</fsummary>
+ <type>
+ <v>File = string()</v>
+ </type>
+ <desc>
+ <p>The Erlang runtime system requires that the contents of
+ the script used to boot the system is a binary Erlang term.
+ This function transforms the <c>File.script</c> boot script
+ to a binary term which is stored in the file <c>File.boot</c>.</p>
+ <p>A boot script generated using the <c>make_script</c>
+ function is already transformed to the binary form.</p>
+ </desc>
+ </func>
+ </funcs>
+
+ <section>
+ <title>SEE ALSO</title>
+ <p>app(4), appup(4), erl(1), rel(4), release_handler(3), relup(4),
+ script(4)</p>
+ </section>
+</erlref>
+
diff --git a/lib/sasl/doc/src/warning.gif b/lib/sasl/doc/src/warning.gif
new file mode 100644
index 0000000000..96af52360e
--- /dev/null
+++ b/lib/sasl/doc/src/warning.gif
Binary files differ