diff options
Diffstat (limited to 'lib/sasl')
74 files changed, 3169 insertions, 2699 deletions
diff --git a/lib/sasl/Makefile b/lib/sasl/Makefile index 9085c487d4..065eb45fbb 100644 --- a/lib/sasl/Makefile +++ b/lib/sasl/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1996-2010. All Rights Reserved. +# Copyright Ericsson AB 1996-2016. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/lib/sasl/doc/src/Makefile b/lib/sasl/doc/src/Makefile index 1ee48af338..baf563ca62 100644 --- a/lib/sasl/doc/src/Makefile +++ b/lib/sasl/doc/src/Makefile @@ -9,11 +9,11 @@ # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. # See the License for the specific language governing permissions 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 @@ -36,7 +36,6 @@ RELSYSDIR = $(RELEASE_PATH)/lib/$(APPLICATION)-$(VSN) # ---------------------------------------------------- XML_APPLICATION_FILES = ref_man.xml XML_REF3_FILES = alarm_handler.xml \ - overload.xml \ rb.xml \ release_handler.xml \ systools.xml @@ -45,17 +44,14 @@ 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_PART_FILES = part.xml XML_CHAPTER_FILES = sasl_intro.xml \ error_logging.xml \ - notes.xml \ - notes_history.xml + notes.xml BOOK_FILES = book.xml -GIF_FILES = \ - note.gif \ - warning.gif +GIF_FILES = XML_FILES = \ $(BOOK_FILES) $(XML_CHAPTER_FILES) \ @@ -79,14 +75,14 @@ HTML_REF_MAN_FILE = $(HTMLDIR)/index.html TOP_PDF_FILE = $(PDFDIR)/$(APPLICATION)-$(VSN).pdf # ---------------------------------------------------- -# FLAGS +# FLAGS # ---------------------------------------------------- -XML_FLAGS += +XML_FLAGS += # ---------------------------------------------------- # Targets # ---------------------------------------------------- -$(HTMLDIR)/%.gif: %.gif +$(HTMLDIR)/%.gif: %.gif $(INSTALL_DATA) $< $@ docs: pdf html man @@ -101,7 +97,7 @@ man: $(MAN3_FILES) $(MAN4_FILES) $(MAN6_FILES) gifs: $(GIF_FILES:%=$(HTMLDIR)/%) # We depend just to copy them to ../html -debug opt: +debug opt: clean clean_docs: rm -rf $(HTMLDIR)/* @@ -109,11 +105,11 @@ clean clean_docs: rm -f $(MAN4DIR)/* rm -f $(MAN6DIR)/* rm -f $(TOP_PDF_FILE) $(TOP_PDF_FILE:%.pdf=%.fo) - rm -f errs core *~ + rm -f errs core *~ # ---------------------------------------------------- # Release Target -# ---------------------------------------------------- +# ---------------------------------------------------- include $(ERL_TOP)/make/otp_release_targets.mk release_docs_spec: docs @@ -131,4 +127,3 @@ release_docs_spec: docs $(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 index b98f22d2a1..4160757164 100644 --- a/lib/sasl/doc/src/alarm_handler.xml +++ b/lib/sasl/doc/src/alarm_handler.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1996</year> - <year>2014</year> + <year>2016</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -37,94 +37,92 @@ <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 alarm handler process is a + <seealso marker="stdlib:gen_event"><c>gen_event</c></seealso> + event manager process that 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 startup, 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> + the error logger, and saves all in a list. This list can be + passed to a user-defined event handler, which can be installed + later. The list can grow large if many alarms are generated. + This is a good reason to install a better user-defined + handler.</p> + <p>Functions are provided to set and clear alarms. The alarm + format is defined by the user. For example, an event handler + for SNMP can be defined, together with an alarm Management + Information Base (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> + 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> + <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> + 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> + it can be exchanged by calling + <seealso marker="stdlib:gen_event#swap_handler/3"><c>gen_event:swap_handler/3</c></seealso> + as <c>gen_event:swap_handler(alarm_handler, {alarm_handler, swap}, + {NewHandler, Args})</c>. <c>NewHandler:init({Args, {alarm_handler, + Alarms}})</c> is called. For more details, see + <seealso marker="stdlib:gen_event"><c>gen_event(3)</c></seealso> + in STDLIB.</p> </description> + <funcs> <func> <name>clear_alarm(AlarmId) -> void()</name> - <fsummary>Clear the specified alarms</fsummary> + <fsummary>Clears the specified alarms.</fsummary> <type> <v>AlarmId = term()</v> </type> <desc> - <p>Sends the <c>clear_alarm</c> event to all event handlers.</p> + <p>Sends event <c>clear_alarm</c> to all event handlers.</p> <p>When receiving this event, the default simple handler - clears the latest received alarm with id <c>AlarmId</c>. - </p> + clears the latest received alarm with id <c>AlarmId</c>.</p> </desc> </func> + <func> <name>get_alarms() -> [alarm()]</name> - <fsummary>Get all active alarms</fsummary> + <fsummary>Gets 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> + 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> + <fsummary>Sets an alarm with an id.</fsummary> <type> <v>alarm() = {AlarmId, AlarmDescription}</v> <v>AlarmId = term()</v> <v>AlarmDescription = term()</v> </type> <desc> - <p>Sends the <c>set_alarm</c> event to all event handlers.</p> + <p>Sends event <c>set_alarm</c> to all event handlers.</p> <p>When receiving this event, the default simple handler - stores the alarm. The <c>AlarmId</c> identifies the alarm - and is used when the alarm is cleared. - </p> + stores the alarm. <c>AlarmId</c> identifies the alarm + and is used when the alarm is cleared.</p> </desc> </func> </funcs> <section> <title>See Also</title> - <p>error_logger(3), gen_event(3) - </p> + <p><seealso marker="kernel:error_logger"><c>error_logger(3)</c></seealso>, + <seealso marker="stdlib:gen_event"><c>gen_event(3)</c></seealso></p> </section> </erlref> diff --git a/lib/sasl/doc/src/appup.xml b/lib/sasl/doc/src/appup.xml index 72333960ec..a43a966dcb 100644 --- a/lib/sasl/doc/src/appup.xml +++ b/lib/sasl/doc/src/appup.xml @@ -4,7 +4,7 @@ <fileref> <header> <copyright> - <year>1997</year><year>2014</year> + <year>1997</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -29,78 +29,85 @@ <rev></rev> </header> <file>appup</file> - <filesummary>Application upgrade file.</filesummary> + <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> + <p>This file is used by the functions in + <seealso marker="systools"><c>systools</c></seealso> + 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> + <title>File Syntax</title> + <p>The application upgrade file is to be called + <c>Application.appup</c>, where <c>Application</c> is the + application name. The file is to 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> + 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() | binary()</c> is an earlier - version of the application to upgrade from. If it is a - string, it will be interpreted as a specific version - number. If it is a binary, it will be interpreted as a - regular expression which can match multiple version - numbers.</p> - </item> - <item> - <p><c>DownToVsn = string() | binary()</c> is an earlier - version of the application to downgrade to. If it is a - string, it will be interpreted as a specific version - number. If it is a binary, it will be interpreted as a - regular expression which can match multiple version - numbers.</p> - </item> - <item> - <p><c>Instructions</c> is a list of <em>release upgrade instructions</em>, see below. It is recommended to use + [{DownToVsn, Instructions}, ...]}.</code> + <taglist> + <tag><c>Vsn = string()</c></tag> + <item><p>Current application version.</p></item> + <tag><c>UpFromVsn = string() | binary()</c></tag> + <item><p>An earlier + application version to upgrade from. If it is a + string, it is interpreted as a specific version + number. If it is a binary, it is interpreted as a + regular expression that can match multiple version + numbers.</p></item> + <tag><c>DownToVsn = string() | binary()</c></tag> + <item><p>An earlier + application version to downgrade to. If it is a + string, it is interpreted as a specific version + number. If it is a binary, it is interpreted as a + regular expression that can match multiple version + numbers.</p></item> + <tag><c>Instructions</c></tag> + <item><p>A list of <em>release upgrade instructions</em>, see + <seealso marker="#Release Upgrade Instructions">Release + Upgrade Instructions</seealso>. 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> - <p>In order to avoid duplication of upgrade instructions it is - allowed to use regular expressions to specify the <c>UpFromVsn</c> - and <c>DownToVsn</c>. To be considered a regular expression, the - version identifier must be specified as a binary, e.g.</p> - <code type="none"><<"2\\.1\\.[0-9]+">></code> - <p>will match all versions <c>2.1.x</c>, where x is any number.</p> - <p>Note that the regular expression must match the complete - version string, so the above example will work for for - e.g. <c>2.1.1</c>, but not for <c>2.1.1.1</c></p> + creating the <c>relup</c> file.</p></item> + </taglist> + <p>To avoid duplication of upgrade instructions, it is + allowed to use regular expressions to specify <c>UpFromVsn</c> + and <c>DownToVsn</c>. To be considered a regular expression, the + version identifier must be specified as a binary. For example, + the following match all versions <c>2.1.x</c>, where <c>x</c> is + any number:</p> + <code type="none"> +<<"2\\.1\\.[0-9]+">></code> + <p>Notice that the regular expression must match the complete + version string, so this example works for, for example, + <c>2.1.1</c>, but not for <c>2.1.1.1</c>.</p> </section> <section> - <title>RELEASE UPGRADE INSTRUCTIONS</title> + <marker id="Release Upgrade Instructions"></marker> + <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 + information about release handling, see + <seealso marker="doc/design_principles:release_handling">OTP + Design Principles</seealso> in <em>System Documentation</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> + specification used to start the process, see + <seealso marker="stdlib:supervisor"><c>supervisor(3)</c></seealso>. + In the case of + <seealso marker="stdlib:gen_event"><c>gen_event</c></seealso>, + an event manager process is said to use <c>Mod</c> if <c>Mod</c> + is an installed event handler.</p> + + <section> + <title>High-Level Instructions</title> <pre> {update, Mod} {update, Mod, supervisor} @@ -116,52 +123,69 @@ 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 + DepMods = [Mod]</pre> + <p>Synchronized code replacement of processes using module + <c>Mod</c>.</p> + <p>All those processes are suspended using + <seealso marker="stdlib:sys#suspend/1"><c>sys:suspend</c></seealso>, + the new module version is loaded, and + then the processes are resumed using + <seealso marker="stdlib:sys#resume/1"><c>sys:resume</c></seealso>.</p> + <taglist> + <tag><c>Change</c></tag> + <item><p>Defaults to <c>soft</c> and defines the type of + code change. If it is set to <c>{advanced,Extra}</c>, implemented + processes using + <seealso marker="stdlib:gen_server"><c>gen_server</c></seealso>, + <seealso marker="stdlib:gen_fsm"><c>gen_fsm</c></seealso>, + <seealso marker="stdlib:gen_statem"><c>gen_statem</c></seealso>, or + <seealso marker="stdlib:gen_event"><c>gen_event</c></seealso> + transform their internal state by calling the callback function + <c>code_change</c>. Special processes 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 + <c>Extra</c> is passed as an argument to the callback + function.</p></item> + <tag><c>PrePurge</c></tag> + <item><p>Defaults to <c>brutal_purge</c>. It controls + what action to take with processes executing old code + before loading the new module version. 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 + <c>soft_purge</c>, + <seealso marker="release_handler#install_release/1"><c>release_handler:install_release/1</c></seealso> + returns <c>{error,{old_processes,Mod}}</c>.</p></item> + <tag><c>PostPurge</c></tag> + <item><p>Defaults to <c>brutal_purge</c>. It 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 + when the new module version 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 + <c>soft_purge</c>, the release handler purges the old code + when no remaining processes execute the code.</p></item> + <tag><c>DepMods</c></tag> + <item><p>Defaults to <c>[]</c> and defines other modules that + <c>Mod</c> is dependent on. In the <c>relup</c> file, instructions + for suspending processes using <c>Mod</c> come before instructions for suspending processes using modules in - <c>DepMods</c> when upgrading, and vice versa when downgrading. + <c>DepMods</c> when upgrading, and conversely 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 + the <c>appup</c> file is kept.</p></item> + <tag><c>Timeout</c></tag> + <item><p>Defines the time-out when suspending processes. + If no value or <c>default</c> is specified, the default value for + <seealso marker="stdlib:sys#suspend/1"><c>sys:suspend</c></seealso> + is used.</p></item> + <tag><c>ModType</c></tag> + <item><p>Defaults to <c>dynamic</c>. It specifies if + the code is "dynamic", that is, if a process using the module + spontaneously switches to new code, or if it is "static". + When doing an advanced update and upgrade, 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> + dynamic.</p></item> + </taglist> <p><c>update</c> with argument <c>supervisor</c> is used when changing the start specification of a supervisor.</p> <pre> @@ -170,239 +194,229 @@ {load_module, Mod, PrePurge, PostPurge, DepMods} Mod = atom() PrePurge = PostPurge = soft_purge | brutal_purge - DepMods = [Mod] - </pre> + 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> + <p>For a description of <c>PrePurge</c> and <c>PostPurge</c>, + see <c>update</c> above.</p> + <p><c>DepMods</c> defaults to <c>[]</c> and defines which other modules + <c>Mod</c> is dependent on. In the <c>relup</c> file, instructions for + loading these modules come before the instruction for loading + <c>Mod</c> when upgrading, and conversely when downgrading.</p> <pre> {add_module, Mod} {add_module, Mod, DepMods} Mod = atom() - DepMods = [Mod] - </pre> + DepMods = [Mod]</pre> <p>Loads a new module <c>Mod</c>.</p> - <p><c>DepMods</c> defaults to [] and defines which other modules - <c>Mod</c> is dependent on. In <c>relup</c>, instructions - related to these modules will come before the instruction for - loading <c>Mod</c> when upgrading, and vice versa when + <p><c>DepMods</c> defaults to <c>[]</c> and defines which other modules + <c>Mod</c> is dependent on. In the <c>relup</c> file, instructions + related to these modules come before the instruction for + loading <c>Mod</c> when upgrading, and conversely when downgrading.</p> <pre> {delete_module, Mod} {delete_module, Mod, DepMods} - Mod = atom() - </pre> + Mod = atom()</pre> <p>Deletes a module <c>Mod</c> using the low-level instructions <c>remove</c> and <c>purge</c>.</p> - <p><c>DepMods</c> defaults to [] and defines which other modules - <c>Mod</c> is dependent on. In <c>relup</c>, instructions - related to these modules will come before the instruction for - removing <c>Mod</c> when upgrading, and vice versa when + <p><c>DepMods</c> defaults to <c>[]</c> and defines which other modules + <c>Mod</c> is dependent on. In the <c>relup</c> file, instructions + related to these modules come before the instruction for + removing <c>Mod</c> when upgrading, and conversely when downgrading.</p> <pre> {add_application, Application} {add_application, Application, Type} Application = atom() - Type = permanent | transient | temporary | load | none - </pre> + Type = permanent | transient | temporary | load | none</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>.</p> <p><c>Type</c> defaults to <c>permanent</c> and specifies the start type of the application. 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.</p> + the application is loaded and started in the corresponding way, see + <seealso marker="kernel:application"><c>application(3)</c></seealso>. + If <c>Type = load</c>, the application is only loaded. + If <c>Type = none</c>, the application is not loaded and not + started, although the code for its modules is loaded.</p> <pre> {remove_application, Application} - Application = atom() - </pre> + 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 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> + Application = atom()</pre> <p>Restarting an application means that the application is - stopped and then started again similar to using the instructions + 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> + </section> + + <section> + <title>Low-Level Instructions</title> <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> + Vsn = string()</pre> + <p>Reads each <c>Mod</c> from directory <c>App-Vsn/ebin</c> as + a binary. It does not load the modules. The instruction is to be + placed first in the script to read all new code from the file + to make the suspend-load-resume cycle less time-consuming.</p> <pre> -point_of_no_return - </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 + recover and is restarted from the old release version. + The instruction must only occur once in a script. It is to 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> + 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> + <c>PrePurge</c> is ignored. For a description of <c>PostPurge</c>, + see the high-level instruction <c>update</c> earlier.</p> <pre> {remove, {Mod, PrePurge, PostPurge}} Mod = atom() - PrePurge = PostPurge = soft_purge | brutal_purge - </pre> + 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> + <c>PrePurge</c> is ignored. For a description of <c>PostPurge</c>, + see the high-level instruction <c>update</c> earlier.</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> + Mod = atom()</pre> + <p>Purges each module <c>Mod</c>, that is, removes the old code. + Notice that any process executing purged code is killed.</p> <pre> {suspend, [Mod | {Mod, Timeout}]} Mod = atom() - Timeout = int()>0 | default | infinity - </pre> + 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 + process does not respond, it is ignored. This can 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> + specified, the default value for + <seealso marker="stdlib:sys#suspend/1"><c>sys:suspend</c></seealso> + is used.</p> <pre> {resume, [Mod]} - Mod = atom() - </pre> + 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> + 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> + upgrade or downgrade. This instruction sends a <c>code_change</c> + system message to all processes using a module <c>Mod</c> by + calling function + <seealso marker="stdlib:sys#change_code/4"><c>sys:change_code</c></seealso>, + passing term <c>Extra</c> as argument.</p> <pre> {stop, [Mod]} - Mod = atom() - </pre> + 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 + <seealso marker="stdlib:supervisor#terminate_child/2"><c>supervisor:terminate_child/2</c></seealso>. + This instruction is useful when the simplest way to change code is to stop and restart the - processes which run the code.</p> + processes that run the code.</p> <pre> {start, [Mod]} - Mod = atom() - </pre> + Mod = atom()</pre> <p>Starts all stopped processes using a module <c>Mod</c> by calling - <c>supervisor:restart_child/2</c>.</p> + <seealso marker="stdlib:supervisor#restart_child/2"><c>supervisor:restart_child/2</c></seealso>.</p> <pre> {sync_nodes, Id, [Node]} {sync_nodes, Id, {M, F, A}} Id = term() Node = node() M = F = atom() - A = [term()] - </pre> + 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 + <p>This 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 + the instruction before execution continues. If 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 + time-out for this instruction, which means that it can 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> + A = [term()]</pre> + <p>Evaluates <c>apply(M, F, A)</c>.</p> + <p>If the instruction appears before instruction + <c>point_of_no_return</c>, a failure is caught. + <seealso marker="release_handler#install_release/1"><c>release_handler:install_release/1</c></seealso> + 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 instruction + <c>point_of_no_return</c> and the function call fails, the + system is restarted.</p> <pre> -restart_new_emulator - </pre> - <p>This instruction is used when erts, kernel, stdlib or sasl is +restart_new_emulator</pre> + <p>This instruction is used when the application ERTS, + Kernel, STDLIB, or SASL is upgraded. It shuts down the current emulator and starts a new one. All processes are terminated gracefully, and the new - version of erts, kernel, stdlib and sasl are used when the - emulator restarts. Only one <c>restart_new_emulator</c> - instruction is allowed in the relup, and it shall be placed - first. <seealso marker="systools#make_relup/3">systools:make_relup/3,4</seealso> - will ensure this when the relup is generated. The rest of the - relup script is executed after the restart as a part of the boot - script.</p> - <p>An info report will be written when the upgrade is - completed. To programatically find out if the upgrade is - complete, + version of ERTS, Kernel, STDLIB, and + SASL are used when the emulator restarts. + Only one <c>restart_new_emulator</c> instruction is allowed + in the <c>relup</c> file, and it must be placed first. + <seealso marker="systools#make_relup/3"><c>systools:make_relup/3,4</c></seealso> + ensures this when the <c>relup</c> file is generated. The rest of the + instructions in the <c>relup</c> file is executed after the + restart as a part of the boot script.</p> + <p>An info report is written when the upgrade is completed. + To programmatically determine if the upgrade is complete, call <seealso marker="release_handler#which_releases/0"> - release_handler:which_releases/0,1</seealso> and check if the + <c>release_handler:which_releases/0,1</c></seealso> and check if the expected release has status <c>current</c>.</p> <p>The new release must still be made permanent after the upgrade - is completed. Otherwise, the old emulator is started in case of + is completed, otherwise the old emulator is started if there is an emulator restart.</p> <warning> - <p>As stated above, the <c>restart_new_emulator</c> - instruction causes the emulator to be restarted with new - versions of <c>erts</c>, <c>kernel</c>, <c>stdlib</c> and - <c>sasl</c>. All other applications, however, will at startup - be running their old versions in this new emulator. In most - cases this is no problem, but every now and then there will be - incompatible changes to the core applications which may cause - trouble in this setting. Such incompatible changes (when - functions are removed) are normally preceded by a deprecation - over two major releases. To make sure your application is not - crashed by an incompatible change, always remove any call to - deprecated functions as soon as possible.</p> + <p>As stated earlier, instruction <c>restart_new_emulator</c> + causes the emulator to be restarted with new versions of + ERTS>, Kernel, STDLIB, and SASL. + However, all other applications do at startup run their old + versions in this new emulator. This is usually no problem, + but every now and then incompatible changes occur to the + core applications, which can cause + trouble in this setting. Such incompatible changes (when + functions are removed) are normally preceded by a deprecation + over two major releases. To ensure that your application is not + crashed by an incompatible change, always remove any call to + deprecated functions as soon as possible.</p> </warning> <pre> -restart_emulator - </pre> +restart_emulator</pre> <p>This instruction is similar to <c>restart_new_emulator</c>, - except it shall be placed at the end of the relup script. It is - not related to an upgrade of the emulator or the core + except it must be placed at the end of the <c>relup</c> file. + It is not related to an upgrade of the emulator or the core applications, but can be used by any application when a complete - reboot of the system is reqiured. When generating the - relup, <seealso marker="systools#make_relup/3">systools:make_relup/3,4</seealso> + reboot of the system is required.</p> + <p>When generating the <c>relup</c> file, + <seealso marker="systools#make_relup/3"><c>systools:make_relup/3,4</c></seealso> ensures that there is only one <c>restart_emulator</c> - instruction and that it is the last instruction of the - relup.</p> + instruction and that it is the last instruction in the + <c>relup</c> file.</p> + </section> </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> + <title>See Also</title> + <p><seealso marker="release_handler"><c>release_handler(3)</c></seealso>, + <seealso marker="relup"><c>relup(4)</c></seealso>, + <seealso marker="stdlib:supervisor"><c>supervisor(3)</c></seealso>, + <seealso marker="systools"><c>systools(3)</c></seealso></p> </section> </fileref> diff --git a/lib/sasl/doc/src/book.xml b/lib/sasl/doc/src/book.xml index 2bb5339d94..bca61ee8e7 100644 --- a/lib/sasl/doc/src/book.xml +++ b/lib/sasl/doc/src/book.xml @@ -4,7 +4,7 @@ <book xmlns:xi="http://www.w3.org/2001/XInclude"> <header titlestyle="normal"> <copyright> - <year>1997</year><year>2013</year> + <year>1997</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -22,7 +22,7 @@ </legalnotice> - <title>System Application Support Libraries (SASL)</title> + <title>System Architecture Support Libraries (SASL)</title> <prepared>OTP Team</prepared> <docno></docno> <date>1999-04-22</date> @@ -31,7 +31,7 @@ </header> <insidecover> </insidecover> - <pagetext>System Application Support Libraries (SASL)</pagetext> + <pagetext>System Architecture Support Libraries (SASL)</pagetext> <preamble> <contents level="2"></contents> </preamble> diff --git a/lib/sasl/doc/src/error_logging.xml b/lib/sasl/doc/src/error_logging.xml index 7c45b1970e..4b2c960bbb 100644 --- a/lib/sasl/doc/src/error_logging.xml +++ b/lib/sasl/doc/src/error_logging.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>1997</year><year>2013</year> + <year>1997</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,89 +31,94 @@ <date>1999-04-13</date> <rev>B</rev> <file>error_logging.xml</file> - </header> + </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> + <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> + <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, that is, the environment variables + in the SASL application specification, which is found in the + <c>.app</c> file of SASL. For details, see the + <seealso marker="sasl_app"><c>sasl(6)</c></seealso> application in the + Reference Manual and the <seealso marker="kernel:app"><c>app(4)</c></seealso> + file in the Kernel Reference Manual.</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 + <p>A supervisor report is issued when a supervised child terminates + unexpectedly. 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 + <tag><c>Supervisor</c></tag> + <item><p>Name of the reporting supervisor.</p></item> + <tag><c>Context</c></tag> + <item><p>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> + <c>start_error</c>, <c>child_terminated</c>, or + <c>shutdown_error</c>.</p></item> + <tag><c>Reason</c></tag> + <item><p>Termination reason.</p></item> + <tag><c>Offender</c></tag> + <item><p>Start specification for the child.</p></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> + <p>A progress report is issued when a supervisor starts or + restarts a child. 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> + <tag><c>Supervisor</c></tag> + <item><p>Name of the reporting supervisor.</p></item> + <tag><c>Started</c></tag> + <item><p>Start specification for the successfully + started child.</p></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> + <p>Processes started with functions + <seealso marker="stdlib:proc_lib#spawn/1"><c>proc_lib:spawn</c></seealso> or + <seealso marker="stdlib:proc_lib#spawn_link/1"><c>proc_lib:spawn_link</c></seealso> + are wrapped within a <c>catch</c>. A crash report is issued when such + a process terminates with an unexpected reason, which is any reason + other than <c>normal</c>, <c>shutdown</c>, or <c>{shutdown,Term}</c>. + Processes using behaviors + <seealso marker="stdlib:gen_server"><c>gen_server</c></seealso>, + <seealso marker="stdlib:gen_fsm"><c>gen_fsm</c></seealso> or + <seealso marker="stdlib:gen_statem"><c>gen_statem</c></seealso> + 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 + <tag><c>Crasher</c></tag> + <item><p>Information about the crashing process, such + as initial function call, exit reason, and message queue.</p></item> + <tag><c>Neighbours</c></tag> + <item><p>Information about processes that are linked to the crashing process and do not trap exits. These processes are the - neighbours which will terminate because of this process + neighbours that terminate because of this process crash. The information gathered is the same as the information - for Crasher, shown in the previous item.</item> + for Crasher, described in the previous item.</p></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 + <title>Example</title> + <p>The following example shows the reports generated + when a process crashes. The example process is a <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 + generated, as the process was started using function + <seealso marker="stdlib:proc_lib#spawn/3"><c>proc_lib:spawn/3</c></seealso>. + The supervisor generates a + supervisor report showing the crashed process. A progress report is generated when the process is finally - re-started.</p> + restarted.</p> <pre> =ERROR REPORT==== 27-May-1996::13:38:56 === <0.63.0>: Divide by zero ! @@ -146,7 +151,6 @@ {shutdown,200}, {child_type,worker}] - =PROGRESS REPORT==== 27-May-1996::13:38:56 === Supervisor: {local,test_sup} Started: [{pid,<0.64.0>}, @@ -154,64 +158,66 @@ {mfa,{test,t,[]}}, {restart_type,permanent}, {shutdown,200}, - {child_type,worker}] - </pre> + {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 + <p>Multi-file error report logging is used to store error messages + received by <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 + specified number of kilobytes. No more than a specified number + of files exist at the same time. The logging is very fast, as 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> + <p>For more details, see the + <seealso marker="sasl_app"><c>sasl(6)</c></seealso> + application in the Reference Manual.</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>log_mf_h</c> defined in - <c>stdlib</c>.</p> + written by the error logger handler + <seealso marker="stdlib:log_mf_h"><c>log_mf_h</c></seealso> + defined in STDLIB.</p> <p>The <c>log_mf_h</c> handler writes all reports to a - report logging directory. This directory is specified when + report logging directory, which 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 + used offline, the reports can be copied to another directory + 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> + <title>Starting Report Browser</title> + <p>Start the <c>rb_server</c> with function + <seealso marker="rb#start/1"><c>rb:start([Options])</c></seealso> + as shown in the following example:</p> <pre> - - 5><input>rb:start([{max, 20}]).</input> + 5> <input>rb:start([{max, 20}]).</input> rb: reading report...done. rb: reading report...done. rb: reading report...done. rb: reading report...done. - </pre> + {ok,<0.199.0>}</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> + <title>Online Help</title> + <p>Enter command + <seealso marker="rb#help/0"><c>rb:help()</c></seealso> + to access the report browser online help system.</p> </section> <section> - <title>List Reports in the Server</title> - <p>The function <c>rb:list()</c> lists all loaded reports:</p> + <title>List Reports in Server</title> + <p>Use function + <seealso marker="rb#list/0"><c>rb:list()</c></seealso> + to list all loaded reports:</p> <pre> - - 4><input>rb:list().</input> + 4> <input>rb:list().</input> No Type Process Date Time == ==== ======= ==== ==== 20 progress <0.17.0> 1996-10-16 16:14:54 @@ -234,17 +240,15 @@ 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> + 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> + <p>Use function + <seealso marker="rb#show/1"><c>rb:show(Number)</c></seealso> + to show details of a specific report:</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 @@ -259,7 +263,7 @@ started {child_type,worker}] ok -8> rb:show(9). +8> <input>rb:show(9).</input> CRASH REPORT <0.24.0> 1996-10-16 16:16:21 =============================================================================== @@ -287,19 +291,17 @@ heap_size 610 stack_size 142 reductions 54 -ok - </pre> +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> + <title>Search Reports</title> + <p>All reports containing a common pattern can be shown. + Suppose a process crashes because it tries to call a + non-existing function <c>release_handler:mbj_func/1</c>. + The reports can then be shown as follows:</p> <pre> - -12><input>rb:grep("mbj_func").</input> +12> <input>rb:grep("mbj_func").</input> Found match in report number 11 ERROR REPORT <0.24.0> 1996-10-16 16:16:21 @@ -368,19 +370,17 @@ restart_type permanent shutdown 2000 child_type worker -ok - </pre> +ok</pre> </section> <section> - <title>Stop the Server</title> - <p>Stop the <c>rb_server</c> with the function - <c>rb:stop()</c>:</p> + <title>Stop Server</title> + <p>Use function + <seealso marker="rb#stop/0"><c>rb:stop()</c></seealso> + to stop the <c>rb_server</c>:</p> <pre> - -13><input>rb:stop().</input> -ok - </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 deleted file mode 100644 index 37feca543f..0000000000 --- a/lib/sasl/doc/src/fascicules.xml +++ /dev/null @@ -1,18 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!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/note.gif b/lib/sasl/doc/src/note.gif Binary files differdeleted file mode 100644 index 6fffe30419..0000000000 --- a/lib/sasl/doc/src/note.gif +++ /dev/null diff --git a/lib/sasl/doc/src/notes.xml b/lib/sasl/doc/src/notes.xml index 36ea42762a..791e9c063a 100644 --- a/lib/sasl/doc/src/notes.xml +++ b/lib/sasl/doc/src/notes.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2004</year><year>2013</year> + <year>2004</year><year>2017</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,6 +31,303 @@ </header> <p>This document describes the changes made to the SASL application.</p> +<section><title>SASL 3.1.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + When upgrading with instruction 'restart_new_emulator', + the generated temporary boot file used 'kernelProcess' + statements from the old release instead of the new + release. This is now corrected.</p> + <p> + This correction is needed for upgrade to OTP-21.</p> + <p> + Own Id: OTP-15017</p> + </item> + </list> + </section> + +</section> + +<section><title>SASL 3.1.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + The Report Browser, rb, could earlier not handle reports + that were not lists, for example generated by + <c>error_logger:info_report({some, tuple})</c>. This term + is allowed as input to error_logger, but rb would state + that "A report on bad form was encountered". This is now + corrected.</p> + <p> + Own Id: OTP-13906 Aux Id: ERL-261 </p> + </item> + </list> + </section> + +</section> + +<section><title>SASL 3.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + General Unicode improvements.</p> + <p> + Own Id: OTP-14462</p> + </item> + <item> + <p> + Files generated by <c>release_handler</c> and + <c>reltool</c>, which might contain Unicode characters, + are now encoded as UTF-8 and written with format "~tp" or + "~ts". If the file is to be read by + <c>file:consult/1</c>, an encoding comment is added.</p> + <p> + Own Id: OTP-14463</p> + </item> + <item> + <p> + The SASL error logger event handler, + <c>sasl_report_file_h</c>, will now by default open its + log file with encoding UTF-8. This can be overridden when + configuring SASL, see configuration parameter + <c>sasl_error_logger</c> in the SASL reference manual.</p> + <p> + Own Id: OTP-14618</p> + </item> + </list> + </section> + +</section> + +<section><title>SASL 3.0.4</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Documented default values for the 'mod' and + 'start_phases' fields in .app files were not allowed as + actual values in a .app file. This is now corrected.</p> + <p> + Own Id: OTP-14029</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> Miscellaneous updates due to atoms containing + arbitrary Unicode characters. </p> + <p> + Own Id: OTP-14285</p> + </item> + </list> + </section> + +</section> + +<section><title>SASL 3.0.3</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + When both options 'warnings_as_errors' and 'silent' were + given to systools:make_script or systools:make_relup, no + error reason would be returned if warnings occurred. + Instead only the atom 'error' was returned. This is now + corrected.</p> + <p> + Options 'warnings_as_errors' and 'no_warn_sasl' are now + also allowed for systools:make_tar.</p> + <p> + Own Id: OTP-14170</p> + </item> + </list> + </section> + +</section> + +<section><title>SASL 3.0.2</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + <c>code:add_pathsa/1</c> and command line option + <c>-pa</c> both revert the given list of directories when + adding it at the beginning of the code path. This is now + documented.</p> + <p> + Own Id: OTP-13920 Aux Id: ERL-267 </p> + </item> + </list> + </section> + +</section> + +<section><title>SASL 3.0.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Improved dirty scheduler support. A purge of a module can + now be performed without having to wait for completion of + all ongoing dirty NIF calls.</p> + <p> + Note that when enabling support for dirty schedulers, a + new purge strategy will as of ERTS version 8.1 be + enabled. This new strategy is not fully backwards + compatible with the strategy used by default. For more + information see the documentation of <seealso + marker="erts:erlang#check_process_code/3"><c>erlang:check_process_code/3</c></seealso>.</p> + <p> + Own Id: OTP-13808 Aux Id: OTP-13833 </p> + </item> + <item> + <p> + A new purge strategy has been introduced. The new + strategy will by default be disabled during the OTP 19 + release, but will be the only strategy available as of + the OTP 20 release.</p> + <p> + The new strategy is slightly incompatible with the + strategy being used by default in OTP 19. Using the + default strategy, processes holding <c>fun</c>s that + refer to the module being purged either fail a soft + purge, or will be killed during a hard purge. The new + strategy completely ignores <c>fun</c>s. If <c>fun</c>s + referring to the code being purged exist, and are used + after a purge, an exception will be raised upon usage. + That is, the behavior will be exactly the same as the + case when a <c>fun</c> is received by a process after the + purge.</p> + <p> + The new strategy can optionally be enabled when building + OTP during OTP 19, and will automatically be enabled if + the runtime system is built with support for dirty + schedulers.</p> + <p> + For more information see the documentation of <seealso + marker="erts:erlang#check_process_code/3"><c>erlang:check_process_code/3</c></seealso>.</p> + <p> + Own Id: OTP-13833</p> + </item> + </list> + </section> + +</section> + +<section><title>SASL 3.0</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The module 'overload' is removed.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13184</p> + </item> + </list> + </section> + +</section> + +<section><title>SASL 2.7</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + During upgrade, the release_handler collects a list of + supervisor pids in order to list all processes in the + supervisor tree. If one of the supervisors (legitimately) + exits before release_handler can examine it, then + <c>sys:get_status/1</c> would earlier be called with a + dead pid, causing a <c>'noproc'</c> error. This has been + corrected.</p> + <p> + Own Id: OTP-13291</p> + </item> + </list> + </section> + + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + The module <c>overload</c> is deprecated and will be + removed in OTP 19.</p> + <p> + Own Id: OTP-13057</p> + </item> + <item> + <p> + Improve implementation of supervisor child count, making + it faster and more accurate for dynamic processes of a + <c>simple_one_for_one</c> supervisor.</p> + <p> + Own Id: OTP-13290</p> + </item> + </list> + </section> + +</section> + +<section><title>SASL 2.6.1</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + Documentation improvements</p> + <p> + Own Id: OTP-13000</p> + </item> + </list> + </section> + +</section> + +<section><title>SASL 2.6</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>A mechanism for limiting the amount of text that the + built-in error logger events will produce has been + introduced. It is useful for limiting both the size of + log files and the CPU time used to produce them.</p> + <p>This mechanism is experimental in the sense that it + may be changed if it turns out that it does not solve the + problem it is supposed to solve. In that case, there may + be backward incompatible improvements to this + mechanism.</p> + <p>See the documentation for the config parameter + <c>error_logger_format_depth</c> in the Kernel + application for information about how to turn on this + feature.</p> + <p> + Own Id: OTP-12864</p> + </item> + </list> + </section> + +</section> + <section><title>SASL 2.5</title> <section><title>Fixed Bugs and Malfunctions</title> @@ -724,7 +1021,7 @@ <list> <item> <p>Use an infinity timeout in all calls to - <c>gen_server:call()</c> in the <c>sasl</c> + <c>gen_server:call()</c> in the SASL application.</p> <p> Own Id: OTP-8506 Aux Id: seq11509 </p> diff --git a/lib/sasl/doc/src/notes_history.xml b/lib/sasl/doc/src/notes_history.xml index 006a40f3ac..d37c412d85 100644 --- a/lib/sasl/doc/src/notes_history.xml +++ b/lib/sasl/doc/src/notes_history.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>2006</year><year>2013</year> + <year>2006</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> diff --git a/lib/sasl/doc/src/overload.xml b/lib/sasl/doc/src/overload.xml deleted file mode 100644 index 35877220ab..0000000000 --- a/lib/sasl/doc/src/overload.xml +++ /dev/null @@ -1,152 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE erlref SYSTEM "erlref.dtd"> - -<erlref> - <header> - <copyright> - <year>1996</year><year>2013</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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 index bcd345a7c4..659710487e 100644 --- a/lib/sasl/doc/src/part.xml +++ b/lib/sasl/doc/src/part.xml @@ -4,7 +4,7 @@ <part xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -30,8 +30,9 @@ <file>part.xml</file> </header> <description> - <p>The System Architecture Support Libraries, <em>SASL</em>, - provides support for alarm and release handling etc.</p> + <p>The System Architecture Support Libraries SASL application + provides support for alarm handling, release handling, and + related functions.</p> </description> <xi:include href="sasl_intro.xml"/> <xi:include href="error_logging.xml"/> diff --git a/lib/sasl/doc/src/part_notes.xml b/lib/sasl/doc/src/part_notes.xml deleted file mode 100644 index 57f20ece0e..0000000000 --- a/lib/sasl/doc/src/part_notes.xml +++ /dev/null @@ -1,39 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE part SYSTEM "part.dtd"> - -<part xmlns:xi="http://www.w3.org/2001/XInclude"> - <header> - <copyright> - <year>2004</year><year>2013</year> - <holder>Ericsson AB. All Rights Reserved.</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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 deleted file mode 100644 index b2d278e9c4..0000000000 --- a/lib/sasl/doc/src/part_notes_history.xml +++ /dev/null @@ -1,39 +0,0 @@ -<?xml version="1.0" encoding="utf-8" ?> -<!DOCTYPE part SYSTEM "part.dtd"> - -<part> - <header> - <copyright> - <year>2006</year> - <year>2013</year> - <holder>Ericsson AB, All Rights Reserved</holder> - </copyright> - <legalnotice> - Licensed under the Apache License, Version 2.0 (the "License"); - you may not use this file except in compliance with the License. - You may obtain a copy of the License at - - http://www.apache.org/licenses/LICENSE-2.0 - - Unless required by applicable law or agreed to in writing, software - distributed under the License is distributed on an "AS IS" BASIS, - WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. - See the License for the specific language governing permissions 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 index 85252fc088..d5df4fd345 100644 --- a/lib/sasl/doc/src/rb.xml +++ b/lib/sasl/doc/src/rb.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -35,241 +35,252 @@ <module>rb</module> <modulesummary>The Report Browser Tool</modulesummary> <description> - <p>The Report Browser (RB) tool makes it possible to browse and + <p>The Report Browser (RB) tool is used to browse and format error reports written by the error logger handler - <c>log_mf_h</c>. - </p> + <seealso marker="stdlib:log_mf_h"><c>log_mf_h</c></seealso> + in STDLIB.</p> </description> + <funcs> <func> <name>filter(Filters)</name> <name>filter(Filters, Dates)</name> - <fsummary>Filter reports and displays them on the screen</fsummary> + <fsummary>Filters reports and displays them on the screen.</fsummary> <type> <v>Filters = [filter()]</v> - <v>filter() = {Key, Value} | {Key, Value, no} | {Key, RegExp, re} | {Key, RegExp, re, no}</v> + <v>filter() = {Key, Value} | {Key, Value, no} | {Key, RegExp, re} | + {Key, RegExp, re, no}</v> <v>Key = term()</v> <v>Value = term()</v> - <v>RegExp = string() | {string, Options} | mp(), {mp(), Options}</v> + <v>RegExp = string() | {string(), Options} | re:mp() | {re:mp(), Options}</v> <v>Dates = {DateFrom, DateTo} | {DateFrom, from} | {DateTo, to}</v> - <v>DateFrom = DateTo = {date(), time()}</v> - <v>date() and time() are the same type as in the <c>calendar</c> module</v> + <v>DateFrom = DateTo = calendar:datetime()</v> </type> <desc> - <p>This function displays the reports that match the provided filters.</p> - <p> - When a filter includes the <c>no</c> atom it will exclude the reports that match - that filter. - </p> - <p> - The reports are matched using the <c>proplists</c> module. The report must be a proplist - to be matched against any of the <c>filters()</c>. - </p> - <p> - If the filter is of the form <c>{Key, RegExp, re}</c> the report must contain an element with - <c>key = Key</c> and <c>Value</c> must match the RegExp regular expression. - </p> - <p> - If the Dates parameter is provided, then the reports are filtered according to the date - when they occurred. If Dates is of the form <c>{DateFrom, from}</c> then reports that occurred - after DateFrom are displayed. - </p> - <p> - If Dates is of the form <c>{DateTo, to}</c> then reports that occurred before DateTo - are displayed. - </p> - <p> - If two Dates are provided, then reports that occurred between those dates are returned. - </p> - <p> - If you only want to filter only by dates, then you can provide the empty list as the Filters - parameter. - </p> - <p> - See <c>rb:grep/1</c> for more information on the RegExp parameter. - </p> + <p>Displays the reports that match the provided filters.</p> + <p>When a filter includes the <c>no</c> atom, it excludes the + reports that match that filter.</p> + <p>The reports are matched using the + <seealso marker="stdlib:proplists"><c>proplists</c></seealso> + module in STDLIB. The report must be a proplist + to be matched against any of the filters.</p> + <p>If the filter has the form <c>{Key, RegExp, re}</c>, the + report must contain an element with key equal to <c>Key</c> and + the value must match the regular expression <c>RegExp</c>.</p> + <p>If parameter <c>Dates</c> is specified, the reports are filtered + according to the date when they occurred. If <c>Dates</c> has + the form <c>{DateFrom, from}</c>, reports that occurred after + <c>DateFrom</c> are displayed.</p> + <p>If <c>Dates</c> has the form <c>{DateTo, to}</c>, reports that + occurred before <c>DateTo</c> are displayed.</p> + <p>If two <c>Dates</c> are specified, reports that occurred between + those dates are returned.</p> + <p>To filter only by dates, specify the empty list as the <c>Filters</c> + parameter.</p> + <p>For details about parameter <c>RegExp</c>, see <c>rb:grep/1</c>.</p> + <p>For details about data type <c>mp()</c>, see + <seealso marker="stdlib:re#type-mp"><c>re:mp()</c></seealso>.</p> + <p>For details about data type <c>datetime()</c>, see + <seealso marker="stdlib:calendar#type-datetime"><c>calendar:datetime()</c></seealso>.</p> </desc> </func> + <func> <name>grep(RegExp)</name> - <fsummary>Search the reports for a regular expression</fsummary> + <fsummary>Searches the reports for a regular expression.</fsummary> <type> - <v>RegExp = string() | {string, Options} | mp(), {mp(), Options}</v> + <v>RegExp = string() | {string(), Options} | re:mp() | {re:mp(), Options}</v> </type> <desc> - <p>All reports containing the regular expression <c>RegExp</c> - are printed. - </p> - <p><c>RegExp</c> can be a string containing the regular - expression; a tuple with the string and the options for - compilation; a compiled regular expression; a compiled - regular expression and the options for running it. - Refer to the module <c>re</c> and specially the function <c>re:run/3</c> - for a definition of valid regular expressions and options. - </p> + <p>All reports matching the regular expression <c>RegExp</c> + are displayed. <c>RegExp</c> can be any of the following:</p> + <list type="bulleted"> + <item>A string containing the regular expression</item> + <item>A tuple with the string and the options for compilation</item> + <item>A compiled regular expression</item> + <item>A compiled regular expression and the options for running it</item> + </list> + <p>For a definition of valid regular expressions and options, see + the <seealso marker="stdlib:re"><c>re</c></seealso> module in + STDLIB and in particular function <c>re:run/3</c>.</p> + <p>For details about data type <c>mp()</c>, see + <seealso marker="stdlib:re#type-mp"><c>re:mp()</c></seealso>.</p> </desc> </func> + <func> <name>h()</name> <name>help()</name> - <fsummary>Print help information</fsummary> + <fsummary>Displays help information.</fsummary> <desc> - <p>Prints the on-line help information. - </p> + <p>Displays online help information.</p> </desc> </func> + <func> <name>list()</name> <name>list(Type)</name> - <fsummary>List all reports</fsummary> + <fsummary>Lists all reports.</fsummary> <type> <v>Type = type()</v> <v>type() = error | error_report | info_msg | info_report | - warning_msg | warning_report | crash_report | - supervisor_report | progress</v> + warning_msg | warning_report | crash_report | + supervisor_report | progress</v> </type> <desc> - <p>This function lists all reports loaded in the + <p>Lists all reports loaded in <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> + can be used as a reference to the report in function + <seealso marker="#show/1"><c>show/1</c></seealso>.</p> + <p>If no <c>Type</c> is specified, all reports are listed.</p> </desc> </func> + <func> <name>log_list()</name> <name>log_list(Type)</name> - <fsummary>Log reports list</fsummary> + <fsummary>Logs report lists.</fsummary> <type> <v>Type = type()</v> <v>type() = error | error_report | info_msg | info_report | - warning_msg | warning_report | crash_report | - supervisor_report | progress</v> + warning_msg | warning_report | crash_report | + supervisor_report | progress</v> </type> <desc> - <p>Same as <c>list/0</c> or <c>list/1</c> functions - but result is printed to logfile, if set, otherwise to standard_io. - </p> - <p>If no <c>Type</c> is given, all reports are listed. - </p> + <p>Same as functions + <seealso marker="#list/0"><c>list/0</c></seealso> or + <seealso marker="#list/1"><c>list/1</c></seealso>, + but the result is printed to a log file, if set; otherwise + to <c>standard_io</c>.</p> + <p>If no <c>Type</c> is specified, all reports are listed.</p> </desc> </func> + <func> <name>rescan()</name> <name>rescan(Options)</name> - <fsummary>Rescan the report directory</fsummary> + <fsummary>Rescans 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> + for function + <seealso marker="#start/1"><c>start/1</c></seealso>.</p> </desc> </func> + <func> <name>show()</name> <name>show(Report)</name> - <fsummary>Show reports</fsummary> + <fsummary>Displays reports.</fsummary> <type> - <v>Report = int() | type()</v> + <v>Report = integer() | 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> + <p>If argument <c>type</c> is specified, all loaded reports of this + type are displayed. If an integer argument is specified, the + report with this reference number is displayed. If no argument + is specified, all reports are displayed.</p> </desc> </func> + <func> <name>start()</name> <name>start(Options)</name> - <fsummary>Start the RB server</fsummary> + <fsummary>Starts the <c>rb_server</c>.</fsummary> <type> <v>Options = [opt()]</v> - <v>opt() = {start_log, FileName} | {max, MaxNoOfReports} | {report_dir, DirString} | {type, ReportType} | {abort_on_error, Bool}</v> + <v>opt() = {start_log, FileName} | {max, MaxNoOfReports} | + {report_dir, DirString} | {type, ReportType} | + {abort_on_error, Bool}</v> <v>FileName = string() | atom() | pid()</v> - <v>MaxNoOfReports = int() | all</v> + <v>MaxNoOfReports = integer() | all</v> <v>DirString = string()</v> <v>ReportType = type() | [type()] | all</v> - <v>Bool = true | false</v> + <v>Bool = boolean()</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 + <p>Function <c>start/1</c> starts <c>rb_server</c> with the + specified options, whereas function <c>start/0</c> starts with + default options. <c>rb_server</c> must be started before + reports can be browsed. When <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, - registered name or io_device. All reports will be printed - to the named file. The default is <c>standard_io</c>. - The option {start_log, standard_error} is not allowed and - will be replaced by default standard_io. - </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> + started.</p> + <p><em>Options:</em></p> + <taglist> + <tag><c>{start_log, FileName}</c></tag> + <item><p>Starts logging to file, + registered name, or <c>io_device</c>. All reports are printed + to the specified destination. Default is <c>standard_io</c>. + Option <c>{start_log, standard_error}</c> is not allowed and + will be replaced by default <c>standard_io</c>.</p></item> + <tag><c>{max, MaxNoOfReports}</c></tag> + <item><p>Controls how many reports + <c>rb_server</c> is to read at startup. This option is + useful, as the directory can contain a large amount of reports. If this + option is specified, the <c>MaxNoOfReports</c> latest reports + are read. Default is <c>all</c>.</p></item> + <tag><c>{report_dir, DirString}</c></tag> + <item><p>Defines the directory where + the error log files are located. Default is + the directory specified by application environment + variable <c>error_logger_mf_dir</c>, + see <seealso marker="sasl_app">sasl(6)</seealso>.</p></item> + <tag><c>{type, ReportType}</c></tag> + <item><p>Controls what kind of reports + <c>rb_server</c> is to read at startup. <c>ReportType</c> + is a supported type, <c>all</c>, or a list of supported + types. Default is <c>all</c>.</p></item> + <tag><c>{abort_on_error, Bool}</c></tag> + <item><p>Specifies if + logging is to be ended if <c>rb</c> encounters an unprintable + report. (You can get a report with an incorrect form if function + <c>error_logger</c>, <c>error_msg</c>, or + <c>info_msg</c> has been called with an invalid format string)</p> + <list type="bulleted"> + <item>If <c>Bool</c> is <c>true</c>, <c>rb</c> stops logging + (and prints an error message to <c>stdout</c>) if it encounters + a badly formatted report. If logging to file is enabled, an + error message is appended to the log file as well.</item> + <item>If <c>Bool</c> is <c>false</c> (the default value), <c>rb</c> + prints an error message to <c>stdout</c> for every bad report it + encounters, but the logging process is never ended. All printable + reports are written. If logging to file is enabled, <c>rb</c> prints + <c>* UNPRINTABLE REPORT *</c> in the log file at the location of an + unprintable report.</item> + </list></item> + </taglist> </desc> </func> + <func> <name>start_log(FileName)</name> - <fsummary>Redirect all output to <c>FileName</c></fsummary> + <fsummary>Redirects all output to <c>FileName</c>.</fsummary> <type> <v>FileName = string() | atom() | pid()</v> </type> <desc> <p>Redirects all report output from the RB tool to the - specified file, registered name or io_device. - </p> + specified file, registered name, or <c>io_device</c>.</p> </desc> </func> + <func> <name>stop()</name> - <fsummary>Stop the RB server</fsummary> + <fsummary>Stops the <c>rb_server</c>.</fsummary> <desc> - <p>Stops the <c>rb_server</c>. - </p> + <p>Stops <c>rb_server</c>.</p> </desc> </func> + <func> <name>stop_log()</name> - <fsummary>Stop logging to file</fsummary> + <fsummary>Stops 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> + <p>Closes the log file. The output from the RB tool is + directed to <c>standard_io</c>.</p> </desc> </func> </funcs> diff --git a/lib/sasl/doc/src/ref_man.xml b/lib/sasl/doc/src/ref_man.xml index 2b608c7c51..78cf1eb26e 100644 --- a/lib/sasl/doc/src/ref_man.xml +++ b/lib/sasl/doc/src/ref_man.xml @@ -4,7 +4,7 @@ <application xmlns:xi="http://www.w3.org/2001/XInclude"> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -30,12 +30,11 @@ <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> + <p>The SASL application provides support for alarm handling, + release handling, and related functions.</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"/> diff --git a/lib/sasl/doc/src/rel.xml b/lib/sasl/doc/src/rel.xml index a16db24295..9356b2cd47 100644 --- a/lib/sasl/doc/src/rel.xml +++ b/lib/sasl/doc/src/rel.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1997</year> - <year>2013</year> + <year>2016</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -33,74 +33,65 @@ <file>rel</file> <filesummary>Release resource file</filesummary> <description> - <p>The <em>release resource file</em> specifies which applications are + <p>The <em>release resource file</em> specifies which applications 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> + <p>This file is used by the functions in + <seealso marker="systools"><c>systools</c></seealso> + 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> + <title>File Syntax</title> + <p>The release resource file is to 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 + 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 + {Application, AppVsn, Type, IncApps}]}.</code> + <taglist> + <tag><c>RelName = string()</c></tag> + <item><p>Release name.</p></item> + <tag><c>Vsn = string()</c></tag> + <item><p>Release version.</p></item> + <tag><c>EVsn = string()</c></tag> + <item><p>ERTS version the release is intended for.</p></item> + <tag><c>Application = atom()</c></tag> + <item><p>Name of an application included in the release.</p></item> + <tag><c>AppVsn = string()</c></tag> + <item><p>Version of an application included in the release.</p></item> + <tag><c>Type = permanent | transient | temporary | load | none</c></tag> + <item><p>Start type of an application included in the release.</p> + <p>If <c>Type = permanent | transient | temporary</c>, the + application is loaded and started in the corresponding way, see + <seealso marker="kernel:application"><c>application(3)</c></seealso>.</p> + <p>If <c>Type = load</c>, the application is only loaded.</p> + <p>If <c>Type = none</c>, the application is not loaded and not + started, although the code for its modules is loaded.</p> + <p>Defaults to <c>permanent</c></p></item> + <tag><c>IncApps = [atom()]</c></tag> + <item><p>A list of applications that are included by an application + included in the release. 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 same value as in the application resource file.</p> - </item> - </list> + to the same value as in the application resource file.</p></item> + </taglist> <note> - <p>The list of applications must contain the <c>kernel</c> and - <c>stdlib</c> applications.</p> + <p>The list of applications must contain the Kernel and + STDLIB applications.</p> </note> </section> <section> - <title>SEE ALSO</title> - <p>application(3), relup(4), systools(3)</p> + <title>See Also</title> + <p><seealso marker="kernel:application"><c>application(3)</c></seealso>, + <seealso marker="relup"><c>relup(4)</c></seealso>, + <seealso marker="systools"><c>systools(3)</c></seealso></p> </section> </fileref> diff --git a/lib/sasl/doc/src/release_handler.xml b/lib/sasl/doc/src/release_handler.xml index 692159d7bf..8f073807fb 100644 --- a/lib/sasl/doc/src/release_handler.xml +++ b/lib/sasl/doc/src/release_handler.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,109 +31,115 @@ <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>, + <p>The <em>release handler</em> process belongs 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>An introduction to release handling and an example is provided in + <seealso marker="doc/design_principles:release_handling">OTP Design + Principles</seealso> in <em>System Documentation</em>.</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 + <seealso marker="systools#make_tar/1"><c>systools:make_tar/1,2</c></seealso>. + The release package is to be located 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>. + <seealso marker="kernel:code#root_dir/0"><c>code:root_dir()</c></seealso>. Another <c>releases</c> directory can be specified using the SASL - configuration parameter <c>releases_dir</c>, or the OS environment + 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. + to this directory 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>A release package is always to contain:</p> + <list type="bulleted"> + <item>A release resource file, <c>Name.rel</c></item> + <item>A boot script, <c>Name.boot</c></item> + </list> + <p>The <c>.rel</c> file contains information about the release: its name, + version, and which ERTS and application versions it uses.</p> + <p>A release package can also contain:</p> + <list type="bulleted"> + <item>A release upgrade file, <c>relup</c></item> + <item>A system configuration file, <c>sys.config</c></item> + </list> + <p>The <c>relup</c> file contains instructions 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 + in the <c>relup</c> file. An installed release can be made + <em>permanent</em>. Only one permanent release can exist in + the system, and this release 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 + belonging to that release only are deleted.</p> + <p>Each release version has a status, which 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> + 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 meaning of the status values are + illustrated in the following table:</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> + 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 + installation can be synchronized between nodes. From an operator + view, it can 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 + nodes there are. It is recommended that + software management functions are written that take care of + this problem. Such a function can 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 + <p>For release handling to work properly, the runtime system must + know which release it is running. It + must also be able to change (in runtime) which boot script and + system configuration file are to 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>The installation of a new release may restart the system. Which + started as an embedded system. Read about this in + <seealso marker="doc/embedded:users_guide">Embedded System</seealso> in + <em>System Documentation</em>. In this case, the system + configuration file <c>sys.config</c> is mandatory.</p> + <p>The installation of a new release can restart the system. Which program to use is specified by the SASL configuration - parameter <c>start_prg</c> which defaults + 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 version of - the release. The release handler furthermore expects that a + Furthermore, the release handler expects that the service is named + <c>NodeName</c>_<c>Release</c>, where <c>NodeName</c> is + the first part of the Erlang node name (up to, but not including + the "@") and <c>Release</c> is the current release version. + 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 + <c>erlsrv</c>. During upgrading with restart, a new service + is registered and started. The new service is set to + automatic and the old service is removed when the new release is made permanent.</p> - <p>The release handler at a node which runs on a diskless machine, + <p>The release handler at a node running 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> + using the following SASL configuration parameters (for + details, see <seealso marker="sasl_app">sasl(6)</seealso>):</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 + <p>This node uses some master nodes to store + and fetch release information. All master nodes must be + operational whenever release information is written by this node.</p> </item> <tag><c>client_directory</c></tag> @@ -145,24 +151,25 @@ old reboot_old permanent <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 + emulator cannot dynamically switch to a new emulator, as the executable files are statically written into memory.</p> </item> </taglist> - <p>It is also possible to use the release handler to unpack and + <p>The release handler can also be used 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 + system. However, in this case the user must somehow ensure 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 + the system must be restarted.</p> + <p>Functions are provided 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> <name>check_install_release(Vsn,Opts) -> {ok, OtherVsn, Descr} | {error, Reason}</name> - <fsummary>Check installation of a release in the system.</fsummary> + <fsummary>Checks installation of a release in the system.</fsummary> <type> <v>Vsn = OtherVsn = string()</v> <v>Opts = [Opt]</v> @@ -173,27 +180,29 @@ old reboot_old permanent <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, + <c>current</c>. Issues warnings if <c>relup</c> file or + <c>sys.config</c> is not present. If <c>relup</c> file 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 + applications are present and that all new code can be loaded; + <c>{error,Reason}</c> is returned if an error is found.</p> + <p>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> - <p>If the option <c>purge</c> is given, all old code that can - be soft purged will be purged after all other checks are - successfully completed. This can be useful in order to + <p>Returns the same as + <seealso marker="#install_release/1"><c>install_release/1</c></seealso>. + <c>Descr</c> defaults to "" if no <c>relup</c> file is found.</p> + <p>If option <c>purge</c> is specified, all old code that can + be soft-purged is purged after all other checks are + successfully completed. This can be useful to reduce the time needed by <seealso - marker="#install_release/1">install_release</seealso>.</p> + marker="#install_release/1"><c>install_release/1</c></seealso>.</p> </desc> </func> + <func> <name>create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}</name> - <fsummary>Create an initial RELEASES file.</fsummary> + <fsummary>Creates an initial <c>RELEASES</c> file.</fsummary> <type> <v>Root = RelDir = RelFile = string()</v> <v>AppDirs = [{App, Vsn, Dir}]</v> @@ -202,52 +211,55 @@ old reboot_old permanent <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 + <p>Creates an initial <c>RELEASES</c> file to be used by the + release handler. This file must exist 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 + described earlier. <c>RelDir</c> is the directory where + the <c>RELEASES</c> file is to 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 + for the specified applications are to 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 + is located. The corresponding modules are to 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> + <fsummary>Installs 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 + <p>Installs a release-dependent file in the release structure. + The release-dependent file 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> + <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> + are generated at the target. The function is to be called after + <seealso marker="#set_unpacked/2"><c>set_unpacked/2</c></seealso> + 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} | {continue_after_restart, OtherVsn, Descr} | {error, Reason}</name> - <fsummary>Install a release in the system.</fsummary> + <fsummary>Installs 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> Timeout = default | infinity | pos_integer()</v> <v> Bool = boolean()</v> <v>Descr = term()</v> <v>Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | {missing_base_app, OtherVsn, App} | {could_not_create_hybrid_boot, term()} | term()</v> @@ -262,7 +274,7 @@ old reboot_old permanent 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 application 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, @@ -271,101 +283,120 @@ old reboot_old permanent <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 <c>{continue_after_restart,OtherVsn,Descr}</c> is - returned, it means that the emulator will be restarted - before the upgrade instructions are executed. This will - happen if the emulator or any of the applications kernel, - stdlib or sasl are updated. The new version of the emulator - and these core applications will execute after the restart, - but for all other applications the old versions will be - started and the upgrade will be performed as normal by + <p>If <c>{continue_after_restart,OtherVsn,Descr}</c> is + returned, the emulator is restarted + before the upgrade instructions are executed. This + occurs if the emulator or any of the applications + Kernel, STDLIB, or SASL + are updated. The new emulator version + and these core applications execute after the restart. + For all other applications the old versions are + started and the upgrade is performed as normal by executing the upgrade instructions.</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"> + <p><em>Options</em>:</p> + <taglist> + <tag><c>error_action</c></tag> + <item><p>Defines if the node is to be + restarted + (<seealso marker="erts:init#restart/0"><c>init:restart()</c></seealso>) + or rebooted + (<seealso marker="erts:init#reboot/0"><c>init:reboot()</c></seealso>) + if there is an error during + the installation. Default is <c>restart</c>.</p></item> + <tag><c>code_change_timeout</c></tag> + <item><p>Defines the time-out + for all calls to + <seealso marker="stdlib:sys#change_code/4"><c>sys:change_code</c></seealso>. + If no value is specified or <c>default</c> is specified, the + default value defined in <c>sys</c> is used.</p></item> + <tag><c>suspend_timeout</c></tag> + <item><p>Defines the time-out for + all calls to + <seealso marker="stdlib:sys#suspend/1"><c>sys:suspend</c></seealso>. + 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></item> + <tag><c>{update_paths,Bool}</c></tag> + <item><p>Indicates if all + application code paths are to be updated (<c>Bool==true</c>) + or if only code paths for modified applications are to be + updated (<c>Bool==false</c>, default). This option has only + effect for other application directories than the default + <c>$ROOT/lib/App-Vsn</c>, that is, application directories + specified in argument <c>AppDirs</c> in a call to + <seealso marker="#create_RELEASES/4"><c>create_RELEASES/4</c></seealso> or + <seealso marker="#set_unpacked/2"><c>set_unpacked/2</c></seealso>.</p> + <p><em>Example:</em></p> + <p>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 as follows:</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> +=> {ok,NewVsn}</code> + <p>If <c>NewVsn</c> is installed with option + <c>{update_paths,true}</c>, then + <seealso marker="kernel:code#lib_dir/1"><c>code:lib_dir(myapp)</c></seealso> + returns <c>/home/user/myapp-1.0</c>.</p></item> + </taglist> <note> - <p>Installing a new release might be quite time consuming if + <p>Installing a new release can be time consuming if there are many processes in the system. The reason is that each process must be checked for references to old code - before a module can be purged. This check might lead to + before a module can be purged. This check can lead to garbage collections and copying of data.</p> - <p>If you wish to speed up the execution of - <c>install_release</c>, then you may call <seealso - marker="#check_install_release/1">check_install_release</seealso> - first, using the option <c>purge</c>. This will do the same - check for old code, and then purge all modules that can be - soft purged. The purged modules will then no longer have any - old code, and <c>install_release</c> will not need to do the + <p>To speed up the execution of + <seealso marker="#install_release/1"><c>install_release</c></seealso>, + first call <seealso + marker="#check_install_release/1"><c>check_install_release</c></seealso>, + using option <c>purge</c>. This does the same + check for old code. Then purges all modules that can be + soft-purged. The purged modules do then no longer have any + old code, and + <seealso marker="#install_release/1"><c>install_release</c></seealso> + does not need to do the checks.</p> - <p>Obviously, this will not reduce the overall time for the - upgrade, but it will allow checks and purge to be executed + <p>This does not reduce the overall time for the + upgrade, but it allows checks and purge to be executed in the background before the real upgrade is started.</p> </note> <note> <p>When upgrading the emulator from a version older than OTP - R15, there will be an attempt to load new application beam - code into the old emulator. In some cases, the new beam - format can not be read by the old emulator, and so the code - loading will fail and terminate the complete upgrade. To - overcome this problem, the new application code should be - compiled with the old emulator. See <seealso - marker="doc/design_principles:appup_cookbook">Design - Principles</seealso> for more information about emulator - upgrade from pre OTP R15 versions.</p> + R15, an attempt is made to load new application beam + code into the old emulator. Sometimes the new beam + format cannot be read by the old emulator, so the code + loading fails and the complete upgrade is terminated. To + overcome this problem, the new application code is to be + compiled with the old emulator. For more information about + emulator upgrade from pre OTP R15 versions, see + <seealso marker="doc/design_principles:appup_cookbook">Design + Principles</seealso> in <em>System Documentation</em>.</p> </note> </desc> </func> + <func> <name>make_permanent(Vsn) -> ok | {error, Reason}</name> - <fsummary>Make the specified release version permanent.</fsummary> + <fsummary>Makes 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 + <p>Makes the specified release version <c>Vsn</c> permanent.</p> </desc> </func> + <func> <name>remove_release(Vsn) -> ok | {error, Reason}</name> - <fsummary>Remove a release from the system.</fsummary> + <fsummary>Removes a release from the system.</fsummary> <type> <v>Vsn = string()</v> <v>Reason = {permanent, Vsn} | client_node | term()</v> @@ -375,23 +406,26 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). 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> + <fsummary>Reboots 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> + calls + <seealso marker="erts:init#reboot/0"><c>init:reboot()</c></seealso> + 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> + <fsummary>Marks a release as removed.</fsummary> <type> <v>Vsn = string()</v> <v>Reason = {permanent, Vsn} | term()</v> @@ -403,9 +437,10 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). 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> + <fsummary>Marks a release as unpacked.</fsummary> <type> <v>RelFile = string()</v> <v>AppDirs = [{App, Vsn, Dir}]</v> @@ -419,18 +454,19 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). 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 + for the specified applications are to 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 + is located. The corresponding modules are to 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> + <fsummary>Unpacks a release package.</fsummary> <type> <v>Name = Vsn = string()</v> <v>Reason = client_node | term()</v> @@ -438,14 +474,15 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). <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 + <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> + <fsummary>Returns all known releases.</fsummary> <type> <v>Name = Vsn = string()</v> <v>Apps = ["App-Vsn"]</v> @@ -455,16 +492,18 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). <p>Returns all releases known to the release handler.</p> </desc> </func> + <func> <name>which_releases(Status) -> [{Name, Vsn, Apps, Status}]</name> - <fsummary>Return all known releases of a specific status</fsummary> + <fsummary>Returns all known releases of a specific status.</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 of a specific status.</p> + <p>Returns all releases, known to the release handler, of a + specific status.</p> </desc> </func> </funcs> @@ -473,7 +512,8 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). <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 + release). A script corresponding to the instructions in the + <c>relup</c> file 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> @@ -482,20 +522,22 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). 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 + <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>, + as this causes the <c>release_handler</c> to end up in an inconsistent state.</p> - <p>No persistent information is updated, why these functions can + <p>No persistent information is updated, so these functions can be used on any Erlang node, embedded or not. Also, using these - functions does not affect which code will be loaded in case of + functions does not affect which code is loaded if there is a reboot.</p> - <p>If the upgrade or downgrade fails, the application may end up + <p>If the upgrade or downgrade fails, the application can end up in an inconsistent state.</p> </warning> </section> + <funcs> <func> <name>upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name> - <fsummary>Upgrade to a new application version</fsummary> + <fsummary>Upgrades to a new application version.</fsummary> <type> <v>App = atom()</v> <v>Dir = string()</v> @@ -506,39 +548,46 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). <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> + the <c>.appup</c> file.</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 + <c>App</c>. The corresponding modules as well as + the <c>.app</c> and <c>.appup</c> files are to 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>. + <seealso marker="#upgrade_script/2"><c>upgrade_script/2</c></seealso>. This script is evaluated using - <seealso marker="#eval_appup_script/4">eval_appup_script/4</seealso>, + <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></seealso>, exactly in the same way as - <seealso marker="#install_release/1">install_release/1,2</seealso> + <seealso marker="#install_release/1"><c>install_release/1,2</c></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_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> + <p>Returns one of the following:</p> + <list type="bulleted"> + <item><c>{ok, Unpurged}</c> if evaluating the script is + successful, where <c>Unpurged</c> is a list of unpurged + modules</item> + <item><c>restart_emulator</c> if this instruction is + encountered in the script</item> + <item><c>{error, Reason}</c> if an error occurred when + finding or evaluating the script</item> + </list> <p>If the <c>restart_new_emulator</c> instruction is found in - the script, <c>upgrade_app/2</c> will return - <c>{error,restart_new_emulator}</c>. The reason for this is - that this instruction requires that a new version of the - emulator is started before the rest of the upgrade - instructions can be executed, and this can only be done by - <c>install_release/1,2</c>.</p> + the script, + <seealso marker="#upgrade_app/2"><c>upgrade_app/2</c></seealso> + returns <c>{error,restart_new_emulator}</c>. This because + <c>restart_new_emulator</c> requires a new version of the + emulator to be started before the rest of the upgrade + instructions can be executed, and this can only be done by + <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>.</p> </desc> </func> + <func> <name>downgrade_app(App, Dir) -></name> <name>downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name> - <fsummary>Downgrade to a previous application version</fsummary> + <fsummary>Downgrades to a previous application version.</fsummary> <type> <v>App = atom()</v> <v>Dir = OldVsn = string()</v> @@ -549,110 +598,124 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). <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> + <c>Dir</c> according to the <c>.appup</c> file.</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 + started. <c>OldVsn</c> is the previous application version + 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 + directory of the previous version of <c>App</c>. + The corresponding modules and the old <c>.app</c> file + are to be located under <c>Dir/ebin</c>. The <c>.appup</c> + file is to 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> + (<seealso marker="kernel:code#lib_dir/1"><c>code:lib_dir(App)</c></seealso>).</p> <p>The function looks in the <c>.appup</c> file and tries to - find an downgrade script to the previous version of + find a downgrade script to the previous version of the application using - <seealso marker="#downgrade_script/3">downgrade_script/3</seealso>. + <seealso marker="#downgrade_script/3"><c>downgrade_script/3</c></seealso>. This script is evaluated using - <seealso marker="#eval_appup_script/4">eval_appup_script/4</seealso>, + <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></seealso>, exactly in the same way as - <seealso marker="#install_release/1">install_release/1,2</seealso> + <seealso marker="#install_release/1"><c>install_release/1,2</c></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_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> + <p>Returns one of the following:</p> + <list type="bulleted"> + <item><c>{ok, Unpurged}</c> if evaluating the script is + successful, where <c>Unpurged</c> is a list of unpurged + modules</item> + <item><c>restart_emulator</c> if this instruction is + encountered in the script</item> + <item><c>{error, Reason}</c> if an error occurred when + finding or evaluating the script</item> + </list> </desc> </func> + <func> <name>upgrade_script(App, Dir) -> {ok, NewVsn, Script}</name> - <fsummary>Find an application upgrade script</fsummary> + <fsummary>Finds 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> + <v>Script = Instructions</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>. + <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></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> + <seealso marker="#upgrade_app/2"><c>upgrade_app/2</c></seealso> + instead, but this function (<c>upgrade_script</c>) is useful + 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 + <c>App</c>. The corresponding modules as well as + the <c>.app</c> and <c>.appup</c> files are to 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> + find an upgrade script from the current application version. + High-level instructions are translated to + low-level instructions. The instructions are sorted in + the same manner as when generating a <c>relup</c> file.</p> <p>Returns <c>{ok, NewVsn, Script}</c> if successful, where - <c>NewVsn</c> is the new application version.</p> + <c>NewVsn</c> is the new application version. + For details about <c>Script</c>, see + <seealso marker="appup"><c>appup(4)</c></seealso>.</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> + <fsummary>Finds an application downgrade script.</fsummary> <type> <v>App = atom()</v> <v>OldVsn = Dir = string()</v> - <v>Script = Instructions -- see appup(4)</v> + <v>Script = Instructions</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>. + <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></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> + <seealso marker="#downgrade_app/2"><c>downgrade_app/2,3</c></seealso> + instead, but this function (<c>downgrade_script</c>) is useful + 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 + <c>App</c>. The corresponding modules and + the old <c>.app</c> file are to be located under + <c>Dir/ebin</c>. The <c>.appup</c> file is to 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> + directory of the application + (<seealso marker="kernel:code#lib_dir/1"><c>code:lib_dir(App)</c>)</seealso>.</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> + find a downgrade script from the current application version. + High-level instructions are translated to + low-level instructions. The instructions are sorted in + the same manner as when generating a <c>relup</c> file.</p> + <p>Returns <c>{ok, Script}</c> if successful. + For details about <c>Script</c>, see + <seealso marker="appup"><c>appup(4)</c></seealso>.</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_emulator | {error, Reason}</name> - <fsummary>Evaluate an application upgrade or downgrade script</fsummary> + <fsummary>Evaluates 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>Script</v> + <d>See <seealso marker="#upgrade_script/2"><c>upgrade_script/2</c></seealso>, <seealso marker="#downgrade_script/3"><c>downgrade_script/3</c></seealso></d> <v>Unpurged = [Module]</v> <v> Module = atom()</v> <v>Reason = term()</v> @@ -660,114 +723,100 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). <desc> <p>Evaluates an application upgrade or downgrade script <c>Script</c>, the result from calling - <seealso marker="#upgrade_app/2">upgrade_script/2</seealso> or - <seealso marker="#downgrade_app/3">downgrade_script/3</seealso>, + <seealso marker="#upgrade_script/2"><c>upgrade_script/2</c></seealso> or + <seealso marker="#downgrade_script/3"><c>downgrade_script/3</c></seealso>, exactly in the same way as - <seealso marker="#install_release/1">install_release/1,2</seealso> + <seealso marker="#install_release/1"><c>install_release/1,2</c></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_emulator</c> if this instruction is - encountered in the script, or <c>{error, Reason}</c> if - an error occurred when evaluating the script.</p> - <p>If the <c>restart_new_emulator</c> instruction is found in - the script, <c>eval_appup_script/4</c> will return - <c>{error,restart_new_emulator}</c>. The reason for this is - that this instruction requires that a new version of the - emulator is started before the rest of the upgrade - instructions can be executed, and this can only be done by - <c>install_release/1,2</c>.</p> + <c>.appup</c> files are to be located under <c>Dir/ebin</c>.</p> + <p>Returns one of the following:</p> + <list type="bulleted"> + <item><c>{ok, Unpurged}</c> if evaluating the script is + successful, where <c>Unpurged</c> is a list of unpurged + modules</item> + <item><c>restart_emulator</c> if this instruction is + encountered in the script</item> + <item><c>{error, Reason}</c> if an error occurred when + finding or evaluating the script</item> + </list> + <p>If the <c>restart_new_emulator</c> instruction is found in + the script, + <seealso marker="#eval_appup_script/4"><c>eval_appup_script/4</c></seealso> + returns <c>{error,restart_new_emulator}</c>. This because + <c>restart_new_emulator</c> requires a new version of the + emulator to be started before the rest of the upgrade + instructions can be executed, and this can only be done by + <seealso marker="#install_release/1"><c>install_release/1,2</c></seealso>.</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> + <taglist> + <tag><c>{bad_masters, Masters}</c></tag> + <item><p>The master nodes <c>Masters</c> are not alive.</p></item> + <tag><c>{bad_rel_file, File}</c></tag> + <item><p>Specified <c>.rel</c> file <c>File</c> cannot be read or + does not contain a single term.</p></item> + <tag><c>{bad_rel_data, Data}</c></tag> + <item><p>Specified <c>.rel</c> file does not contain a recognized + release specification, but another term <c>Data</c>.</p></item> + <tag><c>{bad_relup_file, File}</c></tag> + <item><p>Specified <c>relup</c> file <c>Relup</c> contains bad + data.</p></item> + <tag><c>{cannot_extract_file, Name, Reason}</c></tag> + <item><p>Problems when extracting from a tar file, + <seealso marker="stdlib:erl_tar#extract/2"><c>erl_tar:extract/2</c></seealso> + returned <c>{error, {Name, Reason}}</c>.</p></item> + <tag><c>{existing_release, Vsn}</c></tag> + <item><p>Specified release version <c>Vsn</c> is already + in use.</p></item> + <tag><c>{Master, Reason, When}</c></tag> + <item><p>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> + <tag><c>{no_matching_relup, Vsn, CurrentVsn}</c></tag> + <item><p>Cannot find a script for upgrading/downgrading between + <c>CurrentVsn</c> and <c>Vsn</c>.</p></item> + <tag><c>{no_such_directory, Path}</c></tag> + <item><p>The directory <c>Path</c>does not exist.</p></item> + <tag><c>{no_such_file, Path}</c></tag> + <item><p>The path <c>Path</c> (file or directory) does not + exist.</p></item> + <tag><c>{no_such_file, {Master, Path}}</c></tag> + <item><p>The path <c>Path</c> (file or directory) does not exist at + the master node <c>Master</c>.</p></item> + <tag><c>{no_such_release, Vsn}</c></tag> + <item><p>The specified release version <c>Vsn</c> does not + exist.</p></item> + <tag><c>{not_a_directory, Path}</c></tag> + <item><p><c>Path</c> exists but is not a directory.</p></item> + <tag><c>{Posix, File}</c></tag> + <item><p>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 + <seealso marker="kernel:file"><c>file(3)</c></seealso> + in Kernel.</p></item> + <tag><c>Posix</c></tag> + <item><p>Some file operation failed, as for the previous item in + the list.</p></item> + </taglist> </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> + <title>See Also</title> + <p><seealso marker="doc/design_principles:users_guide">OTP Design Principles</seealso>, + <seealso marker="kernel:config"><c>config(4)</c></seealso>, + <seealso marker="rel"><c>rel(4)</c></seealso>, + <seealso marker="relup"><c>relup(4)</c></seealso>, + <seealso marker="script"><c>script(4)</c></seealso>, + <seealso marker="stdlib:sys"><c>sys(3)</c></seealso>, + <seealso marker="systools"><c>systools(3)</c></seealso></p> </section> </erlref> diff --git a/lib/sasl/doc/src/relup.xml b/lib/sasl/doc/src/relup.xml index 8eecf3fce2..4c5535002c 100644 --- a/lib/sasl/doc/src/relup.xml +++ b/lib/sasl/doc/src/relup.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1997</year> - <year>2013</year> + <year>2016</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -36,59 +36,53 @@ <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 + <seealso marker="systools#make_relup/3"><c>systools:make_relup/3,4</c></seealso>, + 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> + <title>File Syntax</title> + <p>In a target system, the release upgrade file is to be located in + directory <c>$ROOT/releases/Vsn</c>.</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 + [{DownToVsn, Descr, Instructions}, ...]}.</code> + <taglist> + <tag><c>Vsn = string()</c></tag> + <item><p>Current release version.</p></item> + <tag><c>UpFromVsn = string()</c></tag> + <item><p>Earlier version of the release to upgrade from.</p></item> + <tag><c>Descr = term()</c></tag> + <item><p>A user-defined parameter passed + from the function + <seealso marker="systools#make_relup/3"><c>systools:make_relup/3,4</c></seealso>. + It is used in the return value of + <seealso marker="release_handler#install_release/1"><c>release_handler:install_release/1,2</c></seealso>.</p></item> + <tag><c>Instructions</c></tag> + <item><p>A list of low-level release upgrade instructions, see + <seealso marker="appup"><c>appup(4)</c></seealso>. + 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> + as in the start script.</p></item> + <tag><c>DownToVsn = string()</c></tag> + <item><p>Earlier version of the release to downgrade to.</p></item> + </taglist> </section> <section> - <title>SEE ALSO</title> - <p>app(4), appup(4), rel(4), release_handler(3), systools(3)</p> + <title>See Also</title> + <p><seealso marker="kernel:app"><c>app(4)</c></seealso>, + <seealso marker="appup"><c>appup(4)</c></seealso>, + <seealso marker="rel"><c>rel(4)</c></seealso>, + <seealso marker="release_handler"><c>release_handler(3)</c></seealso>, + <seealso marker="systools"><c>systools(3)</c></seealso></p> </section> </fileref> diff --git a/lib/sasl/doc/src/sasl_app.xml b/lib/sasl/doc/src/sasl_app.xml index 7cdb3e2ca7..e0693fcb60 100644 --- a/lib/sasl/doc/src/sasl_app.xml +++ b/lib/sasl/doc/src/sasl_app.xml @@ -4,7 +4,7 @@ <appref> <header> <copyright> - <year>1996</year><year>2013</year> + <year>1996</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -27,27 +27,23 @@ <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> + </header> + <app>sasl</app> + <appsummary>The SASL application</appsummary> + <description> + <p>The SASL application 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> @@ -57,21 +53,35 @@ <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> + <p>Formats and writes <em>supervisor reports</em>, <em>crash + reports</em>, and <em>progress reports</em> to <c>stdio</c>. + This error logger event handler uses + <seealso marker="kernel:kernel_app#error_logger_format_depth">error_logger_format_depth</seealso> + in the Kernel application to limit how much detail is + printed in crash and supervisor reports.</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> + <p>Formats and writes <em>supervisor reports</em>, <em>crash + report</em>, and <em>progress report</em> to a single file. + This error logger event handler uses + <seealso marker="kernel:kernel_app#error_logger_format_depth">error_logger_format_depth</seealso> + in the Kernel application to limit the details + printed in crash and supervisor reports.</p> </item> <tag><c>log_mf_h</c></tag> <item> - <p>This error logger writes <em>all</em> events sent to - the error logger to disk.</p> - <p>To activate this event handler, the following three sasl - configuration parameters must be set: - <c>error_logger_mf_dir</c>, <c>error_logger_mf_maxbytes</c> - and <c>error_logger_mf_maxfiles</c>. See below for more - information about the configuration parameters.</p> + <p>This error logger writes <em>all</em> events sent to the + error logger to disk. Multiple files and log rotation are + used. For efficiency reasons, each event is written as a + binary. For more information about this handler, + see <seealso marker="stdlib:log_mf_h">the STDLIB Reference + Manual</seealso>.</p> + <p>To activate this event handler, three SASL + configuration parameters must be set, + <c>error_logger_mf_dir</c>, <c>error_logger_mf_maxbytes</c>, + and <c>error_logger_mf_maxfiles</c>. The next section provides + more information about the configuration parameters.</p> </item> </taglist> </section> @@ -79,91 +89,88 @@ <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> + application. For more information about configuration parameters, see + <seealso marker="kernel:app"><c>app(4)</c></seealso> in Kernel.</p> + <p>All configuration parameters are optional.</p> <taglist> - <tag><c><![CDATA[sasl_error_logger = Value <optional>]]></c></tag> + <tag><c><![CDATA[sasl_error_logger = Value ]]></c></tag> <item> - <p><c>Value</c> is one of:</p> + <p><c>Value</c> is one of the following:</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> + <item><p>Installs <c>sasl_report_tty_h</c> in the error logger. + This is the default option.</p></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> + <item><p>Installs <c>sasl_report_file_h</c> in the error logger. + All reports go to file <c>FileName</c>, which is a + string. The file is opened in <c>write</c> mode with encoding + <c>utf8</c>.</p></item> <tag><c>{file,FileName,Modes}</c></tag> - <item>Same as <c>{file,FileName}</c> except that the <c>Modes</c> - allows to specify the modes used for opening the <c>FileName</c> - given to the <seealso marker="kernel:file#open/2">file:open/2</seealso> - call. When not specified, the <c>Modes</c> defaults to <c>[write]</c>. - Use <c>[append]</c> for having the <c>FileName</c> open in append mode. - <c>FileName</c> is a string.</item> + <item><p>Same as <c>{file,FileName}</c>, except that <c>Modes</c> + allows you to specify the modes used for opening the <c>FileName</c> + given to the <seealso marker="kernel:file#open/2">file:open/2</seealso> + call. By default, the file is opened in <c>write</c> mode + with encoding <c>utf8</c>. Use <c>[append]</c> to have + the <c>FileName</c> open in append mode. A different + encoding can also be specified. + <c>FileName</c> is a string.</p></item> <tag><c>false</c></tag> - <item> - <p>No SASL error logger handler is installed.</p> - </item> + <item><p>No SASL error logger handler is installed.</p></item> </taglist> </item> - <tag><c><![CDATA[errlog_type = error | progress | all <optional>]]></c></tag> + <tag><c><![CDATA[errlog_type = error | progress | all ]]></c></tag> <item> <p>Restricts the error logging performed by the specified - <c>sasl_error_logger</c> to error reports, progress reports, + <c>sasl_error_logger</c> to error reports or progress reports, or both. Default is <c>all</c>.</p> </item> - <tag><c><![CDATA[error_logger_mf_dir = string() | false<optional>]]></c></tag> + <tag><c><![CDATA[error_logger_mf_dir = string() | false ]]></c></tag> <item> - <p>Specifies in which directory the files are stored. If this - parameter is undefined or <c>false</c>, + <p>Specifies in which directory <c>log_mf_h</c> is to store + its files. If this parameter is undefined or <c>false</c>, the <c>log_mf_h</c> handler 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>log_mf_h</c> handler is not - installed.</p> - </item> - <tag><c><![CDATA[error_logger_mf_maxfiles = 0<integer()<256 <optional>]]></c></tag> + <tag><c><![CDATA[error_logger_mf_maxbytes = integer() ]]></c></tag> <item> - <p>Specifies how many files are used. If this parameter is - undefined, the <c>log_mf_h</c> handler 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> + <p>Specifies the maximum size of each individual file written + by <c>log_mf_h</c>. If this parameter is undefined, + the <c>log_mf_h</c> handler is not installed.</p> </item> - <tag><c><![CDATA[overload_weight = float() > 0 <optional>]]></c></tag> + <tag><c><![CDATA[error_logger_mf_maxfiles = 0<integer()<256 ]]></c></tag> <item> - <p>Specifies the <c>overload</c> weight. Default is <c>0.1</c>.</p> + <p>Specifies the number of files used by <c>log_mf_h</c>. If + this parameter is undefined, the <c>log_mf_h</c> handler is + not installed.</p> </item> - <tag><c><![CDATA[start_prg = string() <optional>]]></c></tag> + <tag><c><![CDATA[start_prg = string() ]]></c></tag> <item> - <p>Specifies which program should be used when restarting - the system. Default is <c>$OTP_ROOT/bin/start</c>.</p> + <p>Specifies the program to be used when restarting the system + during release installation. Default is + <c>$OTP_ROOT/bin/start</c>.</p> </item> - <tag><c><![CDATA[masters = [atom()] <optional>]]></c></tag> + <tag><c><![CDATA[masters = [atom()] ]]></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> + <p>Specifies the nodes used by this node to read/write release + information. This parameter is ignored if parameter + <c>client_directory</c> is not set.</p> </item> - <tag><c><![CDATA[client_directory = string() <optional>]]></c></tag> + <tag><c><![CDATA[client_directory = string() ]]></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> + nodes. For details, see + <seealso marker="doc/design_principles:release_handling">Release Handling</seealso> + in <em>OTP Design Principles</em>. This parameter is + ignored if parameter <c>masters</c> is not set.</p> </item> - <tag><c><![CDATA[static_emulator = true | false <optional>]]></c></tag> + <tag><c><![CDATA[static_emulator = true | false ]]></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> + new emulator, as the executable files are written into memory + statically. This parameter is ignored if parameters <c>masters</c> + and <c>client_directory</c> are not set.</p> </item> - <tag><c><![CDATA[releases_dir = string() <optional>]]></c></tag> + <tag><c><![CDATA[releases_dir = string() ]]></c></tag> <item> <p>Indicates where the <c>releases</c> directory is located. The release handler writes all its files to this directory. @@ -171,7 +178,7 @@ <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> + <tag><c><![CDATA[utc_log = true | false ]]></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 @@ -182,13 +189,12 @@ <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> + <p><seealso marker="alarm_handler"><c>alarm_handler(3)</c></seealso>, + <seealso marker="kernel:error_logger"><c>error_logger(3)</c></seealso>, + <seealso marker="stdlib:log_mf_h"><c>log_mf_h(3)</c></seealso>, + <seealso marker="rb"><c>rb(3)</c></seealso>, + <seealso marker="release_handler"><c>release_handler(3)</c></seealso>, + <seealso marker="systools"><c>systools(3)</c></seealso></p> </section> </appref> diff --git a/lib/sasl/doc/src/sasl_intro.xml b/lib/sasl/doc/src/sasl_intro.xml index 2dc3efebc1..f74a7c1db8 100644 --- a/lib/sasl/doc/src/sasl_intro.xml +++ b/lib/sasl/doc/src/sasl_intro.xml @@ -4,7 +4,7 @@ <chapter> <header> <copyright> - <year>1997</year><year>2013</year> + <year>1997</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,22 +31,31 @@ </header> <section> - <title>About This Document</title> - <p>The SASL (System Architecture Support Libraries) - application provides support for:</p> + <title>Scope</title> + <p>The SASL 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> + <item>Error logging</item> + <item>Alarm handling</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> + <p>Section + <seealso marker="error_logging">SASL Error Logging</seealso> + describes the error + handler that produces the supervisor, progress, and crash + reports, which can be written to screen or to a specified file. + It also describes the Report Browser (RB).</p> + <p>The sections about release structure and release handling have + been moved to section + <seealso marker="doc/design_principles:users_guide">OTP Design Principles</seealso> + in <em>System Documentation</em>.</p> </section> + + <section> + <title>Prerequisites</title> + <p>It is assumed that the reader is familiar with the Erlang + programming language.</p> + </section> + </chapter> diff --git a/lib/sasl/doc/src/script.xml b/lib/sasl/doc/src/script.xml index 838efe69bb..b40ff28179 100644 --- a/lib/sasl/doc/src/script.xml +++ b/lib/sasl/doc/src/script.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1997</year> - <year>2013</year> + <year>2016</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -37,25 +37,21 @@ <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 + <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>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> + <c>Name.script</c> file, using + <seealso marker="systools#script2boot/1"><c>systools:script2boot/1</c></seealso>.</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> + <c>.rel</c> file and from <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> + <title>File Syntax</title> + <p>The boot script is stored in a file with extension + <c>.script</c>. The file has the following syntax:</p> <code type="none"> {script, {Name, Vsn}, [ @@ -70,100 +66,97 @@ ... {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 + {progress, started}]}.</code> + <taglist> + <tag><c>Name = string()</c></tag> + <item><p>Defines the system name.</p></item> + <tag><c>Vsn = string()</c></tag> + <item><p>Defines the system version.</p></item> + <tag><c>{progress, Term}</c></tag> + <item><p>Sets the "progress" of the initialization + program. The + <seealso marker="erts:init#get_status/0"><c>init:get_status/0</c></seealso> + function returns the current value of the progress, which is + <c>{InternalStatus,Term}</c>.</p></item> + <tag><c>{path, [Dir]}</c></tag> + <item><p><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 + any path flags that 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> + <c>DirN, DirN-1, ..., Dir2, Dir1</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> + load path.</item> <item> <p><c>-path Dir1 Dir2 ... DirN</c> defines a set of - directories <c>Dir1, Dir2, ..., DirN</c> which replaces + directories <c>Dir1, Dir2, ..., DirN</c>, which replace 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> + to be absolute path names.</item> <item>Directory names not starting with <c>/</c> are - assumed to be relative the current working directory. - </item> + 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 + in the script, not as a command-line argument. The given directory is relative the Erlang installation - directory. - </item> + 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> + </item> + <tag><c>{primLoad, [Mod]}</c></tag> + <item><p>Loads the modules <c>[Mod]</c> + from the directories specified in <c>Path</c>. The script + interpreter fetches the appropriate module by calling + <seealso marker="erts:erl_prim_loader#get_file/1"> + <c>erl_prim_loader:get_file(Mod)</c></seealso>. A fatal error + that terminates the system occurs if the module cannot be + located.</p></item> + <tag><c>{kernel_load_completed}</c></tag> + <item><p>Indicates that all modules + that <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.</p></item> + <tag><c>{kernelProcess, Name, {Mod, Func, Args}}</c></tag> + <item><p>Starts the + "kernel process" <c>Name</c> + by evaluating <c>apply(Mod, Func, Args)</c>. The start function is + to return <c>{ok, Pid}</c> or <c>ignore</c>. The <c>init</c> + process monitors the behavior 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.</p></item> + <tag><c>{apply, {Mod, Func, Args}}</c>.</tag> + <item><p>The init process + 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.</p></item> + </taglist> <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> + <p>In an interactive system, the code loader provides + demand-driven code loading, but in an embedded system + the code loader loads all code immediately. The same + version of <seealso marker="kernel:code"><c>code</c></seealso> + is used in both cases. The code server calls + <seealso marker="erts:init#get_argument/1"><c>init:get_argument(mode)</c></seealso> + to determine if it is to run in demand mode or non-demand + driven mode.</p> </note> </section> <section> - <title>SEE ALSO</title> - <p>systools(3) - </p> + <title>See Also</title> + <p><seealso marker="systools"><c>systools(3)</c></seealso></p> </section> </fileref> diff --git a/lib/sasl/doc/src/systools.xml b/lib/sasl/doc/src/systools.xml index 11d99fa595..e7c3c499da 100644 --- a/lib/sasl/doc/src/systools.xml +++ b/lib/sasl/doc/src/systools.xml @@ -5,7 +5,7 @@ <header> <copyright> <year>1996</year> - <year>2013</year> + <year>2017</year> <holder>Ericsson AB, All Rights Reserved</holder> </copyright> <legalnotice> @@ -31,17 +31,18 @@ <rev></rev> </header> <module>systools</module> - <modulesummary>A Set of Release Handling Tools.</modulesummary> + <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>.boot</c>, <c>.script</c>), a release upgrade file (<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> + <fsummary>Generates a release upgrade file <c>relup</c>.</fsummary> <type> <v>Name = string()</v> <v>UpFrom = DownTo = [Name | {Name,Descr}]</v> @@ -50,93 +51,94 @@ | warnings_as_errors</v> <v> Dir = string()</v> <v>Result = ok | error | {ok,Relup,Module,Warnings} | {error,Module,Error}</v> - <v> Relup - see relup(4)</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>Generates a release upgrade file <c>relup</c> containing instructions + for upgrading from or downgrading to one or more previous releases. + The instructions are used by + <seealso marker="release_handler"><c>release_handler</c></seealso> + when installing a new version of a release in runtime.</p> + <p>By default, <c>relup</c> file is located in the current working + directory. If option <c>{outdir,Dir}</c> is specified, + the <c>relup</c> file is located 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> + all release resource files <c>Name2.rel</c>, specified in + <c>UpFrom</c> and <c>DownTo</c>. For each such pair, the + following 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> + <p>Which applications to be deleted, that is, + applications 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> + <p>Which applications to be added, that is, applications + 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> + <p>Which applications to 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> + 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 + <p>Instructions for this are added to the <c>relup</c> file 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 + <seealso marker="#make_script/1"><c>make_script/1,2</c></seealso>. + High-level instructions are translated + into low-level instructions and the result is printed to the + <c>relup</c> file.</p> + <p>The optional <c>Descr</c> parameter is included "as is" in + the <c>relup</c> file, see + <seealso marker="relup"><c>relup(4)</c></seealso>. 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 + assumed that the <c>.app</c> and <c>.appup</c> files for an + application are located in the same directory.</p> + <p>If option <c>{path,[Dir]}</c> is specified, this path is + appended to the current path. Wildcard <c>*</c> is + expanded to all matching directories, for example, + <c>lib/*/ebin</c>.</p> + <p>If option <c>restart_emulator</c> is specified, a low-level instruction to restart the emulator is appended to - the relup scripts. This ensures that a complete reboot of + the <c>relup</c> file. This ensures that a complete reboot of the system is done when the system is upgraded or downgraded.</p> - <p>If an upgrade includes a change from an emulator earlier - than OTP R15 to OTP R15 or later, the warning - <c>pre_R15_emulator_upgrade</c> is issued. See <seealso - marker="doc/design_principles:appup_cookbook">Design - Principles</seealso> for more information about this.</p> + <p>If an upgrade includes a change from an emulator earlier + than OTP R15 to OTP R15 or later, the warning + <c>pre_R15_emulator_upgrade</c> is issued. For more information + about this, see + <seealso marker="doc/design_principles:appup_cookbook">Design + Principles</seealso> in <em>System Documentation</em>.</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 + the function returns <c>ok</c> or <c>error</c>. If option + <c>silent</c> is specified, the function instead either returns + <c>{ok,Relup,Module,Warnings}</c>, where <c>Relup</c> is + the release upgrade file, 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> - <p>If the option <c>noexec</c> is provided, the function returns + <p>If option <c>noexec</c> is specified, the function returns the same values as for <c>silent</c> but no <c>relup</c> file is created.</p> - <p>If the option <c>warnings_as_errors</c> is provided, warnings - are treated as errors.</p> + <p>If option <c>warnings_as_errors</c> is specified, warnings + are treated as errors.</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> + <fsummary>Generates a boot script <c>.script/.boot</c>.</fsummary> <type> <v>Name = string()</v> <v>Opt = src_tests | {path,[Dir]} | local | {variables,[Var]} | exref | @@ -153,117 +155,120 @@ <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 + specifies which code to be loaded and which applications + to be started when the Erlang runtime system is started. + See <seealso marker="script"><c>script(4)</c></seealso>.</p> + <p>The release resource file <c>Name.rel</c> is read to determine + which applications are included in the release. Then + the relevant application resource files <c>App.app</c> are read + to determine which modules to be loaded, and if and + how the applications are to be started. (Keys <c>modules</c> + and <c>mod</c>, see + <seealso marker="kernel:app"><c>app(4)</c></seealso>.</p> + <p>By default, the boot script and boot file are located 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 + option <c>{outdir,Dir}</c> is specified, they are located in <c>Dir</c> instead.</p> - <p>The correctness of each application is checked:</p> + <p>The correctness of each application is checked as follows:</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 + the <c>.rel</c> file is to 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> + <p>There are to be no undefined applications, that is, + dependencies to applications that are not included in + the release. (Key <c>applications</c> in the <c>.app</c> file).</p> </item> <item> - <p>There should be no circular dependencies among + <p>There are to be no circular dependencies among the applications.</p> </item> <item> - <p>There should be no duplicated modules, that is, modules with + <p>There are to be no duplicated modules, that is, modules with the same name but belonging to different applications.</p> </item> <item> - <p>If the <c>src_tests</c> option is specified, a + <p>If option <c>src_tests</c> is specified, a warning is issued if the source code for a module is - missing or newer than the object code.</p> + missing or is newer than the object code.</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>The function will fail if the mandatory - applications <c>kernel</c> and <c>stdlib</c> are not - included in the <c>.rel</c> file and have start - type <c>permanent</c> (default).</p> - <p>If <c>sasl</c> is not included as an application in - the <c>.rel</c> file, a warning is emitted because such a - release can not be used in an upgrade. To turn off this - warning, add the option <c>no_warn_sasl</c>.</p> + <p>The function fails if the mandatory + applications Kernel and STDLIB are not + included in the <c>.rel</c> file and have start + type <c>permanent</c> (which is default).</p> + <p>If SASL is not included as an application in + the <c>.rel</c> file, a warning is issued because such a + release cannot be used in an upgrade. To turn off this + warning, add option <c>no_warn_sasl</c>.</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> + application are 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 + it is an <c>ebin</c> directory in which case they can be located in the corresponding <c>src</c> directory.</p> - <p>If the option <c>{path,[Dir]}</c> is provided, this path is + <p>If option <c>{path,[Dir]}</c> is specified, 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 + specified 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 + structured as <c>App-Vsn/ebin</c>. They are 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 + of the installed release. If option <c>local</c> is + specified, 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 + <p>Option <c>variables</c> 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 + <c>Prefix/Rest/App[-Vsn]/ebin</c>, this application gets 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 + the path is <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> + values using command-line flag <c>boot_var</c>.</p> + <p><em>Example:</em> If option <c>{variables,[{"TEST","lib"}]}</c> + is specified and <c>myapp.app</c> is found in + <c>lib/myapp/ebin</c>, the path to this application in + the boot script is <c>"$TEST/myapp-1/ebin"</c>. If + <c>myapp.app</c> is found in <c>lib/test</c>, the path + is <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 + option <c>exref</c>. 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> + warnings are issued 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 + the function returns <c>ok</c> or <c>error</c>. If option + <c>silent</c> is specified, 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> - <p>If the option <c>warnings_as_errors</c> is provided, warnings - are treated as errors.</p> - <p>If the option <c>no_dot_erlang</c> is provided, the instruction to - load the <c>.erlang</c> file during boot is <em>NOT</em> included.</p> + <p>If option <c>warnings_as_errors</c> is specified, warnings + are treated as errors.</p> + <p>If option <c>no_dot_erlang</c> is specified, the instruction to + load the <c>.erlang</c> file during boot is <em>not</em> + included.</p> </desc> </func> + <func> <name>make_tar(Name) -> Result</name> <name>make_tar(Name, [Opt]) -> Result</name> - <fsummary>Create a release package.</fsummary> + <fsummary>Creates a release package.</fsummary> <type> <v>Name = string()</v> - <v>Opt = {dirs,[IncDir]} | {path,[Dir]} | {variables,[Var]} | {var_tar,VarTar} | {erts,Dir} | src_tests | exref | {exref,[App]} | silent | {outdir,Dir}</v> + <v>Opt = {dirs,[IncDir]} | {path,[Dir]} | {variables,[Var]} | {var_tar,VarTar} | {erts,Dir} | src_tests | exref | {exref,[App]} | silent | {outdir,Dir} | | no_warn_sasl | warnings_as_errors</v> <v> Dir = string()</v> <v> IncDir = src | include | atom()</v> <v> Var = {VarName,PreFix}</v> @@ -276,90 +281,95 @@ <v> Warning = Error = term()</v> </type> <desc> - <p>Creates a release package file <c>Name.tar.gz</c>. file. + <p>Creates a release package file <c>Name.tar.gz</c>. 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 + system using + <seealso marker="release_handler"><c>release_handler</c></seealso> + before the new release can be installed.</p> + <p>The release resource file <c>Name.rel</c> is read to determine 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 + read to determine the version and modules of each application + (keys <c>vsn</c> and <c>modules</c>, see + <seealso marker="kernel:app"><c>app(4)</c></seealso>).</p> + <p>By default, the release package file is located 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> + directory unless <c>Name</c> contains a path. If option + <c>{outdir,Dir}</c> is specified, it is located in <c>Dir</c> instead.</p> + <p>If SASL is not included as an application in + the <c>.rel</c> file, a warning is issued because such a + release cannot be used in an upgrade. To turn off this + warning, add option <c>no_warn_sasl</c>.</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: + included application. If more directories are to be included, + option <c>dirs</c> is specified, for 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 + option <c>{path,[Dir]}</c> is specified, this path is + appended to the current path. 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 + <p>Option <c>variables</c> 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 + the applications. If variable <c>{VarName,Prefix}</c> is + specified and an application is found in directory + <c>Prefix/Rest/App[-Vsn]/ebin</c>, this application is 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 + <p><em>Example:</em> If option <c>{variables,[{"TEST","lib"}]}</c> + is specified and <c>myapp.app</c> is located in + <c>lib/myapp-1/ebin</c>, 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 +...</pre> + <p>Option <c>{var_tar,VarTar}</c> can be used to specify if + and where a separate package is to be stored. In this option + <c>VarTar</c> is one of the following:</p> + <taglist> + <tag><c>include</c></tag> + <item><p>Each separate (variable) package is included in the + main <c>ReleaseName.tar.gz</c> file. This is the + default.</p></item> + <tag><c>ownfile</c></tag> + <item><p>Each separate (variable) package is + generated as a separate file in the same directory as + the <c>ReleaseName.tar.gz</c> file.</p></item> + <tag><c>omit</c></tag> + <item><p>No separate (variable) packages are + generated. Applications that are found underneath a + variable directory are ignored.</p></item> + </taglist> + <p>A directory <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 + subdirectory <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 + specified using option <c>path</c>.</p> + <p>If the release package is to 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>src_tests</c> and <c>exref</c> options are also + <p>All checks with function + <seealso marker="#make_script/1"><c>make_script</c></seealso> + are performed before the release package is created. + Options <c>src_tests</c> and <c>exref</c> 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> + are the same as described for + <seealso marker="#make_script/1"><c>make_script</c></seealso>.</p> </desc> </func> + <func> <name>script2boot(File) -> ok | error</name> - <fsummary>Generate a binary version of a boot script.</fsummary> + <fsummary>Generates a binary version of a boot script.</fsummary> <type> <v>File = string()</v> </type> @@ -367,17 +377,24 @@ myapp-1/ebin/myapp.app <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> + to a binary term, which is stored in the <c>File.boot</c> + file.</p> + <p>A boot script generated using + <seealso marker="#make_script/1"><c>make_script</c></seealso> + 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> + <title>See Also</title> + <p><seealso marker="kernel:app"><c>app(4)</c></seealso>, + <seealso marker="appup"><c>appup(4)</c></seealso>, + <seealso marker="erts:erl"><c>erl(1)</c></seealso>, + <seealso marker="rel"><c>rel(4)</c></seealso>, + <seealso marker="release_handler"><c>release_handler(3)</c></seealso>, + <seealso marker="relup"><c>relup(4)</c></seealso>, + <seealso marker="script"><c>script(4)</c></seealso></p> </section> </erlref> diff --git a/lib/sasl/doc/src/warning.gif b/lib/sasl/doc/src/warning.gif Binary files differdeleted file mode 100644 index 96af52360e..0000000000 --- a/lib/sasl/doc/src/warning.gif +++ /dev/null diff --git a/lib/sasl/examples/src/Makefile b/lib/sasl/examples/src/Makefile index 82083d1197..e8b903f252 100644 --- a/lib/sasl/examples/src/Makefile +++ b/lib/sasl/examples/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 2010-2012. All Rights Reserved. +# Copyright Ericsson AB 2010-2016. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. diff --git a/lib/sasl/examples/src/target_system.erl b/lib/sasl/examples/src/target_system.erl index d18fdb17f7..b3d6748306 100644 --- a/lib/sasl/examples/src/target_system.erl +++ b/lib/sasl/examples/src/target_system.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2011-2014. All Rights Reserved. +%% Copyright Ericsson AB 2011-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. diff --git a/lib/sasl/src/Makefile b/lib/sasl/src/Makefile index 7ff6a03a50..ac7ee51100 100644 --- a/lib/sasl/src/Makefile +++ b/lib/sasl/src/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 1996-2013. All Rights Reserved. +# Copyright Ericsson AB 1996-2016. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -36,7 +36,7 @@ RELSYSDIR = $(RELEASE_PATH)/lib/sasl-$(VSN) # ---------------------------------------------------- MODULES= alarm_handler sasl sasl_report \ sasl_report_file_h sasl_report_tty_h format_lib_supp \ - misc_supp overload rb rb_format_supp release_handler \ + misc_supp rb rb_format_supp release_handler \ release_handler_1 si si_sasl_supp systools \ systools_make systools_rc systools_relup systools_lib \ erlsrv diff --git a/lib/sasl/src/alarm_handler.erl b/lib/sasl/src/alarm_handler.erl index e428ba80fa..77863f0f8f 100644 --- a/lib/sasl/src/alarm_handler.erl +++ b/lib/sasl/src/alarm_handler.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2009. All Rights Reserved. +%% Copyright Ericsson AB 1996-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. diff --git a/lib/sasl/src/erlsrv.erl b/lib/sasl/src/erlsrv.erl index bec824ad78..29d40d362f 100644 --- a/lib/sasl/src/erlsrv.erl +++ b/lib/sasl/src/erlsrv.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1998-2013. All Rights Reserved. +%% Copyright Ericsson AB 1998-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. diff --git a/lib/sasl/src/format_lib_supp.erl b/lib/sasl/src/format_lib_supp.erl index e2f70c7f00..00ce1b4e33 100644 --- a/lib/sasl/src/format_lib_supp.erl +++ b/lib/sasl/src/format_lib_supp.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2013. All Rights Reserved. +%% Copyright Ericsson AB 1996-2017. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -25,15 +25,12 @@ %%% tools. %%% The main parts are: %%% 1) print_info. Prints information tagged by 'header', 'data', -%%% 'table', 'items' and 'newline'. +%%% 'items' and 'newline'. %%%--------------------------------------------------------------------- %% intermodule exports -export([print_info/2, print_info/3]). -%% exports for use within module --export([maxcol/2]). - %%--------------------------------------------------------------------- %% Format is an ordered list of: %% {header, HeaderString} @@ -42,10 +39,6 @@ %% (if possible); 'Key: Value'. %% Elements in the list may also be single terms, which are %% printed as they are. -%% {table, {TableName, ColumnNames, Columns}} -%% ColumnNames is a tuple of names for the columns, and -%% Columns is a list, where each element is a tuple of -%% data for that column. %% {items, {Name, Items}} %% Items is a list of KeyValue_tuples. Will be printed as: %% 'Name: @@ -77,9 +70,6 @@ print_format(Device, _Line, []) -> print_format(Device, Line, [{data, Data}|T]) -> print_data(Device, Line, Data), print_format(Device, Line, T); -print_format(Device, Line, [{table, Table}|T]) -> - _ = print_table(Device, Line, Table), - print_format(Device, Line, T); print_format(Device, Line, [{items, Items}|T]) -> print_items(Device, Line, Items), print_format(Device, Line, T); @@ -94,51 +84,51 @@ print_data(Device, Line, [{Key, Value}|T]) -> print_one_line(Device, Line, Key, Value), print_data(Device, Line, T); print_data(Device, Line, [Value|T]) -> - io:format(Device, "~p~n", [Value]), - print_data(Device, Line, T). + Modifier = misc_supp:modifier(Device), + io:format(Device, "~"++Modifier++"p~n", [Value]), + print_data(Device, Line, T); +print_data(Device, _Line, Value) -> + Modifier = misc_supp:modifier(Device), + io:format(Device, "~"++Modifier++"p~n", [Value]). print_items(Device, Line, {Name, Items}) -> print_items(Device, Line, Name, Items). -print_table(Device, Line, {TableName, ColumnNames, Columns}) -> - print_table(Device, Line, TableName, ColumnNames, Columns). - print_newlines(_Device, 0) -> ok; print_newlines(Device, N) when N > 0 -> io:format(Device, '~n', []), print_newlines(Device, N-1). print_one_line(Device, Line, Key, Value) -> - StrKey = term_to_string(Key), + Modifier = misc_supp:modifier(Device), + StrKey = term_to_string(Key,Modifier), KeyLen = lists:min([length(StrKey), Line]), ValueLen = Line - KeyLen, - Format1 = lists:concat(["~-", KeyLen, s]), - Format2 = lists:concat(["~", ValueLen, "s~n"]), + Format1 = lists:concat(["~-", KeyLen, Modifier, "s"]), + Format2 = lists:concat(["~", ValueLen, Modifier, "s~n"]), io:format(Device, Format1, [StrKey]), - Try = term_to_string(Value), + Try = term_to_string(Value,Modifier), Length = length(Try), if Length < ValueLen -> io:format(Device, Format2, [Try]); true -> io:format(Device, "~n ", []), - Format3 = lists:concat(["~", Line, ".9p~n"]), + Format3 = lists:concat(["~", Line, ".9", Modifier, "p~n"]), io:format(Device, Format3, [Value]) end. -term_to_string(Value) -> - lists:flatten(io_lib:format(get_format(Value), [Value])). +term_to_string(Value,Modifier) -> + lists:flatten(io_lib:format(get_format(Value,Modifier), [Value])). -get_format(Value) -> - case misc_supp:is_string(Value) of - true -> "~s"; - false -> "~p" +get_format([],_) -> + "~p"; +get_format(Value,Modifier) -> + case io_lib:printable_list(Value) of + true -> "~"++Modifier++"s"; + false -> "~"++Modifier++"p" end. -make_list(0, _Elem) -> []; -make_list(N, Elem) -> [Elem|make_list(N-1, Elem)]. - - %%----------------------------------------------------------------- %% Items %%----------------------------------------------------------------- @@ -150,76 +140,3 @@ print_item_elements(_Device, _Line, []) -> ok; print_item_elements(Device, Line, [{Key, Value}|T]) -> print_one_line(Device, Line, lists:concat([" ", Key]), Value), print_item_elements(Device, Line, T). - -%%----------------------------------------------------------------- -%% Table handling -%%----------------------------------------------------------------- -extra_space_between_columns() -> 3. - -find_max_col([Row | T], ColumnSizes) -> - find_max_col(T, misc_supp:multi_map({format_lib_supp, maxcol}, - [Row, ColumnSizes])); - -find_max_col([], ColumnSizes) -> ColumnSizes. - -maxcol(Term, OldMax) -> - lists:max([length(term_to_string(Term)), OldMax]). - -make_column_format(With) -> - lists:concat(["~", With + extra_space_between_columns(), s]). - -is_correct_column_length(_Length, []) -> true; -is_correct_column_length(Length, [Tuple|T]) -> - case size(Tuple) of - Length -> is_correct_column_length(Length, T); - _ -> false - end; -is_correct_column_length(_, _) -> false. - -print_table(Device, Line, TableName, _TupleOfColumnNames, []) -> - print_one_line(Device, Line, TableName, "<empty table>"), - io:format(Device, "~n", []); - -print_table(Device, Line, TableName, TupleOfColumnNames, ListOfTuples) - when is_list(ListOfTuples), is_tuple(TupleOfColumnNames) -> - case is_correct_column_length(size(TupleOfColumnNames), - ListOfTuples) of - true -> - print_one_line(Device, Line, TableName, " "), - ListOfColumnNames = tuple_to_list(TupleOfColumnNames), - ListOfLists = lists:map(fun(Tuple) -> - tuple_to_list(Tuple) - end, - ListOfTuples), - ColWidths = find_max_col([ListOfColumnNames | - ListOfLists], - make_list(length(ListOfColumnNames),0)), - Format = lists:flatten([lists:map(fun(CW) -> - make_column_format(CW) - end, - ColWidths), "~n"]), - io:format(Device, Format, ListOfColumnNames), - io:format(Device, - lists:concat(['~', extra_space_between_columns(), - 'c', '~', lists:sum(ColWidths) - + (length(ColWidths) - 1) - * extra_space_between_columns(), - 'c~n']), [$ , $-]), - lists:foreach(fun(List) -> - print_row(List, Device, Format) - end, - ListOfLists), - io:format(Device, '~n', []), - true; - false -> - {error, {'a tuple has wrong size', - {TableName, TupleOfColumnNames, ListOfTuples}}} - end. - -%%-------------------------------------------------- -%% Device MUST be 2nd arg because of extraarg ni foreach... -%%-------------------------------------------------- -print_row(Row, Device, Format) -> - io:format(Device, Format, - lists:map(fun(Term) -> term_to_string(Term) end, - Row)). diff --git a/lib/sasl/src/misc_supp.erl b/lib/sasl/src/misc_supp.erl index 42de7eedec..cbbcba0def 100644 --- a/lib/sasl/src/misc_supp.erl +++ b/lib/sasl/src/misc_supp.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2009. All Rights Reserved. +%% Copyright Ericsson AB 1996-2017. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -27,12 +27,12 @@ %%% 2) Very generic functions such as, multi_map, is_string... %%% %%% This module is a part of the BOS. (format_pdict is called from -%%% init, memsup, disksup, overload (but not the fileserver since it +%%% init, memsup, disksup (but not the fileserver since it %%% formats its pdict its own way).) %%%--------------------------------------------------------------------- -export([format_pdict/3, format_tuples/2, assq/2, passq/2, is_string/1, - multi_map/2]). + multi_map/2, modifier/1]). %%----------------------------------------------------------------- %% Uses format_tuples to format the data in process dictionary. @@ -105,3 +105,19 @@ multi_map(Func, ListOfLists) -> [apply(Func, lists:map(fun(List) -> hd(List) end, ListOfLists)) | multi_map(Func, lists:map(fun(List) -> tl(List) end, ListOfLists))]. + +%%%----------------------------------------------------------------- +%%% Check encoding of the given device and return "t" if this format +%%% modifier should be used. +modifier(Device) -> + Encoding = + case io:getopts(Device) of + List when is_list(List) -> + proplists:get_value(encoding,List,latin1); + _ -> + latin1 + end, + encoding_to_modifier(Encoding). + +encoding_to_modifier(latin1) -> ""; +encoding_to_modifier(_) -> "t". diff --git a/lib/sasl/src/overload.erl b/lib/sasl/src/overload.erl deleted file mode 100644 index 61b925d219..0000000000 --- a/lib/sasl/src/overload.erl +++ /dev/null @@ -1,231 +0,0 @@ -%% -%% %CopyrightBegin% -%% -%% Copyright Ericsson AB 1996-2013. All Rights Reserved. -%% -%% Licensed under the Apache License, Version 2.0 (the "License"); -%% you may not use this file except in compliance with the License. -%% You may obtain a copy of the License at -%% -%% http://www.apache.org/licenses/LICENSE-2.0 -%% -%% Unless required by applicable law or agreed to in writing, software -%% distributed under the License is distributed on an "AS IS" BASIS, -%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -%% See the License for the specific language governing permissions and -%% limitations under the License. -%% -%% %CopyrightEnd% -%% --module(overload). - --export([start_link/0, request/0, set_config_data/2, - get_overload_info/0]). - --export([init/1, handle_call/3, handle_info/2, terminate/2, - format_status/2]). - -%%%----------------------------------------------------------------- -%%% This is a rewrite of overload from BS.3, by Peter Högfeldt. -%%% -%%% DESCRIPTION -%%% -%%% This module implements a server process that keeps record of the -%%% intensity of calls of the request/0 function, and answers accept or -%%% reject depending on if the current average intensity is not greater -%%% than a specified maximum intensity. -%%% -%%% The intensity i is calculated according to the formula: -%%% i(n) = exp(-K*(T(n) - T(n-1)))*i(n-1) + Kappa -%%% where i(n) is the intensity at event n, Kappa is a constant, and -%%% T(n) is the time at event n. -%%% -%%% The constant Kappa can be thought of as 1 / T, where T is the time -%%% constant. Kappa is externally referred to as Weight. -%%% -%%% We keep track of two intensities: the total call intensity and the -%%% intensity of accepted calls. -%%%----------------------------------------------------------------- -%%% TODO -%%% -%%% 3. Hysteresis. -%%% -%%%----------------------------------------------------------------- - --record(state, {total = 0, accept = 0, max, prev_t = get_now(), - kappa, call_counts = {0, 0}, alarm = clear}). - --define(clear_timeout, 30000). - -start_link() -> - gen_server:start_link({local, overload}, overload, [], []). - -init([]) -> - process_flag(priority, high), - MaxIntensity = fetch_config_data(overload_max_intensity), - Kappa = fetch_config_data(overload_weight), - {ok, #state{max = MaxIntensity, kappa = Kappa}}. - -%%----------------------------------------------------------------- -%% Func: request/0 -%% Purpose: This is a request to proceed, e.g. a request to -%% establish a call. -%% Returns: accept | reject -%%----------------------------------------------------------------- -request() -> call(request). - -%%----------------------------------------------------------------- -%% Func: set_config_data/2 -%% Purpose: Set configuration data, and reset intensities. -%% Arguments: MaxIntensity (real > 0), Weight (real > 0). -%% Returns: ok | {error, What} -%% This function is for debugging purposes and is therefore not -%% documented at all. -%%----------------------------------------------------------------- -set_config_data(MaxIntensity, Weight) -> - call({set_config_data, MaxIntensity, Weight}). -%%----------------------------------------------------------------- -%% Func: get_overload_info/0 -%% Returns: A list of tagged items: TotalIntensity, AcceptIntensity, -%% MaxIntensity, Weight, TotalRequests, AcceptedRequests. -%%----------------------------------------------------------------- -get_overload_info() -> call(get_overload_info). - -%%----------------------------------------------------------------- -%% call(Request) -> Term -%%----------------------------------------------------------------- -call(Req) -> - gen_server:call(overload, Req, infinity). - -%%%----------------------------------------------------------------- -%%% Callback functions from gen_server -%%%----------------------------------------------------------------- -handle_call(request, _From, State) -> - #state{total = TI, accept = AI, kappa = Kappa, prev_t = PrevT, - alarm = Alarm} = State, - {TR, AR} = State#state.call_counts, - T = get_now(), - CurI = new_intensity(AI, T, PrevT, Kappa), - NewTI = new_intensity(TI, T, PrevT, Kappa) + Kappa, - if - CurI =< State#state.max -> - %% Hysteresis: If alarm is set, and current intensity has - %% fallen below 75% of max intensity, clear alarm. - NewAlarm = if - CurI =< 0.75*State#state.max -> - clear_alarm(Alarm); - true -> - Alarm - end, - {reply, accept, State#state{call_counts = {TR+1, AR+1}, - prev_t = T, total = NewTI, - accept = CurI + Kappa, - alarm = NewAlarm}, - ?clear_timeout}; - true -> - %% Set alarm if not already set. - NewAlarm = set_alarm(Alarm), - {reply, reject, - State#state{call_counts = {TR+1, AR}, prev_t = T, - total = NewTI, accept = CurI, - alarm = NewAlarm}, - ?clear_timeout} - end; -handle_call({set_config_data, MaxIntensity, Weight}, _From, _State) -> - {reply, ok, #state{max = MaxIntensity, kappa = Weight}, - ?clear_timeout}; -handle_call(get_overload_info, _From, State) -> - #state{max = MI, total = TI, accept = AI, kappa = Kappa, - prev_t = PrevT, call_counts = {TR, AR}} = State, - T = get_now(), - CurI = new_intensity(AI, T, PrevT, Kappa), - NewTI = new_intensity(TI, T, PrevT, Kappa), - Reply = [{total_intensity, NewTI}, {accept_intensity, CurI}, - {max_intensity, MI}, {weight, Kappa}, - {total_requests, TR}, {accepted_requests, AR}], - {reply, Reply, State#state{total = NewTI, accept = CurI}, - ?clear_timeout}. - -handle_info(timeout, State) -> - #state{total = TI, accept = AI, kappa = Kappa, prev_t = PrevT, - alarm = Alarm} = State, - T = get_now(), - CurI = new_intensity(AI, T, PrevT, Kappa), - NewTI = new_intensity(TI, T, PrevT, Kappa), - if - CurI < 0.75* State#state.max -> - NewAlarm = clear_alarm(Alarm), - {noreply, State#state{total = NewTI, accept = CurI, - alarm = NewAlarm}}; - - true -> - {noreply, State#state{total = NewTI, accept = CurI}, - ?clear_timeout} - end; - -handle_info(_, State) -> - {noreply, State, ?clear_timeout}. - -terminate(_Reason, _State) -> - ok. - -%%----------------------------------------------------------------- -%% Internal functions -%%----------------------------------------------------------------- -fetch_config_data(Tag) -> - case application:get_env(sasl, Tag) of - {ok, Value} -> Value; - _ -> fetch_default_data(Tag) - end. - -fetch_default_data(overload_max_intensity) -> 0.8; -fetch_default_data(overload_weight) -> 0.1. - -set_alarm(clear) -> - alarm_handler:set_alarm({overload, []}), - set; -set_alarm(Alarm) -> - Alarm. - -clear_alarm(set) -> - alarm_handler:clear_alarm(overload), - clear; -clear_alarm(Alarm) -> - Alarm. - -%%----------------------------------------------------------------- -%% The catch protects against floating-point exception. -%% -new_intensity(I, T, PrevT, K) -> - Diff = sub(T, PrevT)/1000, - case catch (I*math:exp(-K*Diff)) of - {'EXIT', _} -> % Assume zero. - 0.0; - Res -> - Res - end. - -%% Mask equal to 2^27 - 1, used below. --define(mask27, 16#7ffffff). - -%% Returns number of milliseconds in the range [0, 2^27 - 1]. Must have -%% this since statistics(wall_clock) wraps. Having 2^27 -1 as the max -%% assures that we always get non-negative integers. 2^27 milliseconds -%% are approx. 37.28 hours. -get_now() -> - element(1, statistics(wall_clock)) band ?mask27. - -%% Returns (X - Y) mod 2^27 (which is in the range [0, 2^27 - 1]). -sub(X, Y) -> - (X + (bnot Y) + 1) band ?mask27. - -format_status(Opt, [PDict, #state{max = MI, total = TI, accept = AI, - kappa = K, - call_counts = {TR, AR}}]) -> - [{data, [{"Total Intensity", TI}, - {"Accept Intensity", AI}, - {"Max Intensity", MI}, - {"Weight", K}, - {"Total requests", TR}, - {"Accepted requests", AR}]} | - misc_supp:format_pdict(Opt, PDict, [])]. diff --git a/lib/sasl/src/rb.erl b/lib/sasl/src/rb.erl index f63c02e748..6595d29a9c 100644 --- a/lib/sasl/src/rb.erl +++ b/lib/sasl/src/rb.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2013. All Rights Reserved. +%% Copyright Ericsson AB 1996-2017. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -273,7 +273,7 @@ code_change(_OldVsn, State, _Extra) -> open_log_file(standard_io) -> standard_io; open_log_file(Fd) when is_atom(Fd),Fd=/=standard_error -> case whereis(Fd) of - undefined -> io:format("rb: Registered name not found '~s'.~n", + undefined -> io:format("rb: Registered name not found '~ts'.~n", [Fd]), io:format("rb: Using standard_io~n"), open_log_file(standard_io); @@ -281,10 +281,10 @@ open_log_file(Fd) when is_atom(Fd),Fd=/=standard_error -> end; open_log_file(Fd) when is_pid(Fd)-> Fd; open_log_file(FileName) when is_list(FileName) -> - case file:open(FileName, [write,append]) of + case file:open(FileName, [write,append,{encoding,utf8}]) of {ok, Fd} -> Fd; Error -> - io:format("rb: Cannot open file '~s' (~w).~n", + io:format("rb: Cannot open file '~ts' (~w).~n", [FileName, Error]), io:format("rb: Using standard_io~n"), standard_io @@ -419,8 +419,8 @@ read_reports(No, Fd, Fname, Max, Type) -> add_report_data(NewRes, No, Fname); {error, [Problem | Res]} -> _ = file:close(Fd), - io:format("Error: ~p~n",[Problem]), - io:format("Salvaged ~p entries from corrupt report file ~s...~n", + io:format("Error: ~tp~n",[Problem]), + io:format("Salvaged ~p entries from corrupt report file ~ts...~n", [length(Res),Fname]), NewRes = if @@ -431,7 +431,7 @@ read_reports(No, Fd, Fname, Max, Type) -> end, add_report_data(NewRes, No, Fname); Else -> - io:format("err ~p~n", [Else]), + io:format("err ~tp~n", [Else]), [{No, unknown, "Can't read reports from file " ++ Fname, "???", Fname, 0}] end. @@ -530,21 +530,18 @@ get_short_descr({{Date, Time}, {error_report, Pid, {_, crash_report, Rep}}}) -> {value, {_Key, N}} -> N; _ -> Pid end, - NameStr = lists:flatten(io_lib:format("~w", [Name])), - {NameStr, date_str(Date, Time)}; + {Name, date_str(Date, Time)}; get_short_descr({{Date, Time}, {error_report, Pid, {_, supervisor_report,Rep}}}) -> Name = case lists:keysearch(supervisor, 1, Rep) of {value, {_Key, N}} when is_atom(N) -> N; _ -> Pid end, - NameStr = lists:flatten(io_lib:format("~w", [Name])), - {NameStr, date_str(Date,Time)}; + {Name, date_str(Date,Time)}; get_short_descr({{Date, Time}, {_Type, Pid, _}}) -> - NameStr = lists:flatten(io_lib:format("~w", [Pid])), - {NameStr, date_str(Date,Time)}; + {Pid, date_str(Date,Time)}; get_short_descr(_) -> - {"???", "???"}. + {'???', "???"}. date_str({Y,Mo,D}=Date,{H,Mi,S}=Time) -> case application:get_env(sasl,utc_log) of @@ -571,53 +568,57 @@ local_time_to_universal_time({Date,Time}) -> end. -print_list(Fd, Data, Type) -> +print_list(Fd, Data0, Type) -> + Modifier = misc_supp:modifier(Fd), Header = {"No", "Type", "Process", "Date Time"}, - Width = find_width([Header | Data], 0)+1, - DateWidth = find_date_width([Header | Data], 0) +1, - Format = lists:concat(["~4s~20s ~", Width, "s~20s~n"]), + {DescrWidth,DateWidth,Data} = find_widths(Data0, Modifier, 7, 13, []), + Format = lists:concat(["~4s~20s ~", DescrWidth, "s~20s~n"]), io:format(Fd, Format, tuple_to_list(Header)), io:format(Fd, Format, ["==", "====", "=======", "==== ===="]), - print_list(Fd, Data, Type, Width, DateWidth). -print_list(_, [], _, _, _) -> true; -print_list(Fd, [H|T], Type, Width, DateWidth) -> - print_one_report(Fd, H, Type, Width, DateWidth), - print_list(Fd, T, Type, Width, DateWidth). - -find_width([], Width) -> Width; -find_width([H|T], Width) -> - Try = length(element(3, H)), - if - Try > Width -> find_width(T, Try); - true -> find_width(T, Width) - end. -find_date_width([], Width) -> Width; -find_date_width([H|T], Width) -> - Try = length(element(4, H)), - if - Try > Width -> find_date_width(T, Try); - true -> find_date_width(T, Width) - end. + print_list(Fd, Data, Type, DescrWidth, DateWidth, Modifier). +print_list(_, [], _, _, _, _) -> true; +print_list(Fd, [H|T], Type, Width, DateWidth, Modifier) -> + print_one_report(Fd, H, Type, Width, DateWidth, Modifier), + print_list(Fd, T, Type, Width, DateWidth, Modifier). + + +find_widths([], _Modifier, DescrWidth, DateWidth, Data) -> + {DescrWidth+1, DateWidth+1, lists:reverse(Data)}; +find_widths([H|T], Modifier, DescrWidth, DateWidth, Data) -> + DescrTerm = element(3,H), + Descr = lists:flatten(io_lib:format("~"++Modifier++"w", [DescrTerm])), + DescrTry = length(Descr), + NewDescrWidth = + if + DescrTry > DescrWidth -> DescrTry; + true -> DescrWidth + end, + DateTry = length(element(4, H)), + NewDateWitdh = + if + DateTry > DateWidth -> DateTry; + true -> DateWidth + end, + NewH = setelement(3,H,Descr), + find_widths(T, Modifier, NewDescrWidth, NewDateWitdh, [NewH|Data]). print_one_report(Fd, {No, RealType, ShortDescr, Date, _Fname, _FilePos}, WantedType, - Width, DateWidth) -> + Width, DateWidth, Modifier) -> if WantedType == all -> print_short_descr(Fd, No, RealType, ShortDescr, Date, Width, - DateWidth); + DateWidth, Modifier); WantedType == RealType -> print_short_descr(Fd, No, RealType, ShortDescr, Date, Width, - DateWidth); + DateWidth, Modifier); true -> ok end. -print_short_descr(Fd, No, Type, ShortDescr, Date, Width, DateWidth) -> - Format = lists:concat(["~4w~20w ~", Width, "s~", DateWidth,"s~n"]), - io:format(Fd, Format, [No, - Type, - io_lib:format("~s", [ShortDescr]), - Date]). +print_short_descr(Fd, No, Type, ShortDescr, Date, Width, DateWidth, Modifier) -> + Format = lists:concat(["~4w~20", Modifier, "w ~", Width, Modifier, "s~", + DateWidth, "s~n"]), + io:format(Fd, Format, [No, Type, ShortDescr, Date]). print_report_by_num(Dir, Data, Number, Device, Abort, Log) -> {_,Device1} = print_report(Dir, Data, Number, Device, Abort, Log), @@ -658,7 +659,7 @@ print_report(Dir, Data, Number, Device, Abort, Log) -> {ok, Fd} -> read_rep(Fd, FilePosition, Device, Abort, Log); _ -> - io:format("rb: can't open file ~p~n", [Fname]), + io:format("rb: can't open file ~tp~n", [Fname]), {proceed,Device} end; no_report -> @@ -691,14 +692,14 @@ print_grep_report(Dir, Data, Number, Device, RegExp, Abort, Log) -> {ok, Fd} when is_pid(Fd) -> check_rep(Fd, FilePosition, Device, RegExp, Number, Abort, Log); _ -> - io:format("rb: can't open file ~p~n", [Fname]), + io:format("rb: can't open file ~tp~n", [Fname]), {proceed,Device} end. check_rep(Fd, FilePosition, Device, RegExp, Number, Abort, Log) -> case read_rep_msg(Fd, FilePosition) of {Date, Msg} -> - MsgStr = lists:flatten(io_lib:format("~p",[Msg])), + MsgStr = lists:flatten(io_lib:format("~tp",[Msg])), case run_re(MsgStr, RegExp) of match -> io:format("Found match in report number ~w~n", [Number]), @@ -722,7 +723,7 @@ run_re(Subject, Regexp) -> run_re(Subject, Regexp, []). run_re(Subject, Regexp, Options) -> - case re:run(Subject, Regexp, Options) of + case re:run(Subject, Regexp, [unicode|Options--[unicode]]) of nomatch -> nomatch; _ -> @@ -748,7 +749,7 @@ filter_report(Dir, Data, Filters, Number, Device, Abort, Log) -> {ok, Fd} -> filter_rep(Filters, Fd, FilePosition, Device, Abort, Log); _ -> - io:format("rb: can't open file ~p~n", [Fname]), + io:format("rb: can't open file ~tp~n", [Fname]), {proceed,Device} end; no_report -> @@ -800,7 +801,7 @@ filter_report([{Key, RegExp, re}|T], Msg) -> undefined -> false; Value -> - Subject = lists:flatten(io_lib:format("~p",[Value])), + Subject = lists:flatten(io_lib:format("~tp",[Value])), case run_re(Subject, RegExp) of match -> filter_report(T, Msg); @@ -812,7 +813,7 @@ filter_report([{Key, RegExp, re, no}|T], Msg) -> undefined -> true; Value -> - Subject = lists:flatten(io_lib:format("~p",[Value])), + Subject = lists:flatten(io_lib:format("~tp",[Value])), case run_re(Subject, RegExp) of match -> false; _ -> filter_report(T, Msg) @@ -890,7 +891,7 @@ read_rep(Fd, FilePosition, Device, Abort, Log) -> handle_bad_form(Date, Msg, Device, Abort, Log) -> io:format("rb: ERROR! A report on bad form was encountered. " ++ "It can not be printed to the log.~n~n"), - io:format("Details:~n~p ~p~n~n", [Date,Msg]), + io:format("Details:~n~p ~tp~n~n", [Date,Msg]), case {Abort,Device,open_log_file(Log)} of {true,standard_io,standard_io} -> io:format("rb: Logging aborted.~n"), @@ -899,7 +900,7 @@ handle_bad_form(Date, Msg, Device, Abort, Log) -> io:format("rb: Logging resumed...~n~n"), {proceed,Device}; {_,_,standard_io} -> - io:format("rb: Can not reopen ~p. Logging aborted.~n", [Log]), + io:format("rb: Can not reopen ~tp. Logging aborted.~n", [Log]), {abort,Device}; {true,_,NewDevice} -> io:format(NewDevice, diff --git a/lib/sasl/src/rb_format_supp.erl b/lib/sasl/src/rb_format_supp.erl index ed10022f9d..1eda43dae4 100644 --- a/lib/sasl/src/rb_format_supp.erl +++ b/lib/sasl/src/rb_format_supp.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2009. All Rights Reserved. +%% Copyright Ericsson AB 1996-2017. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -94,13 +94,15 @@ print(Date, Report, Device) -> [{header, Header}]), io:format(Device, Format, Args); {Type, _GL, TypeReport} -> - io:format(Device, "~nInfo type <~w> ~s~n", + Modifier = misc_supp:modifier(Device), + io:format(Device, "~nInfo type <~"++Modifier++"w> ~s~n", [Type, Date]), - io:format(Device, "~p", [TypeReport]); + io:format(Device, "~"++Modifier++"p", [TypeReport]); _ -> + Modifier = misc_supp:modifier(Device), io:format("~nPrinting info of unknown type... ~s~n", [Date]), - io:format(Device, "~p", [Report]) + io:format(Device, "~"++Modifier++"p", [Report]) % end end. diff --git a/lib/sasl/src/release_handler.erl b/lib/sasl/src/release_handler.erl index 7e20d0b321..49756f5799 100644 --- a/lib/sasl/src/release_handler.erl +++ b/lib/sasl/src/release_handler.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2013. All Rights Reserved. +%% Copyright Ericsson AB 1996-2017. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -640,8 +640,8 @@ handle_call({install_release, Vsn, ErrorAction, Opts}, From, S) -> {noreply, NS}; {'EXIT', Reason} -> io:format("release_handler:" - "install_release(Vsn=~p Opts=~p) failed, " - "Reason=~p~n", [Vsn, Opts, Reason]), + "install_release(Vsn=~tp Opts=~tp) failed, " + "Reason=~tp~n", [Vsn, Opts, Reason]), gen_server:reply(From, {error, Reason}), case ErrorAction of restart -> @@ -831,7 +831,7 @@ do_unpack_release(Root, RelDir, ReleaseName, Releases) -> Tar = filename:join(RelDir, ReleaseName ++ ".tar.gz"), do_check_file(Tar, regular), Rel = ReleaseName ++ ".rel", - extract_rel_file(filename:join("releases", Rel), Tar, Root), + _ = extract_rel_file(filename:join("releases", Rel), Tar, Root), RelFile = filename:join(RelDir, Rel), Release = check_rel(Root, RelFile, false), #release{vsn = Vsn} = Release, @@ -1052,8 +1052,8 @@ new_emulator_make_tmp_release(CurrentRelease,ToRelease,RelDir,Opts,Masters) -> ToVsn = ToRelease#release.vsn, TmpVsn = ?tmp_vsn(CurrentVsn), case get_base_libs(ToRelease#release.libs) of - {ok,{Kernel,Stdlib,Sasl}=BaseLibs,_} -> - case get_base_libs(ToRelease#release.libs) of + {ok,{Kernel,Stdlib,Sasl},_} -> + case get_base_libs(CurrentRelease#release.libs) of {ok,_,RestLibs} -> TmpErtsVsn = ToRelease#release.erts_vsn, TmpLibs = [Kernel,Stdlib,Sasl|RestLibs], @@ -1062,7 +1062,7 @@ new_emulator_make_tmp_release(CurrentRelease,ToRelease,RelDir,Opts,Masters) -> libs = TmpLibs, status = unpacked}, new_emulator_make_hybrid_boot(CurrentVsn,ToVsn,TmpVsn, - BaseLibs,RelDir,Opts,Masters), + RelDir,Opts,Masters), new_emulator_make_hybrid_config(CurrentVsn,ToVsn,TmpVsn, RelDir,Masters), {TmpVsn,TmpRelease}; @@ -1095,7 +1095,7 @@ get_base_libs([],_Kernel,_Stdlib,undefined,_Rest) -> get_base_libs([],Kernel,Stdlib,Sasl,Rest) -> {ok,{Kernel,Stdlib,Sasl},lists:reverse(Rest)}. -new_emulator_make_hybrid_boot(CurrentVsn,ToVsn,TmpVsn,BaseLibs,RelDir,Opts,Masters) -> +new_emulator_make_hybrid_boot(CurrentVsn,ToVsn,TmpVsn,RelDir,Opts,Masters) -> FromBootFile = filename:join([RelDir,CurrentVsn,"start.boot"]), ToBootFile = filename:join([RelDir,ToVsn,"start.boot"]), TmpBootFile = filename:join([RelDir,TmpVsn,"start.boot"]), @@ -1103,11 +1103,7 @@ new_emulator_make_hybrid_boot(CurrentVsn,ToVsn,TmpVsn,BaseLibs,RelDir,Opts,Maste Args = [ToVsn,Opts], {ok,FromBoot} = read_file(FromBootFile,Masters), {ok,ToBoot} = read_file(ToBootFile,Masters), - {{_,_,KernelPath},{_,_,StdlibPath},{_,_,SaslPath}} = BaseLibs, - Paths = {filename:join(KernelPath,"ebin"), - filename:join(StdlibPath,"ebin"), - filename:join(SaslPath,"ebin")}, - case systools_make:make_hybrid_boot(TmpVsn,FromBoot,ToBoot,Paths,Args) of + case systools_make:make_hybrid_boot(TmpVsn,FromBoot,ToBoot,Args) of {ok,TmpBoot} -> write_file(TmpBootFile,TmpBoot,Masters); {error,Reason} -> @@ -1124,7 +1120,7 @@ new_emulator_make_hybrid_config(CurrentVsn,ToVsn,TmpVsn,RelDir,Masters) -> {ok,[FC]} -> FC; {error,Error1} -> - io:format("Warning: ~w can not read ~p: ~p~n", + io:format("Warning: ~w can not read ~tp: ~tp~n", [?MODULE,FromFile,Error1]), [] end, @@ -1134,7 +1130,7 @@ new_emulator_make_hybrid_config(CurrentVsn,ToVsn,TmpVsn,RelDir,Masters) -> {ok,[ToConfig]} -> [lists:keyfind(App,1,ToConfig) || App <- [kernel,stdlib,sasl]]; {error,Error2} -> - io:format("Warning: ~w can not read ~p: ~p~n", + io:format("Warning: ~w can not read ~tp: ~tp~n", [?MODULE,ToFile,Error2]), [false,false,false] end, @@ -1143,8 +1139,9 @@ new_emulator_make_hybrid_config(CurrentVsn,ToVsn,TmpVsn,RelDir,Masters) -> Config2 = replace_config(stdlib,Config1,Stdlib), Config3 = replace_config(sasl,Config2,Sasl), - ConfigStr = io_lib:format("~p.~n",[Config3]), - write_file(TmpFile,ConfigStr,Masters). + ConfigStr = io_lib:format("%% ~s~n~tp.~n", + [epp:encoding_to_string(utf8),Config3]), + write_file(TmpFile,unicode:characters_to_binary(ConfigStr),Masters). %% Take the configuration for application App from the new config and %% insert in the old config. @@ -1807,7 +1804,7 @@ check_opt_file(FileName, Type, Masters) -> ok -> true; _Error -> - io:format("Warning: ~p missing (optional)~n", [FileName]), + io:format("Warning: ~tp missing (optional)~n", [FileName]), false end. @@ -1841,14 +1838,12 @@ do_check_file(Master, FileName, Type) -> %% by the user in another way, i.e. ignore this here. %%----------------------------------------------------------------- extract_rel_file(Rel, Tar, Root) -> - erl_tar:extract(Tar, [{files, [Rel]}, {cwd, Root}, compressed]). + _ = erl_tar:extract(Tar, [{files, [Rel]}, {cwd, Root}, compressed]). extract_tar(Root, Tar) -> case erl_tar:extract(Tar, [keep_old_files, {cwd, Root}, compressed]) of ok -> ok; - {error, Reason, Name} -> % Old erl_tar. - throw({error, {cannot_extract_file, Name, Reason}}); {error, {Name, Reason}} -> % New erl_tar (R3A). throw({error, {cannot_extract_file, Name, Reason}}) end. @@ -1876,9 +1871,10 @@ write_releases_1(Dir, NewReleases, Masters) -> write_releases_m(Dir, NewReleases, Masters). do_write_release(Dir, RELEASES, NewReleases) -> - case file:open(filename:join(Dir, RELEASES), [write]) of + case file:open(filename:join(Dir, RELEASES), [write,{encoding,utf8}]) of {ok, Fd} -> - ok = io:format(Fd, "~p.~n", [NewReleases]), + ok = io:format(Fd, "%% ~s~n~tp.~n", + [epp:encoding_to_string(utf8),NewReleases]), ok = file:close(Fd); {error, Reason} -> {error, Reason} diff --git a/lib/sasl/src/release_handler_1.erl b/lib/sasl/src/release_handler_1.erl index 536ac924d4..ca97515299 100644 --- a/lib/sasl/src/release_handler_1.erl +++ b/lib/sasl/src/release_handler_1.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2013. All Rights Reserved. +%% Copyright Ericsson AB 1996-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -587,12 +587,12 @@ get_supervised_procs() -> get_application_names()). get_supervised_procs(_, Root, Procs, {ok, SupMod}) -> - get_procs(maybe_supervisor_which_children(get_proc_state(Root), SupMod, Root), Root) ++ + get_procs(maybe_supervisor_which_children(Root, SupMod, Root), Root) ++ [{undefined, undefined, Root, [SupMod]} | Procs]; get_supervised_procs(Application, Root, Procs, {error, _}) -> error_logger:error_msg("release_handler: cannot find top supervisor for " "application ~w~n", [Application]), - get_procs(maybe_supervisor_which_children(get_proc_state(Root), Application, Root), Root) ++ Procs. + get_procs(maybe_supervisor_which_children(Root, Application, Root), Root) ++ Procs. get_application_names() -> lists:map(fun({Application, _Name, _Vsn}) -> @@ -613,33 +613,54 @@ get_procs([{Name, Pid, worker, Mods} | T], Sup) when is_pid(Pid), is_list(Mods) [{Sup, Name, Pid, Mods} | get_procs(T, Sup)]; get_procs([{Name, Pid, supervisor, Mods} | T], Sup) when is_pid(Pid) -> [{Sup, Name, Pid, Mods} | get_procs(T, Sup)] ++ - get_procs(maybe_supervisor_which_children(get_proc_state(Pid), Name, Pid), Pid); + get_procs(maybe_supervisor_which_children(Pid, Name, Pid), Pid); get_procs([_H | T], Sup) -> get_procs(T, Sup); get_procs(_, _Sup) -> []. +maybe_supervisor_which_children(Proc, Name, Pid) -> + case get_proc_state(Proc) of + noproc -> + %% process exited before we could interrogate it. + %% not necessarily a bug, but reporting a warning as a curiosity. + error_logger:warning_msg("release_handler: a process (~p) exited" + " during supervision tree interrogation." + " Continuing ...~n", [Proc]), + []; + + suspended -> + error_logger:error_msg("release_handler: a which_children call" + " to ~p (~w) was avoided. This supervisor" + " is suspended and should likely be upgraded" + " differently. Exiting ...~n", [Name, Pid]), + error(suspended_supervisor); + + running -> + case catch supervisor:which_children(Pid) of + Res when is_list(Res) -> + Res; + Other -> + error_logger:error_msg("release_handler: ~p~nerror during" + " a which_children call to ~p (~w)." + " [State: running] Exiting ... ~n", + [Other, Name, Pid]), + error(which_children_failed) + end + end. + get_proc_state(Proc) -> - {status, _, {module, _}, [_, State, _, _, _]} = sys:get_status(Proc), - State. - -maybe_supervisor_which_children(suspended, Name, Pid) -> - error_logger:error_msg("release_handler: a which_children call" - " to ~p (~w) was avoided. This supervisor" - " is suspended and should likely be upgraded" - " differently. Exiting ...~n", [Name, Pid]), - error(suspended_supervisor); - -maybe_supervisor_which_children(State, Name, Pid) -> - case catch supervisor:which_children(Pid) of - Res when is_list(Res) -> - Res; - Other -> - error_logger:error_msg("release_handler: ~p~nerror during" - " a which_children call to ~p (~w)." - " [State: ~p] Exiting ... ~n", - [Other, Name, Pid, State]), - error(which_children_failed) + %% sys:send_system_msg can exit with {noproc, {m,f,a}}. + %% This happens if a supervisor exits after which_children has provided + %% its pid for interrogation. + %% ie. Proc may no longer be running at this point. + try sys:get_status(Proc) of + %% as per sys:get_status/1, SysState can only be running | suspended. + {status, _, {module, _}, [_, State, _, _, _]} when State == running ; + State == suspended -> + State + catch exit:{noproc, {sys, get_status, [Proc]}} -> + noproc end. maybe_get_dynamic_mods(Name, Pid) -> @@ -655,48 +676,19 @@ maybe_get_dynamic_mods(Name, Pid) -> error(get_modules_failed) end. -%% XXXX -%% Note: The following is a terrible hack done in order to resolve the -%% problem stated in ticket OTP-3452. - -%% XXXX NOTE WELL: This record is from supervisor.erl. Also the record -%% name is really `state'. --record(supervisor_state, {name, - strategy, - children = [], - dynamics = [], - intensity, - period, - restarts = [], - module, - args}). - %% Return the name of the call-back module that implements the %% (top) supervisor SupPid. %% Returns: {ok, Module} | {error,undefined} %% get_supervisor_module(SupPid) -> - case catch get_supervisor_module1(SupPid) of - {ok, Module} when is_atom(Module) -> + case catch supervisor:get_callback_module(SupPid) of + Module when is_atom(Module) -> {ok, Module}; _Other -> io:format("~w: reason: ~w~n", [SupPid, _Other]), {error, undefined} end. -get_supervisor_module1(SupPid) -> - {status, _Pid, {module, _Mod}, - [_PDict, _SysState, _Parent, _Dbg, Misc]} = sys:get_status(SupPid), - %% supervisor Misc field changed at R13B04, handle old and new variants here - State = case Misc of - [_Name, State1, _Type, _Time] -> - State1; - [_Header, _Data, {data, [{"State", State2}]}] -> - State2 - end, - %% Cannot use #supervisor_state{module = Module} = State. - {ok, element(#supervisor_state.module, State)}. - %%----------------------------------------------------------------- %% Func: do_soft_purge/3 %% Args: Mod = atom() diff --git a/lib/sasl/src/sasl.app.src b/lib/sasl/src/sasl.app.src index 7864e84773..b7bb9133ff 100644 --- a/lib/sasl/src/sasl.app.src +++ b/lib/sasl/src/sasl.app.src @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2010. All Rights Reserved. +%% Copyright Ericsson AB 1996-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -24,7 +24,6 @@ alarm_handler, format_lib_supp, misc_supp, - overload, rb, rb_format_supp, release_handler, @@ -41,11 +40,11 @@ systools_relup, systools_lib ]}, - {registered, [sasl_sup, alarm_handler, overload, release_handler]}, + {registered, [sasl_sup, alarm_handler, release_handler]}, {applications, [kernel, stdlib]}, {env, [{sasl_error_logger, tty}, {errlog_type, all}]}, {mod, {sasl, []}}, - {runtime_dependencies, ["tools-2.6.14","stdlib-2.0","kernel-3.0", - "erts-6.0"]}]}. + {runtime_dependencies, ["tools-2.6.14","stdlib-3.4","kernel-5.3", + "erts-9.0"]}]}. diff --git a/lib/sasl/src/sasl.appup.src b/lib/sasl/src/sasl.appup.src index eddb5a3fd0..0cef762bcf 100644 --- a/lib/sasl/src/sasl.appup.src +++ b/lib/sasl/src/sasl.appup.src @@ -1,7 +1,7 @@ %% -*- erlang -*- %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1999-2014. All Rights Reserved. +%% Copyright Ericsson AB 1999-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -18,7 +18,11 @@ %% %CopyrightEnd% {"%VSN%", %% Up from - max one major revision back - [{<<"2\\.4(\\.[0-9]+)*">>,[restart_new_emulator]}], % OTP-17 + [{<<"3\\.0((\\.[0-3])(\\.[0-9]+)*)?">>,[restart_new_emulator]}, % OTP-19.* + {<<"3\\.0\\.[4-9](\\.[0-9]+)*">>,[restart_new_emulator]}, % OTP-20.0* + {<<"3\\.1(\\.[0-2]+)*">>,[restart_new_emulator]}], % OTP-20.[1-3]* %% Down to - max one major revision back - [{<<"2\\.4(\\.[0-9]+)*">>,[restart_new_emulator]}] % OTP-17 + [{<<"3\\.0((\\.[0-3])(\\.[0-9]+)*)?">>,[restart_new_emulator]}, % OTP-19.* + {<<"3\\.0\\.[4-9](\\.[0-9]+)*">>,[restart_new_emulator]}, % OTP-20.0* + {<<"3\\.1(\\.[0-2]+)*">>,[restart_new_emulator]}] % OTP-20.[1-3]* }. diff --git a/lib/sasl/src/sasl.erl b/lib/sasl/src/sasl.erl index fc49fc2465..24afaee183 100644 --- a/lib/sasl/src/sasl.erl +++ b/lib/sasl/src/sasl.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2011. All Rights Reserved. +%% Copyright Ericsson AB 1996-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -170,7 +170,4 @@ init(safe) -> AlarmH = {alarm_handler, {alarm_handler, start_link, []}, permanent, 2000, worker, dynamic}, - Overload = {overload, - {overload, start_link, []}, - permanent, 2000, worker, [overload]}, - {ok, {SupFlags, [AlarmH, Overload]}}. + {ok, {SupFlags, [AlarmH]}}. diff --git a/lib/sasl/src/sasl_report.erl b/lib/sasl/src/sasl_report.erl index 1b1d432352..e6556ec6ce 100644 --- a/lib/sasl/src/sasl_report.erl +++ b/lib/sasl/src/sasl_report.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2010. All Rights Reserved. +%% Copyright Ericsson AB 1996-2017. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -47,6 +47,7 @@ io_report(_IO, _Fd, _, _) -> is_my_error_report(all, Type) -> is_my_error_report(Type); is_my_error_report(error, Type) -> is_my_error_report(Type); is_my_error_report(_, _Type) -> false. + is_my_error_report(supervisor_report) -> true; is_my_error_report(crash_report) -> true; is_my_error_report(_) -> false. @@ -54,6 +55,7 @@ is_my_error_report(_) -> false. is_my_info_report(all, Type) -> is_my_info_report(Type); is_my_info_report(progress, Type) -> is_my_info_report(Type); is_my_info_report(_, _Type) -> false. + is_my_info_report(progress) -> true; is_my_info_report(_) -> false. @@ -62,27 +64,64 @@ write_report2(IO, Fd, Head, supervisor_report, Report) -> Context = sup_get(errorContext, Report), Reason = sup_get(reason, Report), Offender = sup_get(offender, Report), - FmtString = " Supervisor: ~p~n Context: ~p~n Reason: " - "~80.18p~n Offender: ~80.18p~n~n", - write_report_action(IO, Fd, Head ++ FmtString, - [Name,Context,Reason,Offender]); + Enc = encoding(Fd), + {FmtString,Args} = supervisor_format([Name,Context,Reason,Offender], Enc), + String = io_lib:format(FmtString, Args), + write_report_action(IO, Fd, Head, String); write_report2(IO, Fd, Head, progress, Report) -> - Format = format_key_val(Report), - write_report_action(IO, Fd, Head ++ "~s", [Format]); + Encoding = encoding(Fd), + Depth = error_logger:get_format_depth(), + String = format_key_val(Report, Encoding, Depth), + write_report_action(IO, Fd, Head, String); write_report2(IO, Fd, Head, crash_report, Report) -> - Format = proc_lib:format(Report), - write_report_action(IO, Fd, Head ++ "~s", [Format]). + Encoding = encoding(Fd), + Depth = error_logger:get_format_depth(), + String = proc_lib:format(Report, Encoding, Depth), + write_report_action(IO, Fd, Head, String). + +supervisor_format(Args0, Encoding) -> + {P, Tl} = p(Encoding, error_logger:get_format_depth()), + [A,B,C,D] = Args0, + Args = [A|Tl] ++ [B|Tl] ++ [C|Tl] ++ [D|Tl], + {" Supervisor: ~" ++ P ++ "\n" + " Context: ~" ++ P ++ "\n" + " Reason: ~80.18" ++ P ++ "\n" + " Offender: ~80.18" ++ P ++ "\n~n", + Args}. + +write_report_action(IO, Fd, Head, String) -> + S = [Head|String], + case IO of + io -> io:put_chars(Fd, S); + io_lib -> S + end. -write_report_action(io, Fd, Format, Args) -> - io:format(Fd, Format, Args); -write_report_action(io_lib, _Fd, Format, Args) -> - io_lib:format(Format, Args). +format_key_val(Rep, Encoding, Depth) -> + {P, Tl} = p(Encoding, Depth), + format_key_val1(Rep, P, Tl). -format_key_val([{Tag,Data}|Rep]) -> - io_lib:format(" ~16w: ~p~n",[Tag,Data]) ++ format_key_val(Rep); -format_key_val(_) -> +format_key_val1([{Tag,Data}|Rep], P, Tl) -> + (io_lib:format(" ~16w: ~" ++ P ++ "\n", [Tag, Data|Tl]) ++ + format_key_val1(Rep, P, Tl)); +format_key_val1(_, _, _) -> []. +p(Encoding, Depth) -> + {Letter, Tl} = case Depth of + unlimited -> {"p", []}; + _ -> {"P", [Depth]} + end, + P = modifier(Encoding) ++ Letter, + {P, Tl}. + +encoding(IO) -> + case lists:keyfind(encoding, 1, io:getopts(IO)) of + false -> latin1; + {encoding, Enc} -> Enc + end. + +modifier(latin1) -> ""; +modifier(_) -> "t". sup_get(Tag, Report) -> case lists:keysearch(Tag, 1, Report) of diff --git a/lib/sasl/src/sasl_report_file_h.erl b/lib/sasl/src/sasl_report_file_h.erl index 6c38b320c1..d3b5c7dc0d 100644 --- a/lib/sasl/src/sasl_report_file_h.erl +++ b/lib/sasl/src/sasl_report_file_h.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2013. All Rights Reserved. +%% Copyright Ericsson AB 1996-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -29,15 +29,27 @@ handle_event/2, handle_call/2, handle_info/2, terminate/2]). -init({File, Modes, Type}) when is_list(Modes) -> +init({File, Modes0, Type}) when is_list(Modes0) -> process_flag(trap_exit, true), + Modes1 = + case lists:keymember(encoding,1,Modes0) of + true -> Modes0; + false -> [{encoding,utf8}|Modes0] + end, + Modes = + case [M || M <- Modes1, lists:member(M,[write,append,exclusive])] of + [] -> + [write|Modes1]; + _ -> + Modes1 + end, case file:open(File, Modes) of {ok,Fd} -> {ok, {Fd, File, Type}}; What -> What end. - + handle_event({_Type, GL, _Msg}, State) when node(GL) /= node() -> {ok, State}; handle_event(Event, {Fd, File, Type}) -> diff --git a/lib/sasl/src/sasl_report_tty_h.erl b/lib/sasl/src/sasl_report_tty_h.erl index 54e8addc45..3997e0aa97 100644 --- a/lib/sasl/src/sasl_report_tty_h.erl +++ b/lib/sasl/src/sasl_report_tty_h.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2013. All Rights Reserved. +%% Copyright Ericsson AB 1996-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. diff --git a/lib/sasl/src/si.erl b/lib/sasl/src/si.erl index e4bd8f5fd8..275c6d508b 100644 --- a/lib/sasl/src/si.erl +++ b/lib/sasl/src/si.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2013. All Rights Reserved. +%% Copyright Ericsson AB 1996-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. diff --git a/lib/sasl/src/si_sasl_supp.erl b/lib/sasl/src/si_sasl_supp.erl index 0dcdcdd912..cce628f8c4 100644 --- a/lib/sasl/src/si_sasl_supp.erl +++ b/lib/sasl/src/si_sasl_supp.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2013. All Rights Reserved. +%% Copyright Ericsson AB 1996-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. diff --git a/lib/sasl/src/systools.erl b/lib/sasl/src/systools.erl index 98255e0b12..dd1a58c3c1 100644 --- a/lib/sasl/src/systools.erl +++ b/lib/sasl/src/systools.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2009. All Rights Reserved. +%% Copyright Ericsson AB 1996-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. diff --git a/lib/sasl/src/systools.hrl b/lib/sasl/src/systools.hrl index 0bf822ed07..6b2a597427 100644 --- a/lib/sasl/src/systools.hrl +++ b/lib/sasl/src/systools.hrl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2012. All Rights Reserved. +%% Copyright Ericsson AB 1996-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. diff --git a/lib/sasl/src/systools_lib.erl b/lib/sasl/src/systools_lib.erl index 1538e1e90f..dd97aeff08 100644 --- a/lib/sasl/src/systools_lib.erl +++ b/lib/sasl/src/systools_lib.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2013. All Rights Reserved. +%% Copyright Ericsson AB 1996-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. diff --git a/lib/sasl/src/systools_make.erl b/lib/sasl/src/systools_make.erl index 8132034172..ffd5ecdf6d 100644 --- a/lib/sasl/src/systools_make.erl +++ b/lib/sasl/src/systools_make.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2013. All Rights Reserved. +%% Copyright Ericsson AB 1996-2017. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -32,7 +32,7 @@ -export([read_application/4]). --export([make_hybrid_boot/5]). +-export([make_hybrid_boot/4]). -import(lists, [filter/2, keysort/2, keysearch/3, map/2, reverse/1, append/1, foldl/3, member/2, foreach/2]). @@ -94,7 +94,11 @@ make_script(RelName, Output, Flags) when is_list(RelName), Warnings = wsasl(Flags, Warnings0), case systools_lib:werror(Flags, Warnings) of true -> - return(ok,Warnings,Flags); + Warnings1 = [W || {warning,W}<-Warnings], + return({error,?MODULE, + {warnings_treated_as_errors,Warnings1}}, + Warnings, + Flags); false -> case generate_script(Output,Release,Appls,Flags) of ok -> @@ -115,7 +119,6 @@ make_script(RelName, _Output, Flags) when is_list(Flags) -> make_script(RelName, _Output, Flags) -> badarg(Flags,[RelName, Flags]). - wsasl(Options, Warnings) -> case lists:member(no_warn_sasl,Options) of true -> lists:delete({warning,missing_sasl},Warnings); @@ -148,21 +151,10 @@ get_outdir(Flags) -> return(ok,Warnings,Flags) -> case member(silent,Flags) of true -> - case systools_lib:werror(Flags, Warnings) of - true -> - error; - false -> - {ok,?MODULE,Warnings} - end; + {ok,?MODULE,Warnings}; _ -> - case member(warnings_as_errors,Flags) of - true -> - io:format("~ts",[format_warning(Warnings, true)]), - error; - false -> - io:format("~ts",[format_warning(Warnings)]), - ok - end + io:format("~ts",[format_warning(Warnings)]), + ok end; return({error,Mod,Error},_,Flags) -> case member(silent,Flags) of @@ -186,94 +178,153 @@ return({error,Mod,Error},_,Flags) -> %% and sasl. %% %% TmpVsn = string(), -%% Paths = {KernelPath,StdlibPath,SaslPath} %% Returns {ok,Boot} | {error,Reason} %% Boot1 = Boot2 = Boot = binary() %% Reason = {app_not_found,App} | {app_not_replaced,App} -%% App = kernel | stdlib | sasl -make_hybrid_boot(TmpVsn, Boot1, Boot2, Paths, Args) -> - catch do_make_hybrid_boot(TmpVsn, Boot1, Boot2, Paths, Args). -do_make_hybrid_boot(TmpVsn, Boot1, Boot2, Paths, Args) -> - {script,{_RelName1,_RelVsn1},Script1} = binary_to_term(Boot1), - {script,{RelName2,_RelVsn2},Script2} = binary_to_term(Boot2), - MatchPaths = get_regexp_path(Paths), - NewScript1 = replace_paths(Script1,MatchPaths), - {Kernel,Stdlib,Sasl} = get_apps(Script2,undefined,undefined,undefined), - NewScript2 = replace_apps(NewScript1,Kernel,Stdlib,Sasl), - NewScript3 = add_apply_upgrade(NewScript2,Args), - Boot = term_to_binary({script,{RelName2,TmpVsn},NewScript3}), +%% App = stdlib | sasl +make_hybrid_boot(TmpVsn, Boot1, Boot2, Args) -> + catch do_make_hybrid_boot(TmpVsn, Boot1, Boot2, Args). +do_make_hybrid_boot(TmpVsn, OldBoot, NewBoot, Args) -> + {script,{_RelName1,_RelVsn1},OldScript} = binary_to_term(OldBoot), + {script,{NewRelName,_RelVsn2},NewScript} = binary_to_term(NewBoot), + + %% Everyting upto kernel_load_completed must come from the new script + Fun1 = fun({progress,kernel_load_completed}) -> false; + (_) -> true + end, + {_OldKernelLoad,OldRest1} = lists:splitwith(Fun1,OldScript), + {NewKernelLoad,NewRest1} = lists:splitwith(Fun1,NewScript), + + Fun2 = fun({progress,modules_loaded}) -> false; + (_) -> true + end, + {OldModLoad,OldRest2} = lists:splitwith(Fun2,OldRest1), + {NewModLoad,NewRest2} = lists:splitwith(Fun2,NewRest1), + + Fun3 = fun({kernelProcess,_,_}) -> false; + (_) -> true + end, + {OldPaths,OldRest3} = lists:splitwith(Fun3,OldRest2), + {NewPaths,NewRest3} = lists:splitwith(Fun3,NewRest2), + + Fun4 = fun({progress,init_kernel_started}) -> false; + (_) -> true + end, + {_OldKernelProcs,OldApps} = lists:splitwith(Fun4,OldRest3), + {NewKernelProcs,NewApps} = lists:splitwith(Fun4,NewRest3), + + %% Then comes all module load, which for each app consist of: + %% {path,[AppPath]}, + %% {primLoad,ModuleList} + %% Replace kernel, stdlib and sasl here + MatchPaths = get_regexp_path(), + ModLoad = replace_module_load(OldModLoad,NewModLoad,MatchPaths), + Paths = replace_paths(OldPaths,NewPaths,MatchPaths), + + {Stdlib,Sasl} = get_apps(NewApps,undefined,undefined), + Apps0 = replace_apps(OldApps,Stdlib,Sasl), + Apps = add_apply_upgrade(Apps0,Args), + + Script = NewKernelLoad++ModLoad++Paths++NewKernelProcs++Apps, + Boot = term_to_binary({script,{NewRelName,TmpVsn},Script}), {ok,Boot}. %% For each app, compile a regexp that can be used for finding its path -get_regexp_path({KernelPath,StdlibPath,SaslPath}) -> +get_regexp_path() -> {ok,KernelMP} = re:compile("kernel-[0-9\.]+",[unicode]), {ok,StdlibMP} = re:compile("stdlib-[0-9\.]+",[unicode]), {ok,SaslMP} = re:compile("sasl-[0-9\.]+",[unicode]), - [{KernelMP,KernelPath},{StdlibMP,StdlibPath},{SaslMP,SaslPath}]. - -%% For each path in the script, check if it matches any of the MPs -%% found above, and if so replace it with the correct new path. -replace_paths([{path,Path}|Script],MatchPaths) -> - [{path,replace_path(Path,MatchPaths)}|replace_paths(Script,MatchPaths)]; -replace_paths([Stuff|Script],MatchPaths) -> - [Stuff|replace_paths(Script,MatchPaths)]; -replace_paths([],_) -> + [KernelMP,StdlibMP,SaslMP]. + +replace_module_load(Old,New,[MP|MatchPaths]) -> + replace_module_load(do_replace_module_load(Old,New,MP),New,MatchPaths); +replace_module_load(Script,_,[]) -> + Script. + +do_replace_module_load([{path,[OldAppPath]},{primLoad,OldMods}|OldRest],New,MP) -> + case re:run(OldAppPath,MP,[{capture,none}]) of + nomatch -> + [{path,[OldAppPath]},{primLoad,OldMods}| + do_replace_module_load(OldRest,New,MP)]; + match -> + get_module_load(New,MP) ++ OldRest + end; +do_replace_module_load([Other|Rest],New,MP) -> + [Other|do_replace_module_load(Rest,New,MP)]; +do_replace_module_load([],_,_) -> []. -replace_path([Path|Paths],MatchPaths) -> - [do_replace_path(Path,MatchPaths)|replace_path(Paths,MatchPaths)]; -replace_path([],_) -> +get_module_load([{path,[AppPath]},{primLoad,Mods}|Rest],MP) -> + case re:run(AppPath,MP,[{capture,none}]) of + nomatch -> + get_module_load(Rest,MP); + match -> + [{path,[AppPath]},{primLoad,Mods}] + end; +get_module_load([_|Rest],MP) -> + get_module_load(Rest,MP); +get_module_load([],_) -> + []. + +replace_paths([{path,OldPaths}|Old],New,MatchPaths) -> + {path,NewPath} = lists:keyfind(path,1,New), + [{path,do_replace_paths(OldPaths,NewPath,MatchPaths)}|Old]; +replace_paths([Other|Old],New,MatchPaths) -> + [Other|replace_paths(Old,New,MatchPaths)]. + +do_replace_paths(Old,New,[MP|MatchPaths]) -> + do_replace_paths(do_replace_paths1(Old,New,MP),New,MatchPaths); +do_replace_paths(Paths,_,[]) -> + Paths. + +do_replace_paths1([P|Ps],New,MP) -> + case re:run(P,MP,[{capture,none}]) of + nomatch -> + [P|do_replace_paths1(Ps,New,MP)]; + match -> + get_path(New,MP) ++ Ps + end; +do_replace_paths1([],_,_) -> []. -do_replace_path(Path,[{MP,ReplacePath}|MatchPaths]) -> - case re:run(Path,MP,[{capture,none}]) of - nomatch -> do_replace_path(Path,MatchPaths); - match -> ReplacePath +get_path([P|Ps],MP) -> + case re:run(P,MP,[{capture,none}]) of + nomatch -> + get_path(Ps,MP); + match -> + [P] end; -do_replace_path(Path,[]) -> - Path. - -%% Return the entries for loading the three base applications -get_apps([{kernelProcess,application_controller, - {application_controller,start,[{application,kernel,_}]}}=Kernel| - Script],_,Stdlib,Sasl) -> - get_apps(Script,Kernel,Stdlib,Sasl); +get_path([],_) -> + []. + + +%% Return the entries for loading stdlib and sasl get_apps([{apply,{application,load,[{application,stdlib,_}]}}=Stdlib|Script], - Kernel,_,Sasl) -> - get_apps(Script,Kernel,Stdlib,Sasl); + _,Sasl) -> + get_apps(Script,Stdlib,Sasl); get_apps([{apply,{application,load,[{application,sasl,_}]}}=Sasl|_Script], - Kernel,Stdlib,_) -> - {Kernel,Stdlib,Sasl}; -get_apps([_|Script],Kernel,Stdlib,Sasl) -> - get_apps(Script,Kernel,Stdlib,Sasl); -get_apps([],undefined,_,_) -> - throw({error,{app_not_found,kernel}}); -get_apps([],_,undefined,_) -> + Stdlib,_) -> + {Stdlib,Sasl}; +get_apps([_|Script],Stdlib,Sasl) -> + get_apps(Script,Stdlib,Sasl); +get_apps([],undefined,_) -> throw({error,{app_not_found,stdlib}}); -get_apps([],_,_,undefined) -> +get_apps([],_,undefined) -> throw({error,{app_not_found,sasl}}). - -%% Replace the entries for loading the base applications -replace_apps([{kernelProcess,application_controller, - {application_controller,start,[{application,kernel,_}]}}| - Script],Kernel,Stdlib,Sasl) -> - [Kernel|replace_apps(Script,undefined,Stdlib,Sasl)]; +%% Replace the entries for loading the stdlib and sasl replace_apps([{apply,{application,load,[{application,stdlib,_}]}}|Script], - Kernel,Stdlib,Sasl) -> - [Stdlib|replace_apps(Script,Kernel,undefined,Sasl)]; + Stdlib,Sasl) -> + [Stdlib|replace_apps(Script,undefined,Sasl)]; replace_apps([{apply,{application,load,[{application,sasl,_}]}}|Script], - _Kernel,_Stdlib,Sasl) -> + _Stdlib,Sasl) -> [Sasl|Script]; -replace_apps([Stuff|Script],Kernel,Stdlib,Sasl) -> - [Stuff|replace_apps(Script,Kernel,Stdlib,Sasl)]; -replace_apps([],undefined,undefined,_) -> +replace_apps([Stuff|Script],Stdlib,Sasl) -> + [Stuff|replace_apps(Script,Stdlib,Sasl)]; +replace_apps([],undefined,_) -> throw({error,{app_not_replaced,sasl}}); -replace_apps([],undefined,_,_) -> - throw({error,{app_not_replaced,stdlib}}); -replace_apps([],_,_,_) -> - throw({error,{app_not_replaced,kernel}}). - +replace_apps([],_,_) -> + throw({error,{app_not_replaced,stdlib}}). %% Finally add an apply of release_handler:new_emulator_upgrade - which will %% complete the execution of the upgrade script (relup). @@ -283,8 +334,6 @@ add_apply_upgrade(Script,Args) -> {apply,{release_handler,new_emulator_upgrade,Args}} | RevScript]). - - %%----------------------------------------------------------------- %% Create a release package from a release file. %% Options is a list of {path, Path} | silent | @@ -300,6 +349,8 @@ add_apply_upgrade(Script,Args) -> %% {variables,[{Name,AbsString}]} %% {machine, jam | beam | vee} %% {var_tar, include | ownfile | omit} +%% no_warn_sasl +%% warnings_as_errors %% %% The tar file contains: %% lib/App-Vsn/ebin @@ -332,13 +383,23 @@ make_tar(RelName, Flags) when is_list(RelName), is_list(Flags) -> Path = make_set(Path1 ++ code:get_path()), ModTestP = {member(src_tests, Flags),xref_p(Flags)}, case get_release(RelName, Path, ModTestP, machine(Flags)) of - {ok, Release, Appls, Warnings} -> - case catch mk_tar(RelName, Release, Appls, Flags, Path1) of - ok -> - return(ok,Warnings,Flags); - Error -> - return(Error,Warnings,Flags) - end; + {ok, Release, Appls, Warnings0} -> + Warnings = wsasl(Flags, Warnings0), + case systools_lib:werror(Flags, Warnings) of + true -> + Warnings1 = [W || {warning,W}<-Warnings], + return({error,?MODULE, + {warnings_treated_as_errors,Warnings1}}, + Warnings, + Flags); + false -> + case catch mk_tar(RelName, Release, Appls, Flags, Path1) of + ok -> + return(ok,Warnings,Flags); + Error -> + return(Error,Warnings,Flags) + end + end; Error -> return(Error,[],Flags) end; @@ -643,6 +704,8 @@ get_items([], _Dict) -> check_item({_,{mod,{M,A}}},_) when is_atom(M) -> {M,A}; +check_item({_,{mod,[]}},_) -> % default mod is [], so accept as entry + []; check_item({_,{vsn,Vsn}},I) -> case string_p(Vsn) of true -> Vsn; @@ -678,6 +741,8 @@ check_item({_,{modules,Mods}},I) -> true -> Mods; _ -> throw({bad_param, I}) end; +check_item({_,{start_phases,undefined}},_) -> % default start_phase is undefined, + undefined; % so accept as entry check_item({_,{start_phases,Phase}},I) -> case t_list_p(Phase) of true -> Phase; @@ -1144,10 +1209,10 @@ generate_script(Output, Release, Appls, Flags) -> }, ScriptFile = Output ++ ".script", - case file:open(ScriptFile, [write]) of + case file:open(ScriptFile, [write,{encoding,utf8}]) of {ok, Fd} -> - io:format(Fd, "%% script generated at ~w ~w\n~p.\n", - [date(), time(), Script]), + io:format(Fd, "%% ~s\n%% script generated at ~w ~w\n~tp.\n", + [epp:encoding_to_string(utf8), date(), time(), Script]), case file:close(Fd) of ok -> BootFile = Output ++ ".boot", @@ -1453,23 +1518,47 @@ behave([H|T]) -> behave([]) -> []. -%%______________________________________________________________________ -%% mandatory modules; this modules must be loaded before processes -%% can be started. These are a collection of modules from the kernel -%% and stdlib applications. -%% Nowadays, error_handler dynamically loads almost every module. -%% The error_handler self must still be there though. - mandatory_modules() -> - %% Sorted - [error_handler]. + [error_handler, %Truly mandatory. + + %% Modules that are almost always needed. Listing them here + %% helps the init module to load them faster. Modules not + %% listed here will be loaded by the error_handler module. + %% + %% Keep this list sorted. + application, + application_controller, + application_master, + code, + code_server, + erl_eval, + erl_lint, + erl_parse, + error_logger, + ets, + file, + filename, + file_server, + file_io_server, + gen, + gen_event, + gen_server, + heart, + kernel, + lists, + proc_lib, + supervisor + ]. %%______________________________________________________________________ %% This is the modules that are preloaded into the Erlang system. preloaded() -> %% Sorted - [erl_prim_loader,erlang,erts_internal,init,otp_ring0,prim_eval,prim_file, + [erl_prim_loader,erl_tracer,erlang, + erts_code_purger,erts_dirty_process_code_checker, + erts_internal,erts_literal_area_collector, + init,otp_ring0,prim_eval,prim_file, prim_inet,prim_zip,zlib]. %%______________________________________________________________________ @@ -1876,8 +1965,10 @@ del_tar(Tar, TarName) -> file:delete(TarName). add_to_tar(Tar, FromFile, ToFile) -> - case erl_tar:add(Tar, FromFile, ToFile, [compressed, dereference]) of + case catch erl_tar:add(Tar, FromFile, ToFile, [compressed, dereference]) of ok -> ok; + {'EXIT', Reason} -> + throw({error, {tar_error, {add, FromFile, Reason}}}); {error, Error} -> throw({error, {tar_error, {add, FromFile, Error}}}) end. @@ -2085,90 +2176,80 @@ cas([Y | Args], X) -> %% Check Options for make_tar check_args_tar(Args) -> - cat(Args, {undef, undef, undef, undef, undef, undef, undef, undef, undef, undef, []}). + cat(Args, []). -cat([], {_Path,_Sil,_Dirs,_Erts,_Test,_Var,_VarTar,_Mach,_Xref,_XrefApps, X}) -> +cat([], X) -> X; %%% path --------------------------------------------------------------- -cat([{path, P} | Args], {Path, Sil, Dirs, Erts, Test, - Var, VarTar, Mach, Xref, XrefApps, X}) when is_list(P) -> +cat([{path, P} | Args], X) when is_list(P) -> case check_path(P) of ok -> - cat(Args, {P, Sil, Dirs, Erts, Test, Var, VarTar, Mach, Xref, XrefApps, X}); + cat(Args, X); error -> - cat(Args, {Path, Sil, Dirs, Erts, Test, - Var, VarTar, Mach, Xref, XrefApps, X++[{path,P}]}) + cat(Args, X++[{path,P}]) end; %%% silent ------------------------------------------------------------- -cat([silent | Args], {Path, _Sil, Dirs, Erts, Test, Var, VarTar, Mach, Xref, XrefApps, X}) -> - cat(Args, {Path, silent, Dirs, Erts, Test, Var, VarTar, Mach, Xref, XrefApps, X}); +cat([silent | Args], X) -> + cat(Args, X); %%% dirs --------------------------------------------------------------- -cat([{dirs, D} | Args], {Path, Sil, Dirs, Erts, Test, - Var, VarTar, Mach, Xref, XrefApps, X}) -> +cat([{dirs, D} | Args], X) -> case check_dirs(D) of ok -> - cat(Args, {Path, Sil, D, Erts, Test, Var, VarTar, Mach, Xref, XrefApps, X}); + cat(Args, X); error -> - cat(Args, {Path, Sil, Dirs, Erts, Test, - Var, VarTar, Mach, Xref, XrefApps, X++[{dirs, D}]}) + cat(Args, X++[{dirs, D}]) end; %%% erts --------------------------------------------------------------- -cat([{erts, E} | Args], {Path, Sil, Dirs, _Erts, Test, - Var, VarTar, Mach, Xref, XrefApps, X}) when is_list(E)-> - cat(Args, {Path, Sil, Dirs, E, Test, Var, VarTar, Mach, Xref, XrefApps, X}); +cat([{erts, E} | Args], X) when is_list(E)-> + cat(Args, X); %%% src_tests ---------------------------------------------------- -cat([src_tests | Args], {Path, Sil, Dirs, Erts, _Test, Var, VarTar, Mach, Xref, XrefApps, X}) -> - cat(Args, {Path, Sil, Dirs, Erts, src_tests, Var, VarTar, Mach, - Xref, XrefApps, X}); +cat([src_tests | Args], X) -> + cat(Args, X); %%% variables ---------------------------------------------------------- -cat([{variables, V} | Args], {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, Xref, XrefApps, X}) when is_list(V) -> +cat([{variables, V} | Args], X) when is_list(V) -> case check_vars(V) of ok -> - cat(Args, {Path, Sil, Dirs, Erts, Test, V, VarTar, Mach, Xref, XrefApps, X}); + cat(Args, X); error -> - cat(Args, {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, - Xref, XrefApps, X++[{variables, V}]}) + cat(Args, X++[{variables, V}]) end; %%% var_tar ------------------------------------------------------------ -cat([{var_tar, VT} | Args], {Path, Sil, Dirs, Erts, Test, - Var, _VarTar, Mach, Xref, XrefApps, X}) when VT == include -> - cat(Args, {Path, Sil, Dirs, Erts, Test, Var, include, Mach, Xref, XrefApps, X}); -cat([{var_tar, VT} | Args], {Path, Sil, Dirs, Erts, Test, - Var, _VarTar, Mach, Xref, XrefApps, X}) when VT == ownfile -> - cat(Args, {Path, Sil, Dirs, Erts, Test, Var, ownfile, Mach, Xref, XrefApps, X}); -cat([{var_tar, VT} | Args], {Path, Sil, Dirs, Erts, Test, - Var, _VarTar, Mach, Xref, XrefApps, X}) when VT == omit -> - cat(Args, {Path, Sil, Dirs, Erts, Test, Var, omit, Mach, Xref, XrefApps, X}); +cat([{var_tar, VT} | Args], X) when VT == include; + VT == ownfile; + VT == omit -> + cat(Args, X); %%% machine ------------------------------------------------------------ -cat([{machine, M} | Args], {Path, Sil, Dirs, Erts, Test, - Var, VarTar, Mach, Xref, XrefApps, X}) when is_atom(M) -> - cat(Args, {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, Xref, XrefApps, X}); +cat([{machine, M} | Args], X) when is_atom(M) -> + cat(Args, X); %%% exref -------------------------------------------------------------- -cat([exref | Args], {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, _Xref, XrefApps, X}) -> - cat(Args, {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, exref, XrefApps, X}); +cat([exref | Args], X) -> + cat(Args, X); %%% exref Apps --------------------------------------------------------- -cat([{exref, Apps} | Args], {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, Xref, XrefApps, X}) when is_list(Apps) -> +cat([{exref, Apps} | Args], X) when is_list(Apps) -> case check_apps(Apps) of ok -> - cat(Args, {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, - Xref, Apps, X}); + cat(Args, X); error -> - cat(Args, {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, - Xref, XrefApps, X++[{exref, Apps}]}) + cat(Args, X++[{exref, Apps}]) end; %%% outdir Dir --------------------------------------------------------- -cat([{outdir, Dir} | Args], {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, Xref, XrefApps, X}) when is_list(Dir) -> - cat(Args, {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, - Xref, XrefApps, X}); +cat([{outdir, Dir} | Args], X) when is_list(Dir) -> + cat(Args, X); %%% otp_build (secret, not documented) --------------------------------- -cat([otp_build | Args], {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, Xref, XrefApps, X}) -> - cat(Args, {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, Xref, XrefApps, X}); +cat([otp_build | Args], X) -> + cat(Args, X); +%%% warnings_as_errors ---- +cat([warnings_as_errors | Args], X) -> + cat(Args, X); +%%% no_warn_sasl ---- +cat([no_warn_sasl | Args], X) -> + cat(Args, X); %%% no_module_tests (kept for backwards compatibility, but ignored) ---- -cat([no_module_tests | Args], {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, Xref, XrefApps, X}) -> - cat(Args, {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, Xref, XrefApps, X}); +cat([no_module_tests | Args], X) -> + cat(Args, X); %%% ERROR -------------------------------------------------------------- -cat([Y | Args], {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, Xref, XrefApps, X}) -> - cat(Args, {Path, Sil, Dirs, Erts, Test, Var, VarTar, Mach, Xref, XrefApps, X++[Y]}). +cat([Y | Args], X) -> + cat(Args, X++[Y]). check_path([]) -> ok; @@ -2210,9 +2291,9 @@ check_apps(_) -> format_error(badly_formatted_release) -> io_lib:format("Syntax error in the release file~n",[]); format_error({illegal_name, Name}) -> - io_lib:format("Illegal name (~p) in the release file~n",[Name]); + io_lib:format("Illegal name (~tp) in the release file~n",[Name]); format_error({illegal_form, Form}) -> - io_lib:format("Illegal tag in the release file: ~p~n",[Form]); + io_lib:format("Illegal tag in the release file: ~tp~n",[Form]); format_error({missing_parameter,Par}) -> io_lib:format("Missing parameter (~p) in the release file~n",[Par]); format_error({illegal_applications,Names}) -> @@ -2227,7 +2308,7 @@ format_error({mandatory_app,Name,Type}) -> format_error({duplicate_register,Dups}) -> io_lib:format("Duplicated register names: ~n~ts", [map(fun({{Reg,App1,_,_},{Reg,App2,_,_}}) -> - io_lib:format("\t~w registered in ~w and ~w~n", + io_lib:format("\t~tw registered in ~w and ~w~n", [Reg,App1,App2]) end, Dups)]); format_error({undefined_applications,Apps}) -> @@ -2251,26 +2332,29 @@ format_error({modules,ModErrs}) -> format_error({circular_dependencies,Apps}) -> io_lib:format("Circular dependencies among applications: ~p~n",[Apps]); format_error({not_found,File}) -> - io_lib:format("File not found: ~p~n",[File]); + io_lib:format("File not found: ~tp~n",[File]); format_error({parse,File,{Line,Mod,What}}) -> Str = Mod:format_error(What), io_lib:format("~ts:~w: ~ts\n",[File, Line, Str]); format_error({read,File}) -> - io_lib:format("Cannot read ~p~n",[File]); + io_lib:format("Cannot read ~tp~n",[File]); format_error({open,File,Error}) -> - io_lib:format("Cannot open ~p - ~ts~n", + io_lib:format("Cannot open ~tp - ~ts~n", [File,file:format_error(Error)]); format_error({close,File,Error}) -> - io_lib:format("Cannot close ~p - ~ts~n", + io_lib:format("Cannot close ~tp - ~ts~n", [File,file:format_error(Error)]); format_error({delete,File,Error}) -> - io_lib:format("Cannot delete ~p - ~ts~n", + io_lib:format("Cannot delete ~tp - ~ts~n", [File,file:format_error(Error)]); format_error({tar_error,What}) -> form_tar_err(What); +format_error({warnings_treated_as_errors,Warnings}) -> + io_lib:format("Warnings being treated as errors:~n~ts", + [map(fun(W) -> form_warn("",W) end, Warnings)]); format_error(ListOfErrors) when is_list(ListOfErrors) -> format_errors(ListOfErrors); -format_error(E) -> io_lib:format("~p~n",[E]). +format_error(E) -> io_lib:format("~tp~n",[E]). format_errors(ListOfErrors) -> map(fun({error,E}) -> form_err(E); @@ -2286,19 +2370,19 @@ form_err({module_not_found,App,Mod}) -> form_err({error_add_appl, {Name, {tar_error, What}}}) -> io_lib:format("~p: ~ts~n",[Name,form_tar_err(What)]); form_err(E) -> - io_lib:format("~p~n",[E]). + io_lib:format("~tp~n",[E]). form_reading({not_found,File}) -> - io_lib:format("File not found: ~p~n",[File]); + io_lib:format("File not found: ~tp~n",[File]); form_reading({application_vsn, {Name,Vsn}}) -> - io_lib:format("Application ~ts with version ~p not found~n",[Name, Vsn]); + io_lib:format("Application ~ts with version ~tp not found~n",[Name, Vsn]); form_reading({parse,File,{Line,Mod,What}}) -> Str = Mod:format_error(What), io_lib:format("~ts:~w: ~ts\n",[File, Line, Str]); form_reading({read,File}) -> - io_lib:format("Cannot read ~p~n",[File]); + io_lib:format("Cannot read ~tp~n",[File]); form_reading({{bad_param, P},_}) -> - io_lib:format("Bad parameter in .app file: ~p~n",[P]); + io_lib:format("Bad parameter in .app file: ~tp~n",[P]); form_reading({{missing_param,P},_}) -> io_lib:format("Missing parameter in .app file: ~p~n",[P]); form_reading({badly_formatted_application,_}) -> @@ -2307,12 +2391,12 @@ form_reading({override_include,Apps}) -> io_lib:format("Tried to include not (in .app file) specified applications: ~p~n", [Apps]); form_reading({no_valid_version, {{_, SVsn}, {_, File, FVsn}}}) -> - io_lib:format("No valid version (~p) of .app file found. Found file ~p with version ~p~n", + io_lib:format("No valid version (~tp) of .app file found. Found file ~tp with version ~tp~n", [SVsn, File, FVsn]); form_reading({parse_error, {File, Line, Error}}) -> - io_lib:format("Parse error in file: ~p. Line: ~w Error: ~p; ~n", [File, Line, Error]); + io_lib:format("Parse error in file: ~tp. Line: ~w Error: ~tp; ~n", [File, Line, Error]); form_reading(W) -> - io_lib:format("~p~n",[W]). + io_lib:format("~tp~n",[W]). form_tar_err({open, File, Error}) -> io_lib:format("Cannot open tar file ~ts - ~ts~n", @@ -2324,35 +2408,26 @@ form_tar_err({add, File, Error}) -> %% Format warning format_warning(Warnings) -> - format_warning(Warnings, false). - -format_warning(Warnings, Werror) -> - Prefix = case Werror of - true -> - ""; - false -> - "*WARNING* " - end, - map(fun({warning,W}) -> form_warn(Prefix, W) end, Warnings). - -form_warn(Prefix, {source_not_found,{Mod,_,App,_,_}}) -> + map(fun({warning,W}) -> form_warn("*WARNING* ", W) end, Warnings). + +form_warn(Prefix, {source_not_found,{Mod,App,_}}) -> io_lib:format("~ts~w: Source code not found: ~w.erl~n", [Prefix,App,Mod]); form_warn(Prefix, {{parse_error, File},{_,_,App,_,_}}) -> - io_lib:format("~ts~w: Parse error: ~p~n", + io_lib:format("~ts~w: Parse error: ~tp~n", [Prefix,App,File]); -form_warn(Prefix, {obj_out_of_date,{Mod,_,App,_,_}}) -> +form_warn(Prefix, {obj_out_of_date,{Mod,App,_}}) -> io_lib:format("~ts~w: Object code (~w) out of date~n", [Prefix,App,Mod]); form_warn(Prefix, {exref_undef, Undef}) -> F = fun({M,F,A}) -> - io_lib:format("~tsUndefined function ~w:~w/~w~n", + io_lib:format("~tsUndefined function ~w:~tw/~w~n", [Prefix,M,F,A]) end, map(F, Undef); form_warn(Prefix, missing_sasl) -> - io_lib:format("~ts: Missing application sasl. " + io_lib:format("~tsMissing application sasl. " "Can not upgrade with this release~n", [Prefix]); form_warn(Prefix, What) -> - io_lib:format("~ts ~p~n", [Prefix,What]). + io_lib:format("~ts~tp~n", [Prefix,What]). diff --git a/lib/sasl/src/systools_rc.erl b/lib/sasl/src/systools_rc.erl index 285c805b5d..c570ed00ab 100644 --- a/lib/sasl/src/systools_rc.erl +++ b/lib/sasl/src/systools_rc.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2014. All Rights Reserved. +%% Copyright Ericsson AB 1996-2017. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -942,41 +942,41 @@ format_error(too_many_point_of_no_return) -> io_lib:format("Too many point_of_no_return~n", []); format_error({bad_instruction, X}) -> - io_lib:format("Bad instruction: ~p~n", [X]); + io_lib:format("Bad instruction: ~tp~n", [X]); format_error({bad_module, X}) -> - io_lib:format("Bad module: ~p(should be atom())~n", [X]); + io_lib:format("Bad module: ~tp(should be atom())~n", [X]); format_error({bad_code_change, X}) -> - io_lib:format("Bad code_change: ~p(should be {Mod, Extra})~n", [X]); + io_lib:format("Bad code_change: ~tp(should be {Mod, Extra})~n", [X]); format_error({bad_change, X}) -> - io_lib:format("Bad change spec: ~p(should be soft | {advanced, E})~n", [X]); + io_lib:format("Bad change spec: ~tp(should be soft | {advanced, E})~n", [X]); format_error({bad_mod_type, X}) -> - io_lib:format("Bad module type: ~p(should be static | dynamic)~n", [X]); + io_lib:format("Bad module type: ~tp(should be static | dynamic)~n", [X]); format_error({bad_purge_method, X}) -> - io_lib:format("Bad purge method: ~p(should be soft_purge | brutal_purge)~n", + io_lib:format("Bad purge method: ~tp(should be soft_purge | brutal_purge)~n", [X]); format_error({bad_list, X}) -> - io_lib:format("Bad list: ~p~n", [X]); + io_lib:format("Bad list: ~tp~n", [X]); format_error({bad_args_list, X}) -> - io_lib:format("Bad argument list: ~p~n", [X]); + io_lib:format("Bad argument list: ~tp~n", [X]); format_error({bad_node, X}) -> - io_lib:format("Bad node: ~p(should be atom())~n", [X]); + io_lib:format("Bad node: ~tp(should be atom())~n", [X]); format_error({bad_application, X}) -> - io_lib:format("Bad application: ~p(should be atom())~n", [X]); + io_lib:format("Bad application: ~tp(should be atom())~n", [X]); format_error({bad_func, X}) -> - io_lib:format("Bad function: ~p(should be atom())~n", [X]); + io_lib:format("Bad function: ~tp(should be atom())~n", [X]); format_error({bad_lib, X}) -> - io_lib:format("Bad library: ~p(should be atom())~n", [X]); + io_lib:format("Bad library: ~tp(should be atom())~n", [X]); format_error({bad_lib_vsn, X}) -> - io_lib:format("Bad library version: ~p(should be string())~n", [X]); + io_lib:format("Bad library version: ~tp(should be string())~n", [X]); format_error({bad_timeout, X}) -> - io_lib:format("Bad timeout: ~p(should be infinity | int() > 0)~n", [X]); + io_lib:format("Bad timeout: ~tp(should be infinity | int() > 0)~n", [X]); format_error({undef_module, Mod}) -> io_lib:format("Undefined module: ~p~n", [Mod]); format_error({muldef_module, Mod}) -> io_lib:format("Multiply defined module: ~p~n", [Mod]); format_error(E) -> - io_lib:format("~p~n",[E]). + io_lib:format("~tp~n",[E]). %%----------------------------------------------------------------- diff --git a/lib/sasl/src/systools_relup.erl b/lib/sasl/src/systools_relup.erl index a520da1c3f..e836d57670 100644 --- a/lib/sasl/src/systools_relup.erl +++ b/lib/sasl/src/systools_relup.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 1996-2013. All Rights Reserved. +%% Copyright Ericsson AB 1996-2017. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -155,36 +155,12 @@ mk_relup(TopRelFile, BaseUpRelDcs, BaseDnRelDcs) -> mk_relup(TopRelFile, BaseUpRelDcs, BaseDnRelDcs, Opts) -> case check_opts(Opts) of [] -> - R = (catch do_mk_relup(TopRelFile,BaseUpRelDcs,BaseDnRelDcs, - add_code_path(Opts), Opts)), - case {get_opt(silent, Opts), get_opt(noexec, Opts)} of - {false, false} -> - case R of - {ok, _Res, _Mod, Ws} -> - print_warnings(Ws, Opts), - case systools_lib:werror(Opts, Ws) of - true -> - error; - false -> - ok - end; - Other -> - print_error(Other), - error - end; - _ -> - case R of - {ok, _Res, _Mod, Ws} -> - case systools_lib:werror(Opts, Ws) of - true -> - error; - false -> - R - end; - R -> - R - end - end; + R = try do_mk_relup(TopRelFile,BaseUpRelDcs,BaseDnRelDcs, + add_code_path(Opts), Opts) + catch throw:Error -> + Error + end, + done_mk_relup(Opts, R); BadArg -> erlang:error({badarg, BadArg}) end. @@ -224,17 +200,45 @@ do_mk_relup(TopRelFile, BaseUpRelDcs, BaseDnRelDcs, Path, Opts) -> {Dn, Ws2} = foreach_baserel_dn(TopRel, TopApps, BaseDnRelDcs, Path, Opts, Ws1), Relup = {TopRel#release.vsn, Up, Dn}, - case systools_lib:werror(Opts, Ws2) of - true -> - ok; - false -> - write_relup_file(Relup, Opts) - end, - {ok, Relup, ?MODULE, Ws2}; + + {ok, Relup, Ws2}; Other -> - throw(Other) + Other end. +done_mk_relup(Opts, {ok,Relup,Ws}) -> + WAE = get_opt(warnings_as_errors,Opts), + Silent = get_opt(silent,Opts), + Noexec = get_opt(noexec,Opts), + + if WAE andalso Ws=/=[] -> + return_error(Silent, + {error,?MODULE,{warnings_treated_as_errors, Ws}}); + not Noexec -> + case write_relup_file(Relup,Opts) of + ok -> + return_ok(Silent,Relup,Ws); + Error -> + return_error(Silent,Error) + end; + true -> % noexec + return_ok(true,Relup,Ws) + end; +done_mk_relup(Opts, Error) -> + return_error(get_opt(silent,Opts) orelse get_opt(noexec,Opts), Error). + +return_error(true, Error) -> + Error; +return_error(false, Error) -> + print_error(Error), + error. + +return_ok(true,Relup,Ws) -> + {ok,Relup,?MODULE,Ws}; +return_ok(false,_Relup,Ws) -> + print_warnings(Ws), + ok. + %%----------------------------------------------------------------- %% foreach_baserel_up(Rel, TopApps, BaseRelDcs, Path, Opts, Ws) -> Ret %% foreach_baserel_dn(Rel, TopApps, BaseRelDcs, Path, Opts, Ws) -> Ret @@ -529,33 +533,18 @@ to_list(X) when is_list(X) -> X. %% Writes a relup file. %% write_relup_file(Relup, Opts) -> - case get_opt(noexec, Opts) of - true -> - ok; - _ -> - Filename = case get_opt(outdir, Opts) of - OutDir when is_list(OutDir) -> - filename:join(filename:absname(OutDir), - "relup"); - false -> - "relup"; - Badarg -> - throw({error, ?MODULE, {badarg, {outdir,Badarg}}}) - end, - - case file:open(Filename, [write]) of - {ok, Fd} -> - io:format(Fd, "~p.~n", [Relup]), - case file:close(Fd) of - ok -> ok; - {error,Reason} -> - throw({error, ?MODULE, - {file_problem, {"relup", {close,Reason}}}}) - end; - {error, Reason} -> - throw({error, ?MODULE, - {file_problem, {"relup", {open, Reason}}}}) - end + Filename = filename:join(filename:absname(get_opt(outdir,Opts)), + "relup"), + case file:open(Filename, [write,{encoding,utf8}]) of + {ok, Fd} -> + io:format(Fd, "%% ~s~n~tp.~n", [epp:encoding_to_string(utf8),Relup]), + case file:close(Fd) of + ok -> ok; + {error,Reason} -> + {error, ?MODULE, {file_problem, {"relup", {close,Reason}}}} + end; + {error, Reason} -> + {error, ?MODULE, {file_problem, {"relup", {open, Reason}}}} end. add_code_path(Opts) -> @@ -593,15 +582,14 @@ default(path) -> false; default(noexec) -> false; default(silent) -> false; default(restart_emulator) -> false; -default(outdir) -> false. +default(outdir) -> "."; +default(warnings_as_errors) -> false. -print_error({'EXIT', Err}) -> - print_error(Err); print_error({error, Mod, Error}) -> S = apply(Mod, format_error, [Error]), io:format(S, []); print_error(Other) -> - io:format("Error: ~p~n", [Other]). + io:format("Error: ~tp~n", [Other]). format_error({file_problem, {File, What}}) -> io_lib:format("Could not ~w file ~ts~n", [get_reason(What), File]); @@ -614,33 +602,31 @@ format_error({missing_sasl,Release}) -> io_lib:format("No sasl application in release ~ts, ~ts. " "Can not be upgraded.", [Release#release.name, Release#release.vsn]); +format_error({warnings_treated_as_errors, Warnings}) -> + io_lib:format("Warnings being treated as errors:~n~ts", + [[format_warning("",W) || W <- Warnings]]); format_error(Error) -> - io:format("~p~n", [Error]). + io_lib:format("~tp~n", [Error]). -print_warnings(Ws, Opts) when is_list(Ws) -> - lists:foreach(fun(W) -> print_warning(W, Opts) end, Ws); -print_warnings(W, Opts) -> - print_warning(W, Opts). +print_warnings(Ws) when is_list(Ws) -> + lists:foreach(fun(W) -> print_warning(W) end, Ws); +print_warnings(W) -> + print_warning(W). -print_warning(W, Opts) -> - Prefix = case lists:member(warnings_as_errors, Opts) of - true -> - ""; - false -> - "*WARNING* " - end, - S = format_warning(Prefix, W), - io:format("~ts", [S]). +print_warning(W) -> + io:format("~ts", [format_warning(W)]). format_warning(W) -> format_warning("*WARNING* ", W). format_warning(Prefix, {erts_vsn_changed, {Rel1, Rel2}}) -> - io_lib:format("~tsThe ERTS version changed between ~p and ~p~n", + io_lib:format("~tsThe ERTS version changed between ~tp and ~tp~n", [Prefix, Rel1, Rel2]); +format_warning(Prefix, pre_R15_emulator_upgrade) -> + io_lib:format("~tsUpgrade from an OTP version earlier than R15. New code should be compiled with the old emulator.~n",[Prefix]); format_warning(Prefix, What) -> - io_lib:format("~ts~p~n",[Prefix, What]). + io_lib:format("~ts~tp~n",[Prefix, What]). get_reason({error, {open, _, _}}) -> open; diff --git a/lib/sasl/test/Makefile b/lib/sasl/test/Makefile index 86fc57abfc..2a782bcf61 100644 --- a/lib/sasl/test/Makefile +++ b/lib/sasl/test/Makefile @@ -1,7 +1,7 @@ # # %CopyrightBegin% # -# Copyright Ericsson AB 2011-2012. All Rights Reserved. +# Copyright Ericsson AB 2011-2016. All Rights Reserved. # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -29,11 +29,12 @@ MODULES= \ alarm_handler_SUITE \ installer \ release_handler_SUITE \ + sasl_report_SUITE \ + sasl_report_suite_supervisor \ systools_SUITE \ systools_rc_SUITE \ - overload_SUITE \ rb_SUITE \ - rh_test_lib + rh_test_lib \ ERL_FILES= $(MODULES:%=%.erl) @@ -53,8 +54,7 @@ RELSYSDIR = $(RELEASE_PATH)/sasl_test # FLAGS # ---------------------------------------------------- ERL_MAKE_FLAGS += -ERL_COMPILE_FLAGS += -I$(ERL_TOP)/lib/test_server/include \ - -I$(ERL_TOP)/lib/sasl/src +ERL_COMPILE_FLAGS += -I$(ERL_TOP)/lib/sasl/src EBIN = . diff --git a/lib/sasl/test/alarm_handler_SUITE.erl b/lib/sasl/test/alarm_handler_SUITE.erl index f2ed9ffc19..dbbdf05f12 100644 --- a/lib/sasl/test/alarm_handler_SUITE.erl +++ b/lib/sasl/test/alarm_handler_SUITE.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2011. All Rights Reserved. +%% Copyright Ericsson AB 2011-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. diff --git a/lib/sasl/test/installer.erl b/lib/sasl/test/installer.erl index c42f26a506..e38d0cfa7b 100644 --- a/lib/sasl/test/installer.erl +++ b/lib/sasl/test/installer.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2011-2013. All Rights Reserved. +%% Copyright Ericsson AB 2011-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. diff --git a/lib/sasl/test/overload_SUITE.erl b/lib/sasl/test/overload_SUITE.erl deleted file mode 100644 index 02d1056698..0000000000 --- a/lib/sasl/test/overload_SUITE.erl +++ /dev/null @@ -1,168 +0,0 @@ -%% -%% %CopyrightBegin% -%% -%% Copyright Ericsson AB 2011. All Rights Reserved. -%% -%% Licensed under the Apache License, Version 2.0 (the "License"); -%% you may not use this file except in compliance with the License. -%% You may obtain a copy of the License at -%% -%% http://www.apache.org/licenses/LICENSE-2.0 -%% -%% Unless required by applicable law or agreed to in writing, software -%% distributed under the License is distributed on an "AS IS" BASIS, -%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -%% See the License for the specific language governing permissions and -%% limitations under the License. -%% -%% %CopyrightEnd% -%% - --module(overload_SUITE). --include_lib("common_test/include/ct.hrl"). - --compile(export_all). - -%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% - -all() -> [info, set_config_data, set_env_vars, request, timeout]. - -init_per_testcase(_Case,Config) -> - restart_sasl(), - Config. - -end_per_testcase(Case,Config) -> - try apply(?MODULE,Case,[cleanup,Config]) - catch error:undef -> ok - end, - ok. - -%%%----------------------------------------------------------------- -info(_Config) -> - Info = overload:get_overload_info(), - [{total_intensity,0.0}, - {accept_intensity,0.0}, - {max_intensity,0.8}, - {weight,0.1}, - {total_requests,0}, - {accepted_requests,0}] = Info. - -%%%----------------------------------------------------------------- -set_config_data(_Config) -> - InfoDefault = overload:get_overload_info(), - ok = check_info(0.8,0.1,InfoDefault), - ok = overload:set_config_data(0.5,0.4), - Info1 = overload:get_overload_info(), - ok = check_info(0.5,0.4,Info1), - ok. - -%%%----------------------------------------------------------------- -set_env_vars(_Config) -> - InfoDefault = overload:get_overload_info(), - ok = check_info(0.8,0.1,InfoDefault), - ok = application:set_env(sasl,overload_max_intensity,0.5), - ok = application:set_env(sasl,overload_weight,0.4), - ok = application:stop(sasl), - ok = application:start(sasl), - Info1 = overload:get_overload_info(), - ok = check_info(0.5,0.4,Info1), - ok. -set_env_vars(cleanup,_Config) -> - application:unset_env(sasl,overload_max_intensity), - application:unset_env(sasl,overload_weight), - ok. - -%%%----------------------------------------------------------------- -request(_Config) -> - %% Find number of request that can be done with default settings - %% and no delay - overload:set_config_data(0.8, 0.1), - NDefault = do_many_requests(0), - restart_sasl(), - ?t:format("NDefault: ~p",[NDefault]), - - %% Check that the number of requests increases when max_intensity - %% increases - overload:set_config_data(2, 0.1), - NLargeMI = do_many_requests(0), - restart_sasl(), - ?t:format("NLargeMI: ~p",[NLargeMI]), - true = NLargeMI > NDefault, - - %% Check that the number of requests decreases when weight - %% increases - overload:set_config_data(0.8, 1), - NLargeWeight = do_many_requests(0), - restart_sasl(), - ?t:format("NLargeWeight: ~p",[NLargeWeight]), - true = NLargeWeight < NDefault, - - %% Check that number of requests increases when delay between - %% requests increases. - %% (Keeping same config and comparing to large weight in order to - %% minimize the time needed for this case.) - overload:set_config_data(0.8, 1), - NLargeTime = do_many_requests(500), - restart_sasl(), - ?t:format("NLargeTime: ~p",[NLargeTime]), - true = NLargeTime > NLargeWeight, - ok. - -%%%----------------------------------------------------------------- -timeout(_Config) -> - overload:set_config_data(0.8, 1), - _N = do_many_requests(0), - - %% Check that the overload alarm is raised - [{overload,_}] = alarm_handler:get_alarms(), - - %% Fake a clear timeout in overload.erl and check that, since it - %% came very soon after the overload situation, the alarm is not - %% cleared - overload ! timeout, - timer:sleep(1000), - [{overload,_}] = alarm_handler:get_alarms(), - - %% A bit later, try again and check that this time the alarm is - %% cleared - overload ! timeout, - timer:sleep(1000), - [] = alarm_handler:get_alarms(), - - ok. - - -%%%----------------------------------------------------------------- -%%% INTERNAL FUNCTIONS - -%%%----------------------------------------------------------------- -%%% Call overload:request/0 up to 30 times with the given time delay -%%% between. Stop when 'reject' is returned. -do_many_requests(T) -> - 30 - do_requests(30,T). - -do_requests(0,_) -> - ?t:fail(never_rejected); -do_requests(N,T) -> - case overload:request() of - accept -> - timer:sleep(T), - do_requests(N-1,T); - reject -> - N - end. - -%%%----------------------------------------------------------------- -%%% Restart the sasl application -restart_sasl() -> - application:stop(sasl), - application:start(sasl), - ok. - -%%%----------------------------------------------------------------- -%%% Check that max_intensity and weight is set as expected -check_info(MI,W,Info) -> - case {lists:keyfind(max_intensity,1,Info), lists:keyfind(weight,1,Info)} of - {{_,MI},{_,W}} -> ok; - _ -> ?t:fail({unexpected_info,MI,W,Info}) - end. diff --git a/lib/sasl/test/rb_SUITE.erl b/lib/sasl/test/rb_SUITE.erl index 9a33df369e..4ba2540545 100644 --- a/lib/sasl/test/rb_SUITE.erl +++ b/lib/sasl/test/rb_SUITE.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2011-2012. All Rights Reserved. +%% Copyright Ericsson AB 2011-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -36,6 +36,7 @@ no_group_cases() -> groups() -> [{running_error_logger,[shuffle],[show, + show_other, list, rescan, start_stop_log, @@ -165,6 +166,23 @@ show(Config) -> ok. +show_other(Config) -> + PrivDir = ?config(priv_dir,Config), + OutFile = filename:join(PrivDir,"rb_SUITE_log.txt"), + + %% Insert some reports in the error log and start rb + error_logger:info_report([rb_test_term_in_list]), + error_logger:info_report(rb_test_term_no_list), + ok = start_rb(OutFile), + + %% Show by type and check content + [{_,I1},{_,I2}] = check_report(fun() -> rb:show(info_report) end,OutFile), + + true = contains(I1,"rb_test_term_no_list"), + true = contains(I2,"rb_test_term_in_list"), + + ok. + list(Config) -> PrivDir = ?config(priv_dir,Config), OutFile = filename:join(PrivDir,"rb_SUITE_log.txt"), diff --git a/lib/sasl/test/release_handler_SUITE.erl b/lib/sasl/test/release_handler_SUITE.erl index d57de2593a..50932e89e4 100644 --- a/lib/sasl/test/release_handler_SUITE.erl +++ b/lib/sasl/test/release_handler_SUITE.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2011-2015. All Rights Reserved. +%% Copyright Ericsson AB 2011-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -54,7 +54,7 @@ unix_cases() -> end, [target_system, target_system_unicode] ++ RunErlCases ++ cases(). -win32_cases() -> +win32_cases() -> [{group,release} | cases()]. %% Cases that can be run on all platforms @@ -66,7 +66,7 @@ cases() -> supervisor_which_children_timeout, release_handler_which_releases, install_release_syntax_check, upgrade_supervisor, upgrade_supervisor_fail, otp_9864, - otp_10463_upgrade_script_regexp, no_dot_erlang]. + otp_10463_upgrade_script_regexp, no_dot_erlang, unicode_upgrade]. groups() -> [{release,[], @@ -89,11 +89,16 @@ groups() -> %% {group,release} %% Top group for all cases using run_erl init_per_group(release, Config) -> - Dog = ?t:timetrap(?default_timeout), - P1gInstall = filename:join(priv_dir(Config),p1g_install), - ok = create_p1g(Config,P1gInstall), - ok = create_p1h(Config), - ?t:timetrap_cancel(Dog); + case {os:type(), os:version()} of + {{win32, nt}, Vsn} when Vsn > {6,1,999999} -> + {skip, "Requires admin privileges on Win 8 and later"}; + _ -> + Dog = ?t:timetrap(?default_timeout), + P1gInstall = filename:join(priv_dir(Config),p1g_install), + ok = create_p1g(Config,P1gInstall), + ok = create_p1h(Config), + ?t:timetrap_cancel(Dog) + end; %% {group,release_single} %% Subgroup of {group,release}, contains all cases that are not @@ -1058,6 +1063,12 @@ otp_9395_check_and_purge(cleanup,_Conf) -> %% OTP-9395 - performance problems when there are MANY processes %% Upgrade which updates many modules (brutal_purge) otp_9395_update_many_mods(Conf) when is_list(Conf) -> + + %% "nain" is very slow - it fails this test quite often due to a + %% long sys call + %% /proc/cpuinfo: "clock: 1249MHz" + inet:gethostname() == {ok,"nain"} andalso throw({skip,"slow test host"}), + %% Set some paths PrivDir = priv_dir(Conf), Dir = filename:join(PrivDir,"otp_9395_update_many_mods"), @@ -1098,6 +1109,7 @@ otp_9395_update_many_mods(Conf) when is_list(Conf) -> [RelVsn2, filename:join(Rel2Dir, "sys.config")]), %% First, install release directly and check how much time it takes + rpc:call(Node,erlang,garbage_collect,[]), rpc:call(Node,erlang,system_flag,[scheduler_wall_time,true]), {TInst0,{ok, _, []}} = timer:tc(rpc,call,[Node, release_handler, install_release, [RelVsn2]]), @@ -1124,6 +1136,7 @@ otp_9395_update_many_mods(Conf) when is_list(Conf) -> %% Finally install release after check and purge, and check that %% this install was faster than the first. rpc:call(Node,erlang,system_flag,[scheduler_wall_time,false]), + rpc:call(Node,erlang,garbage_collect,[]), rpc:call(Node,erlang,system_flag,[scheduler_wall_time,true]), {TInst2,{ok, _RelVsn1, []}} = timer:tc(rpc,call,[Node, release_handler, install_release, [RelVsn2]]), @@ -1155,6 +1168,12 @@ otp_9395_update_many_mods(cleanup,_Conf) -> %% OTP-9395 - performance problems when there are MANY processes %% Upgrade which removes many modules (brutal_purge) otp_9395_rm_many_mods(Conf) when is_list(Conf) -> + + %% "nain" is very slow - it fails this test quite often due to a + %% long sys call + %% /proc/cpuinfo: "clock: 1249MHz" + inet:gethostname() == {ok,"nain"} andalso throw({skip,"slow test host"}), + %% Set some paths PrivDir = priv_dir(Conf), Dir = filename:join(PrivDir,"otp_9395_rm_many_mods"), @@ -1195,6 +1214,7 @@ otp_9395_rm_many_mods(Conf) when is_list(Conf) -> [RelVsn2, filename:join(Rel2Dir, "sys.config")]), %% First, install release directly and check how much time it takes + rpc:call(Node,erlang,garbage_collect,[]), rpc:call(Node,erlang,system_flag,[scheduler_wall_time,true]), {TInst0,{ok, _, []}} = timer:tc(rpc,call,[Node, release_handler, install_release, [RelVsn2]]), @@ -1221,6 +1241,7 @@ otp_9395_rm_many_mods(Conf) when is_list(Conf) -> %% Finally install release after check and purge, and check that %% this install was faster than the first. rpc:call(Node,erlang,system_flag,[scheduler_wall_time,false]), + rpc:call(Node,erlang,garbage_collect,[]), rpc:call(Node,erlang,system_flag,[scheduler_wall_time,true]), {TInst2,{ok, _RelVsn1, []}} = timer:tc(rpc,call,[Node, release_handler, install_release, [RelVsn2]]), @@ -1361,9 +1382,9 @@ upgrade_supervisor(Conf) when is_list(Conf) -> ASupBeam2 = rpc:call(Node, code, which, [a_sup]), %% Check that the restart strategy and child spec is updated - {status, _, {module, _}, [_, _, _, _, [_,_,{data,[{"State",State}]}]]} = + {status, _, {module, _}, [_, _, _, _, [_,_,{data,[{"State",State}]}|_]]} = rpc:call(Node,sys,get_status,[a_sup]), - {state,_,RestartStrategy,[Child],_,_,_,_,_,_} = State, + {state,_,RestartStrategy,[Child],_,_,_,_,_,_,_} = State, one_for_all = RestartStrategy, % changed from one_for_one {child,_,_,_,_,brutal_kill,_,_} = Child, % changed from timeout 2000 @@ -1756,8 +1777,6 @@ upgrade_gg(Conf) -> Nodes1 = [Gg1,Gg3,Gg4,Gg5] = start_nodes(Conf,[Gg1Sname,Gg3Sname,Gg4Sname,Gg5Sname],"upgrade_gg"), - %% Give some time to synch nodes, then check global group info. - timer:sleep(1000), [check_gg_info(Node,Nodes1,[],Nodes1--[Node]) || Node <- Nodes1], %% register a process on each of the nodes @@ -1856,6 +1875,86 @@ no_dot_erlang(Conf) -> ok end. +%%%----------------------------------------------------------------- +%%% Test unicode handling. Make sure that release name, application +%%% description, and application environment variables may contain +%%% unicode characters. +unicode_upgrade(Conf) -> + %% Set some paths + DataDir = ?config(data_dir, Conf), + PrivDir = priv_dir(Conf), + Dir = filename:join(PrivDir,"unicode"), + LibDir0 = filename:join(DataDir, "unicode"), + LibDir = + case {file:native_name_encoding(),os:type()} of + {utf8,{Os,_}} when Os =/= win32 -> + LD = filename:join(DataDir,"unicode_αβ"), + file:make_symlink("unicode",LD), + LD; + _ -> + LibDir0 + end, + + %% Create the releases + RelName = "unicode_rel_αβ", + Rel1 = create_and_install_fake_first_release(Dir,{RelName,"1"}, + [{u,"1.0",LibDir}]), + Rel2 = create_fake_upgrade_release(Dir, + {RelName,"2"}, + [{u,"1.1",LibDir}], + {[Rel1],[Rel1],[LibDir]}), + Rel1Dir = filename:dirname(Rel1), + Rel2Dir = filename:dirname(Rel2), + + %% Start a slave node + {ok, Node} = t_start_node(unicode_upgrade, Rel1, + filename:join(Rel1Dir,"sys.config"), "+pc unicode"), + + %% Check + Dir1 = filename:join([LibDir, "u-1.0"]), + Dir1 = rpc:call(Node, code, lib_dir, [u]), + UBeam1 = filename:join([Dir1,"ebin","u.beam"]), + UBeam1 = rpc:call(Node,code,which,[u]), + {RelName,"1"} = rpc:call(Node,init,script_id,[]), + {Env,state} = rpc:call(Node,u,u,[]), + 'val_αβ' = proplists:get_value('key_αβ',Env), + [{RelName,"1",_,permanent}|_] = + rpc:call(Node,release_handler,which_releases,[]), + {ok,ReleasesDir} = rpc:call(Node,application,get_env,[sasl,releases_dir]), + {ok,[[{release,RelName,"1",_,_,permanent}|_]]} = + file:consult(filename:join(ReleasesDir,"RELEASES")), + + %% Install second release + {ok, RelVsn2} = + rpc:call(Node, release_handler, set_unpacked, + [Rel2++".rel", [{u,"1.1",LibDir}]]), + ok = rpc:call(Node, release_handler, install_file, + [RelVsn2, filename:join(Rel2Dir, "relup")]), + ok = rpc:call(Node, release_handler, install_file, + [RelVsn2, filename:join(Rel2Dir, "start.boot")]), + ok = rpc:call(Node, release_handler, install_file, + [RelVsn2, filename:join(Rel2Dir, "sys.config")]), + + {ok, _RelVsn1, []} = + rpc:call(Node, release_handler, install_release, [RelVsn2]), + + %% And check + Dir2 = filename:join([LibDir, "u-1.1"]), + Dir2 = rpc:call(Node, code, lib_dir, [u]), + UBeam2 = filename:join([Dir2,"ebin","u.beam"]), + {file,UBeam2} = rpc:call(Node,code,is_loaded,[u]), + {RelName,"1"} = rpc:call(Node,init,script_id,[]), + {Env,{state,'αβ'}} = rpc:call(Node,u,u,[]), + [{RelName,"2",_,current}|_] = + rpc:call(Node,release_handler,which_releases,[]), + {ok,ReleasesDir2} = rpc:call(Node,application,get_env,[sasl,releases_dir]), + {ok,<<"%% coding: utf-8\n[{release,\"unicode_rel_αβ\",\"2\""/utf8,_/binary>>}= + file:read_file(filename:join(ReleasesDir2,"RELEASES")), + ok. + +unicode_upgrade(cleanup,_Conf) -> + stop_node(node_name(unicode_upgrade)). + %%%================================================================= %%% Misceleaneous functions @@ -1913,7 +2012,7 @@ wait_nodes_up(Nodes, Tag) -> wait_nodes_up(Nodes0, Tag, Apps) -> ?t:format("wait_nodes_up(~p, ~p, ~p):",[Nodes0, Tag, Apps]), Nodes = fix_nodes(Nodes0), - wait_nodes_up(Nodes, Tag, lists:umerge(Apps,[kernel,stdlib,sasl]), 30). + wait_nodes_up(Nodes, Tag, lists:umerge(Apps,[kernel,stdlib,sasl]), 60). fix_nodes([{Node,InitPid}|Nodes]) -> [{Node,InitPid} | fix_nodes(Nodes)]; @@ -1955,7 +2054,7 @@ wait_nodes_up(Nodes, Tag, Apps, N) -> ?t:format("",[]), ok; _ -> - timer:sleep(1000), + timer:sleep(2000), wait_nodes_up(Pang, Tag, Apps, N-1) end. @@ -1983,6 +2082,8 @@ are_names_reg_gg(Node, Names, N) -> t_start_node(Name, Boot, SysConfig) -> + t_start_node(Name, Boot, SysConfig, ""). +t_start_node(Name, Boot, SysConfig, ArgStr) -> Args = case Boot of [] -> []; @@ -1991,8 +2092,9 @@ t_start_node(Name, Boot, SysConfig) -> case SysConfig of [] -> []; _ -> " -config " ++ SysConfig - end, - test_server:start_node(Name, slave, [{args, Args}]). + end ++ + " " ++ ArgStr, + test_server:start_node(Name, peer, [{args, Args}]). stop_node(Node) -> ?t:stop_node(Node). @@ -2441,40 +2543,32 @@ create_rel_file(RelFile,RelName,RelVsn,Erts,ExtraApps) -> %% Insert a term in a file, which can be read with file:consult/1. write_term_file(File,Term) -> - ok = file:write_file(File,io_lib:format("~p.~n",[Term])). + Str = io_lib:format("%% ~s~n~tp.~n",[epp:encoding_to_string(utf8),Term]), + Bin = unicode:characters_to_binary(Str), + ok = file:write_file(File,Bin). -%% Check that global group info is correct +%% Check that global group info is correct - try again for a maximum of 5 sec check_gg_info(Node,OtherAlive,OtherDead,Synced) -> + check_gg_info(Node,OtherAlive,OtherDead,Synced,5). + +check_gg_info(Node,OtherAlive,OtherDead,Synced,N) -> GGI = rpc:call(Node, global_group, info, []), GI = rpc:call(Node, global, info,[]), try do_check_gg_info(OtherAlive,OtherDead,Synced,GGI,GI) - catch _:E -> - ?t:format("~ncheck_gg_info failed for ~p: ~p~nwhen GGI was: ~p~n" - "and GI was: ~p~n", - [Node,E,GGI,GI]), - %% An attempt to find out if it is only a timing issue - %% that makes this fail every now and then: - try_again_check(Node,GGI,GI,1), - ?t:fail("check_gg_info failed") - end. - -try_again_check(_Node,_GGI,_GI,6) -> - ok; -try_again_check(Node,GGI,GI,N) -> - timer:sleep(1000), - case {rpc:call(Node,global_group,info,[]), - rpc:call(Node,global,info,[])} of - {GGI,GI} -> - ?t:format("~nAfter one more sek, GGI and GI are still the same"), - try_again_check(Node,GGI,GI,N+1); - {NewGGI,NewGI} -> - ?t:format("~nAfter one more sek:~nNew GGI: ~p~nNew GI: ~p~n", - [NewGGI,NewGI]), - try_again_check(Node,NewGGI,NewGI,N+1) + catch _:E when N==0 -> + ?t:format("~nERROR: check_gg_info failed for ~p:~n~p~n" + "when GGI was: ~p~nand GI was: ~p~n", + [Node,{E,erlang:get_stacktrace()},GGI,GI]), + ?t:fail("check_gg_info failed"); + _:E -> + ?t:format("~nWARNING: check_gg_info failed for ~p:~n~p~n" + "when GGI was: ~p~nand GI was: ~p~n", + [Node,{E,erlang:get_stacktrace()},GGI,GI]), + timer:sleep(1000), + check_gg_info(Node,OtherAlive,OtherDead,Synced,N-1) end. - do_check_gg_info(OtherAlive,OtherDead,Synced,GGI,GI) -> {_,gg1} = lists:keyfind(own_group_name,1,GGI), {_,synced} = lists:keyfind(state,1,GGI), @@ -2710,8 +2804,8 @@ cover_fun(Node,Func) -> %% and possibly other applications if they are listed in AppDirs = %% [{App,Vsn,LibDir}] create_and_install_fake_first_release(Dir,AppDirs) -> - %% Create the first release - {RelName,RelVsn} = init:script_id(), + create_and_install_fake_first_release(Dir,init:script_id(),AppDirs). +create_and_install_fake_first_release(Dir,{RelName,RelVsn},AppDirs) -> {Rel,_} = create_fake_release(Dir,RelName,RelVsn,AppDirs), ReleasesDir = filename:join(Dir, "releases"), RelDir = filename:dirname(Rel), @@ -2735,9 +2829,11 @@ create_and_install_fake_first_release(Dir,AppDirs) -> %% be upgraded to from the release created by %% create_and_install_fake_first_release/2. Unpack first by calls to %% release_handler:set_unpacked and release_handler:install_file. -create_fake_upgrade_release(Dir,RelVsn,AppDirs,{UpFrom,DownTo,ExtraLibs}) -> - %% Create a new release +create_fake_upgrade_release(Dir,RelVsn,AppDirs,UpgrInstr) when not is_tuple(RelVsn) -> {RelName,_} = init:script_id(), + create_fake_upgrade_release(Dir,{RelName,RelVsn},AppDirs,UpgrInstr); +create_fake_upgrade_release(Dir,{RelName,RelVsn},AppDirs,{UpFrom,DownTo,ExtraLibs}) -> + %% Create a new release {Rel,Paths} = create_fake_release(Dir,RelName,RelVsn,AppDirs), RelDir = filename:dirname(Rel), diff --git a/lib/sasl/test/release_handler_SUITE_data/Makefile.src b/lib/sasl/test/release_handler_SUITE_data/Makefile.src index b794aa0e6f..113d3e2290 100644 --- a/lib/sasl/test/release_handler_SUITE_data/Makefile.src +++ b/lib/sasl/test/release_handler_SUITE_data/Makefile.src @@ -76,7 +76,13 @@ SUP= \ release_handler_timeouts/dummy-0.1/ebin/dummy_sup.@EMULATOR@ \ release_handler_timeouts/dummy-0.1/ebin/dummy_sup_2.@EMULATOR@ -all: $(LIB) $(APP) $(OTP2740) $(C) $(SUP) +UNICODE= \ + unicode/u-1.0/ebin/u.@EMULATOR@ \ + unicode/u-1.0/ebin/u_sup.@EMULATOR@ \ + unicode/u-1.1/ebin/u.@EMULATOR@ \ + unicode/u-1.1/ebin/u_sup.@EMULATOR@ + +all: $(LIB) $(APP) $(OTP2740) $(C) $(SUP) $(UNICODE) lib/a-1.0/ebin/a.@EMULATOR@: lib/a-1.0/src/a.erl erlc $(EFLAGS) -olib/a-1.0/ebin lib/a-1.0/src/a.erl @@ -236,3 +242,13 @@ release_handler_timeouts/dummy-0.1/ebin/dummy_sup.@EMULATOR@: release_handler_ti erlc $(EFLAGS) -orelease_handler_timeouts/dummy-0.1/ebin release_handler_timeouts/dummy-0.1/src/dummy_sup.erl release_handler_timeouts/dummy-0.1/ebin/dummy_sup_2.@EMULATOR@: release_handler_timeouts/dummy-0.1/src/dummy_sup_2.erl erlc $(EFLAGS) -orelease_handler_timeouts/dummy-0.1/ebin release_handler_timeouts/dummy-0.1/src/dummy_sup_2.erl + +unicode/u-1.0/ebin/u.@EMULATOR@: unicode/u-1.0/src/u.erl + erlc $(EFLAGS) -ounicode/u-1.0/ebin unicode/u-1.0/src/u.erl +unicode/u-1.0/ebin/u_sup.@EMULATOR@: unicode/u-1.0/src/u_sup.erl + erlc $(EFLAGS) -ounicode/u-1.0/ebin unicode/u-1.0/src/u_sup.erl + +unicode/u-1.1/ebin/u.@EMULATOR@: unicode/u-1.1/src/u.erl + erlc $(EFLAGS) -ounicode/u-1.1/ebin unicode/u-1.1/src/u.erl +unicode/u-1.1/ebin/u_sup.@EMULATOR@: unicode/u-1.1/src/u_sup.erl + erlc $(EFLAGS) -ounicode/u-1.1/ebin unicode/u-1.1/src/u_sup.erl diff --git a/lib/sasl/test/release_handler_SUITE_data/start b/lib/sasl/test/release_handler_SUITE_data/start index 87275045b1..eab2b77aed 100755 --- a/lib/sasl/test/release_handler_SUITE_data/start +++ b/lib/sasl/test/release_handler_SUITE_data/start @@ -21,8 +21,7 @@ then fi HEART_COMMAND=$ROOTDIR/bin/start -HW_WD_DISABLE=true -export HW_WD_DISABLE HEART_COMMAND +export HEART_COMMAND START_ERL_DATA=${1:-$RELDIR/start_erl.data} diff --git a/lib/sasl/test/release_handler_SUITE_data/start_client b/lib/sasl/test/release_handler_SUITE_data/start_client index 5ea94d6f7c..05d744f06e 100755 --- a/lib/sasl/test/release_handler_SUITE_data/start_client +++ b/lib/sasl/test/release_handler_SUITE_data/start_client @@ -24,8 +24,7 @@ RELDIR=$CLIENTDIR/releases # Note that this scripts is modified an copied to $CLIENTDIR/bin/start # in release_handler_SUITE:copy_client - therefore HEART_COMMAND is as follows: HEART_COMMAND=$CLIENTDIR/bin/start -HW_WD_DISABLE=true -export HW_WD_DISABLE HEART_COMMAND +export HEART_COMMAND START_ERL_DATA=${1:-$RELDIR/start_erl.data} diff --git a/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.0/ebin/u.app b/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.0/ebin/u.app new file mode 100644 index 0000000000..fea4f9992e --- /dev/null +++ b/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.0/ebin/u.app @@ -0,0 +1,8 @@ +{application, u, + [{description, "This app shall test unicode handling αβ"}, + {vsn, "1.0"}, + {modules, [u, u_sup]}, + {registered, [u_sup]}, + {applications, [kernel, stdlib]}, + {env, [{'key_αβ', 'val_αβ'}]}, + {mod, {u_sup, []}}]}. diff --git a/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.0/src/u.erl b/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.0/src/u.erl new file mode 100644 index 0000000000..45fe098c0e --- /dev/null +++ b/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.0/src/u.erl @@ -0,0 +1,50 @@ +%% ``Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions 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$ +%% +-module(u). + + +-behaviour(gen_server). + +-vsn(1). + +%% External exports +-export([start_link/0, u/0]). +%% Internal exports +-export([init/1, handle_call/3, handle_info/2, terminate/2]). + +start_link() -> gen_server:start_link({local, uu}, u, [], []). + +u() -> gen_server:call(uu, u). + +%%----------------------------------------------------------------- +%% Callback functions from gen_server +%%----------------------------------------------------------------- +init([]) -> + process_flag(trap_exit, true), + {ok, state}. + +handle_call(u, _From, State) -> + X = application:get_all_env(u), + {reply, {X,State}, State}. + +handle_info(_, State) -> + {noreply, State}. + +terminate(_Reason, _State) -> + ok. diff --git a/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.0/src/u_sup.erl b/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.0/src/u_sup.erl new file mode 100644 index 0000000000..b0d4a7b58f --- /dev/null +++ b/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.0/src/u_sup.erl @@ -0,0 +1,38 @@ +%% ``Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions 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$ +%% +-module(u_sup). + + +-behaviour(supervisor). + +%% External exports +-export([start/2]). + +%% Internal exports +-export([init/1]). + +start(_, _) -> + supervisor:start_link({local, ?MODULE}, ?MODULE, []). + +init([]) -> + SupFlags = {one_for_one, 4, 3600}, + Config = {u, + {u, start_link, []}, + permanent, 2000, worker, [u]}, + {ok, {SupFlags, [Config]}}. diff --git a/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.1/ebin/u.app b/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.1/ebin/u.app new file mode 100644 index 0000000000..8fcc3bba42 --- /dev/null +++ b/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.1/ebin/u.app @@ -0,0 +1,8 @@ +{application, u, + [{description, "This app shall test unicode handling αβ"}, + {vsn, "1.1"}, + {modules, [u, u_sup]}, + {registered, [u_sup]}, + {applications, [kernel, stdlib]}, + {env, [{'key_αβ', 'val_αβ'}]}, + {mod, {u_sup, []}}]}. diff --git a/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.1/ebin/u.appup b/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.1/ebin/u.appup new file mode 100644 index 0000000000..0344ce92ab --- /dev/null +++ b/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.1/ebin/u.appup @@ -0,0 +1,3 @@ +{"1.1", + [{"1.0",[{update,u,{advanced,'αβ'}}]}], + [{"1.0",[{update,u,{advanced,'αβ'}}]}]}. diff --git a/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.1/src/u.erl b/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.1/src/u.erl new file mode 100644 index 0000000000..d2544d6fc1 --- /dev/null +++ b/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.1/src/u.erl @@ -0,0 +1,55 @@ +%% ``Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions 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$ +%% +-module(u). + + +-behaviour(gen_server). + +-vsn(1). + +%% External exports +-export([start_link/0, u/0]). +%% Internal exports +-export([init/1, handle_call/3, handle_info/2, terminate/2, code_change/3]). + +start_link() -> gen_server:start_link({local, uu}, u, [], []). + +u() -> gen_server:call(uu, u). + +%%----------------------------------------------------------------- +%% Callback functions from gen_server +%%----------------------------------------------------------------- +init([]) -> + process_flag(trap_exit, true), + {ok, {state,'αβ'}}. + +handle_call(u, _From, State) -> + X = application:get_all_env(u), + {reply, {X,State}, State}. + +handle_info(_, State) -> + {noreply, State}. + +terminate(_Reason, _State) -> + ok. + +code_change({down,_}, {State,_}, _Extra) -> + {ok, State}; +code_change(_, State, Extra) -> + {ok, {State, Extra}}. diff --git a/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.1/src/u_sup.erl b/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.1/src/u_sup.erl new file mode 100644 index 0000000000..b0d4a7b58f --- /dev/null +++ b/lib/sasl/test/release_handler_SUITE_data/unicode/u-1.1/src/u_sup.erl @@ -0,0 +1,38 @@ +%% ``Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions 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$ +%% +-module(u_sup). + + +-behaviour(supervisor). + +%% External exports +-export([start/2]). + +%% Internal exports +-export([init/1]). + +start(_, _) -> + supervisor:start_link({local, ?MODULE}, ?MODULE, []). + +init([]) -> + SupFlags = {one_for_one, 4, 3600}, + Config = {u, + {u, start_link, []}, + permanent, 2000, worker, [u]}, + {ok, {SupFlags, [Config]}}. diff --git a/lib/sasl/test/rh_test_lib.erl b/lib/sasl/test/rh_test_lib.erl index 11935496d8..dacd8b6b9f 100644 --- a/lib/sasl/test/rh_test_lib.erl +++ b/lib/sasl/test/rh_test_lib.erl @@ -18,7 +18,7 @@ cmd(Cmd,Args,Env) -> case open_port({spawn_executable, Cmd}, [{args,Args},{env,Env}]) of Port when is_port(Port) -> unlink(Port), - erlang:port_close(Port), + catch erlang:port_close(Port), % migth already be closed, so catching ok; Error -> Error diff --git a/lib/sasl/test/sasl_SUITE.erl b/lib/sasl/test/sasl_SUITE.erl index 1d76cdee6e..f12bde9b3d 100644 --- a/lib/sasl/test/sasl_SUITE.erl +++ b/lib/sasl/test/sasl_SUITE.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2011-2014. All Rights Reserved. +%% Copyright Ericsson AB 2011-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -28,10 +28,11 @@ -export([app_test/1, appup_test/1, log_mf_h_env/1, - log_file/1]). + log_file/1, + utc_log/1]). all() -> - [log_mf_h_env, log_file, app_test, appup_test]. + [log_mf_h_env, log_file, app_test, appup_test, utc_log]. groups() -> []. @@ -182,20 +183,104 @@ log_mf_h_env(Config) -> log_file(Config) -> PrivDir = ?config(priv_dir,Config), LogDir = filename:join(PrivDir,sasl_SUITE_log_dir), - ok = filelib:ensure_dir(LogDir), File = filename:join(LogDir, "file.log"), + ok = filelib:ensure_dir(File), application:stop(sasl), clear_env(sasl), - ok = application:set_env(sasl,sasl_error_logger,{file, File}, [{persistent, true}]), + _ = test_log_file(File, {file,File}), + _ = test_log_file(File, {file,File,[write]}), + + ok = file:write_file(File, <<"=PROGRESS preserve me\n">>), + <<"=PROGRESS preserve me\n",_/binary>> = + test_log_file(File, {file,File,[append]}), + + ok = application:set_env(sasl,sasl_error_logger, tty, + [{persistent, false}]), + ok = application:start(sasl). + +test_log_file(File, Arg) -> + ok = application:set_env(sasl, sasl_error_logger, Arg, + [{persistent, true}]), + ok = application:start(sasl), + application:stop(sasl), + {ok,Bin} = file:read_file(File), + ok = file:delete(File), + Lines0 = binary:split(Bin, <<"\n">>, [trim_all,global]), + Lines = [L || L <- Lines0, + binary:match(L, <<"=PROGRESS">>) =:= {0,9}], + io:format("~p:\n~p\n", [Arg,Lines]), + + %% There must be at least four PROGRESS lines. + if + length(Lines) >= 4 -> ok; + true -> ?t:fail() + end, + Bin. + +%% Make a basic test of utc_log. +utc_log(Config) -> + PrivDir = ?config(priv_dir, Config), + LogDir = filename:join(PrivDir, sasl_SUITE_log_dir), + Log = filename:join(LogDir, "utc.log"), + ok = filelib:ensure_dir(Log), + + application:stop(sasl), + clear_env(sasl), + + %% Test that the UTC marker gets added to PROGRESS lines + %% when the utc_log configuration variable is set to true. + ok = application:set_env(sasl, sasl_error_logger, {file,Log}, + [{persistent,true}]), + ok = application:set_env(sasl, utc_log, true, [{persistent,true}]), ok = application:start(sasl), application:stop(sasl), - ok = application:set_env(sasl,sasl_error_logger,{file, File, [append]}, [{persistent, true}]), + + verify_utc_log(Log, true), + + %% Test that no UTC markers gets added to PROGRESS lines + %% when the utc_log configuration variable is set to false. + ok = application:set_env(sasl, utc_log, false, [{persistent,true}]), + ok = application:start(sasl), + application:stop(sasl), + + verify_utc_log(Log, false), + + %% Test that no UTC markers gets added to PROGRESS lines + %% when the utc_log configuration variable is unset. + ok = application:unset_env(sasl, utc_log, [{persistent,true}]), ok = application:start(sasl), application:stop(sasl), - ok = application:set_env(sasl,sasl_error_logger, tty, [{persistent, false}]), + + verify_utc_log(Log, false), + + %% Change back to the standard TTY error logger. + ok = application:set_env(sasl,sasl_error_logger, tty, + [{persistent, false}]), ok = application:start(sasl). +verify_utc_log(Log, UTC) -> + {ok,Bin} = file:read_file(Log), + ok = file:delete(Log), + + Lines0 = binary:split(Bin, <<"\n">>, [trim_all,global]), + Lines = [L || L <- Lines0, + binary:match(L, <<"=PROGRESS">>) =:= {0,9}], + Setting = application:get_env(sasl, utc_log), + io:format("utc_log ~p:\n~p\n", [Setting,Lines]), + Filtered = [L || L <- Lines, + binary:match(L, <<" UTC ===">>) =:= nomatch], + %% Filtered now contains all lines WITHOUT any UTC markers. + case UTC of + false -> + %% No UTC marker on the PROGRESS line. + Filtered = Lines; + true -> + %% Each PROGRESS line must have an UTC marker. + [] = Filtered + end, + ok. + %%----------------------------------------------------------------- %% Internal diff --git a/lib/sasl/test/sasl_report_SUITE.erl b/lib/sasl/test/sasl_report_SUITE.erl new file mode 100644 index 0000000000..92df5e6e40 --- /dev/null +++ b/lib/sasl/test/sasl_report_SUITE.erl @@ -0,0 +1,161 @@ +%% +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2015-2017. All Rights Reserved. +%% +%% Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions and +%% limitations under the License. +%% +%% %CopyrightEnd% +%% +-module(sasl_report_SUITE). +-export([all/0, suite/0,groups/0,init_per_suite/1, end_per_suite/1, + init_per_group/2,end_per_group/2]). +-export([gen_server_crash/1, gen_server_crash_unicode/1]). + +-export([crash_me/0,start_link/0,init/1,handle_cast/2,terminate/2]). + +-include_lib("common_test/include/ct.hrl"). + +suite() -> [{ct_hooks,[ts_install_cth]}]. + +all() -> + [gen_server_crash, gen_server_crash_unicode]. + +groups() -> + []. + +init_per_suite(Config) -> + Config. + +end_per_suite(_Config) -> + ok. + +init_per_group(_GroupName, Config) -> + Config. + +end_per_group(_GroupName, Config) -> + Config. + +gen_server_crash(Config) -> + gen_server_crash(Config, latin1). + +gen_server_crash_unicode(Config) -> + gen_server_crash(Config, unicode). + +gen_server_crash(Config, Encoding) -> + try + do_gen_server_crash(Config, Encoding) + after + error_logger:tty(true), + ok = application:unset_env(sasl, sasl_error_logger), + ok = application:unset_env(kernel, error_logger_format_depth), + error_logger:add_report_handler(cth_log_redirect) + end, + ok. + +do_gen_server_crash(Config, Encoding) -> + PrivDir = ?config(priv_dir, Config), + LogDir = filename:join(PrivDir, ?MODULE), + KernelLog = filename:join(LogDir, "kernel.log"), + SaslLog = filename:join(LogDir, "sasl.log"), + ok = filelib:ensure_dir(SaslLog), + + error_logger:delete_report_handler(cth_log_redirect), + error_logger:tty(false), + application:stop(sasl), + Modes = [write, {encoding, Encoding}], + ok = application:set_env(sasl, sasl_error_logger, {file,SaslLog,Modes}, + [{persistent,true}]), + application:set_env(kernel, error_logger_format_depth, 30), + error_logger:logfile({open,KernelLog}), + application:start(sasl), + io:format("~p\n", [gen_event:which_handlers(error_logger)]), + + crash_me(), + + error_logger:logfile(close), + + check_file(KernelLog, utf8, 70000, 150000), + check_file(SaslLog, Encoding, 70000, 150000), + + %% ok = file:delete(KernelLog), + %% ok = file:delete(SaslLog), + ok. + +check_file(File, Encoding, Min, Max) -> + {ok,Bin} = file:read_file(File), + Base = filename:basename(File), + io:format("*** Contents of ~s ***\n", [Base]), + case Encoding of + latin1 -> io:format("~s\n", [Bin]); + _ -> io:format("~ts\n", [Bin]) + end, + Sz = byte_size(Bin), + io:format("Size: ~p (allowed range is ~p..~p)\n", + [Sz,Min,Max]), + if + Sz < Min -> + %% Truncated? Other problem? + ?t:fail({too_short,Base}); + Sz > Max -> + %% Truncation doesn't work? + ?t:fail({too_big,Base}); + true -> + ok + end. + +%%% +%%% gen_server that crashes. +%%% + +crash_me() -> + {ok,SuperPid} = supervisor:start_link(sasl_report_suite_supervisor, []), + [{Id,Pid,_,_}] = supervisor:which_children(SuperPid), + HugeData = gb_sets:from_list(lists:seq(1, 100000)), + SomeData1 = list_to_atom([246]), + SomeData2 = list_to_atom([1024]), + gen_server:cast(Pid, {HugeData,SomeData1,SomeData2}), + Ref = monitor(process, Pid), + receive + {'DOWN',Ref,process,Pid,_} -> + supervisor:terminate_child(SuperPid, Id), + unlink(SuperPid), + exit(SuperPid, kill), + ok + end. + +start_link() -> + gen_server:start_link(?MODULE, [], []). + +init(_) -> + St = <<0:100000/unit:8>>, + {ok,St}. + +handle_cast(Big, St) -> + Seq = lists:seq(1, 10000), + Latin1Atom = list_to_atom([246]), + UnicodeAtom = list_to_atom([1024]), + put(Latin1Atom, Latin1Atom), + put(UnicodeAtom, UnicodeAtom), + self() ! Latin1Atom, + self() ! UnicodeAtom, + self() ! Seq, + self() ! Seq, + self() ! Seq, + self() ! Seq, + self() ! Seq, + x = Big, + {noreply,St}. + +terminate(_, _) -> + ok. diff --git a/lib/sasl/test/sasl_report_suite_supervisor.erl b/lib/sasl/test/sasl_report_suite_supervisor.erl new file mode 100644 index 0000000000..bc92a40af2 --- /dev/null +++ b/lib/sasl/test/sasl_report_suite_supervisor.erl @@ -0,0 +1,77 @@ +%% +%% %CopyrightBegin% +%% +%% Copyright Ericsson AB 2015. All Rights Reserved. +%% +%% Licensed under the Apache License, Version 2.0 (the "License"); +%% you may not use this file except in compliance with the License. +%% You may obtain a copy of the License at +%% +%% http://www.apache.org/licenses/LICENSE-2.0 +%% +%% Unless required by applicable law or agreed to in writing, software +%% distributed under the License is distributed on an "AS IS" BASIS, +%% WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +%% See the License for the specific language governing permissions and +%% limitations under the License. +%% +%% %CopyrightEnd% +%% + +-module(sasl_report_suite_supervisor). + +-behaviour(supervisor). + +%% API +-export([start_link/0]). + +%% Supervisor callbacks +-export([init/1]). + +-define(SERVER, ?MODULE). + +%%%=================================================================== +%%% API functions +%%%=================================================================== + +%%-------------------------------------------------------------------- +%% @doc +%% Starts the supervisor +%% +%% @spec start_link() -> {ok, Pid} | ignore | {error, Error} +%% @end +%%-------------------------------------------------------------------- +start_link() -> + supervisor:start_link({local, ?SERVER}, ?MODULE, []). + +%%%=================================================================== +%%% Supervisor callbacks +%%%=================================================================== + +%%-------------------------------------------------------------------- +%% @private +%% @doc +%% Whenever a supervisor is started using supervisor:start_link/[2,3], +%% this function is called by the new process to find out about +%% restart strategy, maximum restart intensity, and child +%% specifications. +%% +%% @spec init(Args) -> {ok, {SupFlags, [ChildSpec]}} | +%% ignore | +%% {error, Reason} +%% @end +%%-------------------------------------------------------------------- +init([]) -> + + SupFlags = #{strategy => one_for_one, + intensity => 1, + period => 5}, + + AChild = #{id => 'sasl_report_suit_supervisor', + start => {sasl_report_SUITE, start_link, []}, + restart => permanent, + shutdown => 5000, + type => worker, + modules => [sasl_report_SUITE]}, + + {ok, {SupFlags, [AChild]}}. diff --git a/lib/sasl/test/systools_SUITE.erl b/lib/sasl/test/systools_SUITE.erl index cf0ed5fcfc..6e83b4c2e2 100644 --- a/lib/sasl/test/systools_SUITE.erl +++ b/lib/sasl/test/systools_SUITE.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2012-2014. All Rights Reserved. +%% Copyright Ericsson AB 2012-2017. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -29,6 +29,8 @@ -module(systools_SUITE). +-compile(export_all). + %%-define(debug, true). -include_lib("common_test/include/ct.hrl"). @@ -39,31 +41,6 @@ -include_lib("kernel/include/file.hrl"). --export([all/0,suite/0,groups/0,init_per_group/2,end_per_group/2]). - --export([script_options/1, normal_script/1, unicode_script/1, - unicode_script/2, no_mod_vsn_script/1, - wildcard_script/1, variable_script/1, no_sasl_script/1, - no_dot_erlang_script/1, - abnormal_script/1, src_tests_script/1, crazy_script/1, - included_script/1, included_override_script/1, - included_fail_script/1, included_bug_script/1, exref_script/1, - duplicate_modules_script/1, - otp_3065_circular_dependenies/1, included_and_used_sort_script/1]). --export([tar_options/1, normal_tar/1, no_mod_vsn_tar/1, system_files_tar/1, - system_files_tar/2, invalid_system_files_tar/1, - invalid_system_files_tar/2, variable_tar/1, - src_tests_tar/1, var_tar/1, exref_tar/1, link_tar/1, - otp_9507_path_ebin/1]). --export([normal_relup/1, restart_relup/1, abnormal_relup/1, no_sasl_relup/1, - no_appup_relup/1, bad_appup_relup/1, app_start_type_relup/1, - regexp_relup/1]). --export([normal_hybrid/1,hybrid_no_old_sasl/1,hybrid_no_new_sasl/1]). --export([otp_6226_outdir/1]). --export([init_per_suite/1, end_per_suite/1, - init_per_testcase/2, end_per_testcase/2]). --export([delete_tree/1]). - -import(lists, [foldl/3]). -define(default_timeout, ?t:minutes(20)). @@ -91,13 +68,14 @@ groups() -> {tar, [], [tar_options, normal_tar, no_mod_vsn_tar, system_files_tar, invalid_system_files_tar, variable_tar, - src_tests_tar, var_tar, exref_tar, link_tar, otp_9507_path_ebin]}, + src_tests_tar, var_tar, exref_tar, link_tar, no_sasl_tar, + otp_9507_path_ebin]}, {relup, [], [normal_relup, restart_relup, abnormal_relup, no_sasl_relup, no_appup_relup, bad_appup_relup, app_start_type_relup, regexp_relup ]}, {hybrid, [], [normal_hybrid,hybrid_no_old_sasl,hybrid_no_new_sasl]}, - {options, [], [otp_6226_outdir]}]. + {options, [], [otp_6226_outdir,app_file_defaults]}]. init_per_group(_GroupName, Config) -> Config. @@ -109,25 +87,25 @@ end_per_group(_GroupName, Config) -> init_per_suite(Config) when is_list(Config) -> + %% To use in end_per_testcase + Path = code:get_path(), + {ok,Cwd} = file:get_cwd(), + %% Make of copy of the data directory. DataDir = ?datadir, PrivDir = ?privdir, CopyDir = fname(PrivDir, "datacopy"), + ok = file:make_dir(CopyDir), TarFile = fname(PrivDir, "datacopy.tgz"), - {ok, Tar} = erl_tar:open(TarFile, [write, compressed]), - ok = erl_tar:add(Tar, DataDir, CopyDir, [compressed]), - ok = erl_tar:close(Tar), - ok = erl_tar:extract(TarFile, [compressed]), + ok = file:set_cwd(DataDir), + ok = erl_tar:create(TarFile, ["."], [compressed]), + ok = erl_tar:extract(TarFile, [compressed, {cwd,CopyDir}]), ok = file:delete(TarFile), %% Compile source files in the copy directory. Sources = filelib:wildcard(fname([CopyDir,'*','*','*','*','*.erl'])), lists:foreach(fun compile_source/1, Sources), - %% To use in end_per_testcase - Path = code:get_path(), - {ok,Cwd} = file:get_cwd(), - [{copy_dir, CopyDir}, {cwd,Cwd}, {path,Path} | Config]. compile_source(File) -> @@ -238,6 +216,7 @@ normal_script(Config) when is_list(Config) -> %% Check the same but w. silent flag {ok, _, []} = systools:make_script(LatestName, [silent]), + {ok, _, []} = systools:make_script(LatestName, [silent,warnings_as_errors]), %% Use the local option ok = systools:make_script(LatestName, [local]), @@ -456,9 +435,16 @@ no_sasl_script(Config) when is_list(Config) -> {ok, _ , [{warning,missing_sasl}]} = systools:make_script(LatestName,[{path, P},silent]), + {error, systools_make, {warnings_treated_as_errors,[missing_sasl]}} = + systools:make_script(LatestName,[{path, P},silent,warnings_as_errors]), + {ok, _ , []} = systools:make_script(LatestName,[{path, P},silent, no_warn_sasl]), + {ok, _ , []} = + systools:make_script(LatestName,[{path, P},silent, no_warn_sasl, + warnings_as_errors]), + ok = file:set_cwd(OldDir), ok. @@ -525,7 +511,9 @@ src_tests_script(Config) when is_list(Config) -> ok = file:delete(BootFile), false = filelib:is_regular(BootFile), %% With warnings_as_errors and src_tests option, an error should be issued - error = + {error, systools_make, + {warnings_treated_as_errors, [{obj_out_of_date,_}, + {source_not_found,_}]}} = systools:make_script(LatestName, [silent, {path, N}, src_tests, warnings_as_errors]), error = @@ -745,7 +733,7 @@ exref_script(Config) when is_list(Config) -> ok = file:set_cwd(LatestDir), - {ok, _, _} = systools:make_script(LatestName, [{path,P}, silent]), + {ok, _, []} = systools:make_script(LatestName, [{path,P}, silent]), %% Complete exref {ok, _, W1} = @@ -894,10 +882,10 @@ normal_tar(Config) when is_list(Config) -> ok = file:set_cwd(LatestDir), - {ok, _, _} = systools:make_script(LatestName, [silent, {path, P}]), + {ok, _, []} = systools:make_script(LatestName, [silent, {path, P}]), ok = systools:make_tar(LatestName, [{path, P}]), ok = check_tar(fname([lib,'db-2.1',ebin,'db.app']), LatestName), - {ok, _, _} = systools:make_tar(LatestName, [{path, P}, silent]), + {ok, _, []} = systools:make_tar(LatestName, [{path, P}, silent]), ok = check_tar(fname([lib,'fe-3.1',ebin,'fe.app']), LatestName), ok = file:set_cwd(OldDir), @@ -918,10 +906,10 @@ no_mod_vsn_tar(Config) when is_list(Config) -> ok = file:set_cwd(LatestDir), - {ok, _, _} = systools:make_script(LatestName, [silent, {path, P}]), + {ok, _, []} = systools:make_script(LatestName, [silent, {path, P}]), ok = systools:make_tar(LatestName, [{path, P}]), ok = check_tar(fname([lib,'db-3.1',ebin,'db.app']), LatestName), - {ok, _, _} = systools:make_tar(LatestName, [{path, P}, silent]), + {ok, _, []} = systools:make_tar(LatestName, [{path, P}, silent]), ok = check_tar(fname([lib,'fe-3.1',ebin,'fe.app']), LatestName), ok = file:set_cwd(OldDir), @@ -945,11 +933,11 @@ system_files_tar(Config) -> ok = file:write_file("sys.config","[].\n"), ok = file:write_file("relup","{\"LATEST\",[],[]}.\n"), - {ok, _, _} = systools:make_script(LatestName, [silent, {path, P}]), + {ok, _, []} = systools:make_script(LatestName, [silent, {path, P}]), ok = systools:make_tar(LatestName, [{path, P}]), ok = check_tar(fname(["releases","LATEST","sys.config"]), LatestName), ok = check_tar(fname(["releases","LATEST","relup"]), LatestName), - {ok, _, _} = systools:make_tar(LatestName, [{path, P}, silent]), + {ok, _, []} = systools:make_tar(LatestName, [{path, P}, silent]), ok = check_tar(fname(["releases","LATEST","sys.config"]), LatestName), ok = check_tar(fname(["releases","LATEST","relup"]), LatestName), @@ -978,7 +966,7 @@ invalid_system_files_tar(Config) -> ok = file:set_cwd(LatestDir), - {ok, _, _} = systools:make_script(LatestName, [silent, {path, P}]), + {ok, _, []} = systools:make_script(LatestName, [silent, {path, P}]), %% Add dummy relup and sys.config - faulty sys.config ok = file:write_file("sys.config","[]\n"), %!!! syntax error - missing '.' @@ -1036,7 +1024,7 @@ variable_tar(Config) when is_list(Config) -> ok = file:set_cwd(LatestDir), - {ok, _, _} = systools:make_script(LatestName, + {ok, _, []} = systools:make_script(LatestName, [silent, {path, P}, {variables,[{"TEST", LibDir}]}]), @@ -1045,7 +1033,7 @@ variable_tar(Config) when is_list(Config) -> {variables,[{"TEST", LibDir}]}]), ok = check_var_tar("TEST", LatestName), - {ok, _, _} = systools:make_tar(LatestName, + {ok, _, []} = systools:make_tar(LatestName, [{path, P}, silent, {variables,[{"TEST", LibDir}]}]), ok = check_var_tar("TEST", LatestName), @@ -1174,7 +1162,7 @@ var_tar(Config) when is_list(Config) -> ok = file:set_cwd(LatestDir), - {ok, _, _} = systools:make_script(LatestName, + {ok, _, []} = systools:make_script(LatestName, [silent, {path, P}, {variables,[{"TEST", LibDir}]}]), @@ -1218,7 +1206,7 @@ exref_tar(Config) when is_list(Config) -> ok = file:set_cwd(LatestDir), - {ok, _, _} = systools:make_script(LatestName, [silent, {path, P}]), + {ok, _, []} = systools:make_script(LatestName, [silent, {path, P}]), %% Complete exref {ok, _, W1} = @@ -1248,7 +1236,41 @@ exref_tar(Config) when is_list(Config) -> ok = file:set_cwd(OldDir), ok. +%% make_tar: Create tar without sasl appl. Check warning. +no_sasl_tar(Config) when is_list(Config) -> + {ok, OldDir} = file:get_cwd(), + + {LatestDir, LatestName} = create_script(latest1_no_sasl,Config), + + DataDir = filename:absname(?copydir), + LibDir = fname([DataDir, d_normal, lib]), + P = [fname([LibDir, '*', ebin]), + fname([DataDir, lib, kernel, ebin]), + fname([DataDir, lib, stdlib, ebin]), + fname([DataDir, lib, sasl, ebin])], + + ok = file:set_cwd(LatestDir), + + {ok, _, _} = systools:make_script(LatestName, [silent, {path, P}]), + ok = systools:make_tar(LatestName, [{path, P}]), + {ok, _, [{warning,missing_sasl}]} = + systools:make_tar(LatestName, [{path, P}, silent]), + {ok, _, []} = + systools:make_tar(LatestName, [{path, P}, silent, no_warn_sasl]), + {ok, _, []} = + systools:make_tar(LatestName, [{path, P}, silent, no_warn_sasl, + warnings_as_errors]), + TarFile = LatestName ++ ".tar.gz", + true = filelib:is_regular(TarFile), + ok = file:delete(TarFile), + {error, systools_make, {warnings_treated_as_errors,[missing_sasl]}} = + systools:make_tar(LatestName, [{path, P}, silent, warnings_as_errors]), + error = + systools:make_tar(LatestName, [{path, P}, warnings_as_errors]), + false = filelib:is_regular(TarFile), + ok = file:set_cwd(OldDir), + ok. %% make_tar: OTP-9507 - make_tar failed when path given as just 'ebin'. otp_9507_path_ebin(Config) when is_list(Config) -> @@ -1268,7 +1290,7 @@ otp_9507_path_ebin(Config) when is_list(Config) -> fname([DataDir, lib, kernel, ebin]), fname([DataDir, lib, stdlib, ebin]), fname([DataDir, lib, sasl, ebin])], - {ok, _, _} = systools:make_script(RelName, [silent, {path, P1}]), + {ok, _, []} = systools:make_script(RelName, [silent, {path, P1}]), ok = systools:make_tar(RelName, [{path, P1}]), Content1 = tar_contents(RelName), @@ -1309,7 +1331,7 @@ normal_relup(Config) when is_list(Config) -> ok = systools:make_relup(LatestName, [LatestName1], [LatestName1], [{path, P}]), ok = check_relup([{db, "2.1"}], [{db, "1.0"}]), - {ok, _, _, []} = + {ok, Relup, _, []} = systools:make_relup(LatestName, [LatestName1], [LatestName1], [{path, P}, silent]), ok = check_relup([{db, "2.1"}], [{db, "1.0"}]), @@ -1322,7 +1344,9 @@ normal_relup(Config) when is_list(Config) -> error = systools:make_relup(LatestName, [LatestName2], [LatestName1], [{path, P}, warnings_as_errors]), - error = + {error, systools_relup, + {warnings_treated_as_errors,[pre_R15_emulator_upgrade, + {erts_vsn_changed, _}]}} = systools:make_relup(LatestName, [LatestName2], [LatestName1], [{path, P}, silent, warnings_as_errors]), @@ -1341,6 +1365,14 @@ normal_relup(Config) when is_list(Config) -> %% relup file should exist now true = filelib:is_regular("relup"), + %% file should not be written if noexec option is used. + %% delete before running tests. + ok = file:delete("relup"), + {ok,Relup,_,[]} = + systools:make_relup(LatestName, [LatestName1], [LatestName1], + [{path, P}, noexec]), + false = filelib:is_regular("relup"), + ok = file:set_cwd(OldDir), ok. @@ -1640,25 +1672,21 @@ app_start_type_relup(Dir2,Name2,Config) -> %% ?t:format("Dn: ~p",[DownInstructions]), [{load_object_code, {mnesia, _, _}}, {load_object_code, {runtime_tools, _, _}}, - {load_object_code, {webtool, _, _}}, {load_object_code, {snmp, _, _}}, {load_object_code, {xmerl, _, _}}, point_of_no_return | UpInstructionsT] = UpInstructions, true = lists:member({apply,{application,start,[mnesia,permanent]}}, UpInstructionsT), true = lists:member({apply,{application,start,[runtime_tools,transient]}}, UpInstructionsT), - true = lists:member({apply,{application,start,[webtool,temporary]}}, UpInstructionsT), true = lists:member({apply,{application,load,[snmp]}}, UpInstructionsT), false = lists:any(fun({apply,{application,_,[xmerl|_]}}) -> true; (_) -> false end, UpInstructionsT), [point_of_no_return | DownInstructionsT] = DownInstructions, true = lists:member({apply,{application,stop,[mnesia]}}, DownInstructionsT), true = lists:member({apply,{application,stop,[runtime_tools]}}, DownInstructionsT), - true = lists:member({apply,{application,stop,[webtool]}}, DownInstructionsT), true = lists:member({apply,{application,stop,[snmp]}}, DownInstructionsT), true = lists:member({apply,{application,stop,[xmerl]}}, DownInstructionsT), true = lists:member({apply,{application,unload,[mnesia]}}, DownInstructionsT), true = lists:member({apply,{application,unload,[runtime_tools]}}, DownInstructionsT), - true = lists:member({apply,{application,unload,[webtool]}}, DownInstructionsT), true = lists:member({apply,{application,unload,[snmp]}}, DownInstructionsT), true = lists:member({apply,{application,unload,[xmerl]}}, DownInstructionsT), ok. @@ -1732,27 +1760,28 @@ normal_hybrid(Config) -> ok = file:set_cwd(OldDir), - BasePaths = {"testkernelpath","teststdlibpath","testsaslpath"}, {ok,Hybrid} = systools_make:make_hybrid_boot("tmp_vsn",Boot1,Boot2, - BasePaths, [dummy,args]), + [dummy,args]), {script,{"Test release","tmp_vsn"},Script} = binary_to_term(Hybrid), ct:log("~p.~n",[Script]), %% Check that all paths to base apps are replaced by paths from BaseLib Boot1Str = io_lib:format("~p~n",[binary_to_term(Boot1)]), + Boot2Str = io_lib:format("~p~n",[binary_to_term(Boot2)]), HybridStr = io_lib:format("~p~n",[binary_to_term(Hybrid)]), ReOpts = [global,{capture,first,list},unicode], {match,OldKernelMatch} = re:run(Boot1Str,"kernel-[0-9\.]+",ReOpts), {match,OldStdlibMatch} = re:run(Boot1Str,"stdlib-[0-9\.]+",ReOpts), {match,OldSaslMatch} = re:run(Boot1Str,"sasl-[0-9\.]+",ReOpts), - nomatch = re:run(HybridStr,"kernel-[0-9\.]+",ReOpts), - nomatch = re:run(HybridStr,"stdlib-[0-9\.]+",ReOpts), - nomatch = re:run(HybridStr,"sasl-[0-9\.]+",ReOpts), - {match,NewKernelMatch} = re:run(HybridStr,"testkernelpath",ReOpts), - {match,NewStdlibMatch} = re:run(HybridStr,"teststdlibpath",ReOpts), - {match,NewSaslMatch} = re:run(HybridStr,"testsaslpath",ReOpts), + {match,NewKernelMatch} = re:run(Boot2Str,"kernel-[0-9\.]+",ReOpts), + {match,NewStdlibMatch} = re:run(Boot2Str,"stdlib-[0-9\.]+",ReOpts), + {match,NewSaslMatch} = re:run(Boot2Str,"sasl-[0-9\.]+",ReOpts), + + {match,NewKernelMatch} = re:run(HybridStr,"kernel-[0-9\.]+",ReOpts), + {match,NewStdlibMatch} = re:run(HybridStr,"stdlib-[0-9\.]+",ReOpts), + {match,NewSaslMatch} = re:run(HybridStr,"sasl-[0-9\.]+",ReOpts), NewKernelN = length(NewKernelMatch), NewKernelN = length(OldKernelMatch), @@ -1761,6 +1790,11 @@ normal_hybrid(Config) -> NewSaslN = length(NewSaslMatch), NewSaslN = length(OldSaslMatch), + %% Check that kernelProcesses are taken from new boot script + {script,_,Script2} = binary_to_term(Boot2), + NewKernelProcs = [KP || KP={kernelProcess,_,_} <- Script2], + NewKernelProcs = [KP || KP={kernelProcess,_,_} <- Script], + %% Check that application load instruction has correct versions Apps = application:loaded_applications(), {_,_,KernelVsn} = lists:keyfind(kernel,1,Apps), @@ -1831,10 +1865,8 @@ hybrid_no_old_sasl(Config) -> {ok,Boot1} = file:read_file(Name1 ++ ".boot"), {ok,Boot2} = file:read_file(Name2 ++ ".boot"), - BasePaths = {"testkernelpath","teststdlibpath","testsaslpath"}, {error,{app_not_replaced,sasl}} = - systools_make:make_hybrid_boot("tmp_vsn",Boot1,Boot2, - BasePaths,[dummy,args]), + systools_make:make_hybrid_boot("tmp_vsn",Boot1,Boot2,[dummy,args]), ok = file:set_cwd(OldDir), ok. @@ -1864,10 +1896,8 @@ hybrid_no_new_sasl(Config) -> {ok,Boot1} = file:read_file(Name1 ++ ".boot"), {ok,Boot2} = file:read_file(Name2 ++ ".boot"), - BasePaths = {"testkernelpath","teststdlibpath","testsaslpath"}, {error,{app_not_found,sasl}} = - systools_make:make_hybrid_boot("tmp_vsn",Boot1,Boot2, - BasePaths,[dummy,args]), + systools_make:make_hybrid_boot("tmp_vsn",Boot1,Boot2,[dummy,args]), ok = file:set_cwd(OldDir), ok. @@ -2018,6 +2048,37 @@ otp_6226_outdir(Config) when is_list(Config) -> ok. +%% Test that all default values can be used as values in the .app file +app_file_defaults(Config) -> + PrivDir = ?config(priv_dir,Config), + Name = app1, + NameStr = atom_to_list(Name), + Vsn = "1.0", + AppSpec = app_spec(Name,#{vsn=>"1.0"}), + ok = file:write_file(filename:join(PrivDir,NameStr ++ ".app"), + io_lib:format("~p.~n",[AppSpec])), + {ok,_} = systools_make:read_application(NameStr,Vsn,[PrivDir],[]), + ok. + +app_spec(Name,New) -> + {application,Name,app_spec(New)}. + +app_spec(New) -> + Default = #{description => "", + id => "", + vsn => "", + modules => [], + maxP => infinity, + maxT => infinity, + registered => [], + included_applications => [], + applications => [], + env => [], + mod => [], + start_phases => undefined, + runtime_dependencies => []}, + maps:to_list(maps:merge(Default,New)). + %%%%%% %%%%%% Utilities %%%%%% @@ -2207,7 +2268,6 @@ create_script(latest_app_start_type1,Config) -> create_script(latest_app_start_type2,Config) -> OtherApps = [{mnesia,current,permanent}, {runtime_tools,current,transient}, - {webtool,current,temporary}, {snmp,current,load}, {xmerl,current,none}], Apps = core_apps(current) ++ OtherApps, diff --git a/lib/sasl/test/systools_rc_SUITE.erl b/lib/sasl/test/systools_rc_SUITE.erl index 3754ed99f2..baa3a16e70 100644 --- a/lib/sasl/test/systools_rc_SUITE.erl +++ b/lib/sasl/test/systools_rc_SUITE.erl @@ -1,7 +1,7 @@ %% %% %CopyrightBegin% %% -%% Copyright Ericsson AB 2010-2014. All Rights Reserved. +%% Copyright Ericsson AB 2010-2016. All Rights Reserved. %% %% Licensed under the Apache License, Version 2.0 (the "License"); %% you may not use this file except in compliance with the License. @@ -26,10 +26,6 @@ translate_emulator_restarts/1, translate_add_delete_module/1]). -%%----------------------------------------------------------------- -%% erl -compile systools_rc_SUITE @i ../src/ @i ../../test_server/include/ -%% c(systools_rc_SUITE, [{i, "../src"}, {i, "../../test_server/include"}]). -%%----------------------------------------------------------------- all() -> [syntax_check, translate, translate_app, translate_emulator_restarts, translate_add_delete_module]. diff --git a/lib/sasl/test/test_lib.hrl b/lib/sasl/test/test_lib.hrl index b16c4ac34c..9a54937f96 100644 --- a/lib/sasl/test/test_lib.hrl +++ b/lib/sasl/test/test_lib.hrl @@ -1,3 +1,3 @@ -define(ertsvsn,"4.4"). --define(kernelvsn,"3.0"). --define(stdlibvsn,"2.0"). +-define(kernelvsn,"5.0"). +-define(stdlibvsn,"3.0"). diff --git a/lib/sasl/vsn.mk b/lib/sasl/vsn.mk index e07b36f4ba..52b168598a 100644 --- a/lib/sasl/vsn.mk +++ b/lib/sasl/vsn.mk @@ -1 +1 @@ -SASL_VSN = 2.5 +SASL_VSN = 3.1.2 |
