diff options
Diffstat (limited to 'lib/sasl/doc')
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örklund</prepared> + <responsible>Bjarne Dacker</responsible> + <docno></docno> + <approved>Bjarne Däcker</approved> + <checked>Martin Bjö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öberg</prepared> + <responsible>Bjarne Dä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 === + <0.63.0>: Divide by zero ! + + =CRASH REPORT==== 27-May-1996::13:38:56 === + crasher: + pid: <0.63.0> + registered_name: [] + error_info: {badarith,{test,s,[]}} + initial_call: {test,s,[]} + ancestors: [test_sup,<0.46.0>] + messages: [] + links: [<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,<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,<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 <0.17.0> 1996-10-16 16:14:54 + 19 progress <0.14.0> 1996-10-16 16:14:55 + 18 error <0.15.0> 1996-10-16 16:15:02 + 17 progress <0.14.0> 1996-10-16 16:15:06 + 16 progress <0.38.0> 1996-10-16 16:15:12 + 15 progress <0.17.0> 1996-10-16 16:16:14 + 14 progress <0.17.0> 1996-10-16 16:16:14 + 13 progress <0.17.0> 1996-10-16 16:16:14 + 12 progress <0.14.0> 1996-10-16 16:16:14 + 11 error <0.17.0> 1996-10-16 16:16:21 + 10 error <0.17.0> 1996-10-16 16:16:21 + 9 crash_report release_handler 1996-10-16 16:16:21 + 8 supervisor_report <0.17.0> 1996-10-16 16:16:21 + 7 progress <0.17.0> 1996-10-16 16:16:21 + 6 progress <0.17.0> 1996-10-16 16:16:36 + 5 progress <0.17.0> 1996-10-16 16:16:36 + 4 progress <0.17.0> 1996-10-16 16:16:36 + 3 progress <0.14.0> 1996-10-16 16:16:36 + 2 error <0.15.0> 1996-10-16 16:17:04 + 1 progress <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 <0.20.0> 1996-10-16 16:16:36 +=============================================================================== +supervisor {local,sasl_sup} +started +[{pid,<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 <0.24.0> 1996-10-16 16:16:21 +=============================================================================== +Crashing process +pid <0.24.0> +registered_name release_handler +error_info {undef,{release_handler,mbj_func,[]}} +initial_call +{gen,init_it, +[gen_server, +<0.20.0>, +<0.20.0>, +{erlang,register}, +release_handler, +release_handler, +[], +[]]} +ancestors [sasl_sup,<0.18.0>] +messages [] +links [<0.23.0>,<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 <0.24.0> 1996-10-16 16:16:21 +=============================================================================== + +** undefined function: release_handler:mbj_func[] ** +Found match in report number 10 + +ERROR REPORT <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 <0.24.0> 1996-10-16 16:16:21 +=============================================================================== +Crashing process +pid <0.24.0> +registered_name release_handler +error_info {undef,{release_handler,mbj_func,[]}} +initial_call +{gen,init_it, +[gen_server, +<0.20.0>, +<0.20.0>, +{erlang,register}, +release_handler, +release_handler, +[], +[]]} +ancestors [sasl_sup,<0.18.0>] +messages [] +links [<0.23.0>,<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 <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 <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 Binary files differnew file mode 100644 index 0000000000..6fffe30419 --- /dev/null +++ b/lib/sasl/doc/src/note.gif 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ögfeldt</prepared> + <responsible>Peter Hö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örklund</prepared> + <responsible>Martin Björklund</responsible> + <docno></docno> + <approved>Bjarne Dä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> App = atom()</v> + <v> 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> | {suspend_timeout, Timeout} | {update_paths, Bool}</v> + <v> Action = restart | reboot</v> + <v> Timeout = default | infinity | int()>0</v> + <v> 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> App = atom()</v> + <v> 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> 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> 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> 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örklund</prepared> + <responsible>Bjarne Däcker</responsible> + <docno></docno> + <approved>Bjarne Dä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> Descr = term()</v> + <v>Opt = {path,[Dir]} | restart_emulator | silent | noexec | {outdir,Dir}</v> + <v> Dir = string()</v> + <v>Result = ok | error | {ok,Relup,Module,Warnings} | {error,Module,Error}</v> + <v> Relup - see relup(4)</v> + <v> Module = atom()</v> + <v> 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> Dir = string()</v> + <v> Var = {VarName,Prefix}</v> + <v> VarName = Prefix = string()</v> + <v> App = atom()</v> + <v>Result = ok | error | {ok,Module,Warnings} | {error,Module,Error}</v> + <v> Module = atom()</v> + <v> 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> Dir = string()</v> + <v> IncDir = src | include | atom()</v> + <v> Var = {VarName,PreFix}</v> + <v> VarName = Prefix = string()</v> + <v> VarTar = include | ownfile | omit</v> + <v> Machine = atom()</v> + <v> App = atom()</v> + <v>Result = ok | error | {ok,Module,Warnings} | {error,Module,Error}</v> + <v> Module = atom()</v> + <v> 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 Binary files differnew file mode 100644 index 0000000000..96af52360e --- /dev/null +++ b/lib/sasl/doc/src/warning.gif |
