diff options
Diffstat (limited to 'lib/sasl/doc/src')
| -rw-r--r-- | lib/sasl/doc/src/Makefile | 1 | ||||
| -rw-r--r-- | lib/sasl/doc/src/alarm_handler.xml | 8 | ||||
| -rw-r--r-- | lib/sasl/doc/src/appup.xml | 16 | ||||
| -rw-r--r-- | lib/sasl/doc/src/error_logging.xml | 55 | ||||
| -rw-r--r-- | lib/sasl/doc/src/notes.xml | 116 | ||||
| -rw-r--r-- | lib/sasl/doc/src/rb.xml | 38 | ||||
| -rw-r--r-- | lib/sasl/doc/src/release_handler.xml | 46 | ||||
| -rw-r--r-- | lib/sasl/doc/src/sasl_app.xml | 184 | ||||
| -rw-r--r-- | lib/sasl/doc/src/systools.xml | 22 |
9 files changed, 337 insertions, 149 deletions
diff --git a/lib/sasl/doc/src/Makefile b/lib/sasl/doc/src/Makefile index baf563ca62..8e1e8b502c 100644 --- a/lib/sasl/doc/src/Makefile +++ b/lib/sasl/doc/src/Makefile @@ -101,6 +101,7 @@ debug opt: clean clean_docs: rm -rf $(HTMLDIR)/* + rm -rf $(XMLDIR) rm -f $(MAN3DIR)/* rm -f $(MAN4DIR)/* rm -f $(MAN6DIR)/* diff --git a/lib/sasl/doc/src/alarm_handler.xml b/lib/sasl/doc/src/alarm_handler.xml index 4160757164..6e74f833cd 100644 --- a/lib/sasl/doc/src/alarm_handler.xml +++ b/lib/sasl/doc/src/alarm_handler.xml @@ -34,7 +34,7 @@ <rev>A</rev> <file>alarm_handler.sgml.t1</file> </header> - <module>alarm_handler</module> + <module since="">alarm_handler</module> <modulesummary>An Alarm Handling Process</modulesummary> <description> <p>The alarm handler process is a @@ -81,7 +81,7 @@ <funcs> <func> - <name>clear_alarm(AlarmId) -> void()</name> + <name since="">clear_alarm(AlarmId) -> void()</name> <fsummary>Clears the specified alarms.</fsummary> <type> <v>AlarmId = term()</v> @@ -94,7 +94,7 @@ </func> <func> - <name>get_alarms() -> [alarm()]</name> + <name since="">get_alarms() -> [alarm()]</name> <fsummary>Gets all active alarms.</fsummary> <desc> <p>Returns a list of all active alarms. This function can only @@ -103,7 +103,7 @@ </func> <func> - <name>set_alarm(alarm())</name> + <name since="">set_alarm(alarm())</name> <fsummary>Sets an alarm with an id.</fsummary> <type> <v>alarm() = {AlarmId, AlarmDescription}</v> diff --git a/lib/sasl/doc/src/appup.xml b/lib/sasl/doc/src/appup.xml index a43a966dcb..102ea9e5d7 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>2016</year> + <year>1997</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -249,9 +249,17 @@ <pre> {restart_application, Application} Application = atom()</pre> - <p>Restarting an application means that the application is - stopped and then started again, similar to using the instructions - <c>remove_application</c> and <c>add_application</c> in sequence.</p> + <p>Restarting an application means that the application is stopped + and then started again, similar to using the instructions + <c>remove_application</c> and <c>add_application</c> in sequence. + Note that, even if the application has been started before the + release upgrade is performed, <c>restart_application</c> may only + <c>load</c> it rather than <c>start</c> it, depending on the + application's <c>start type</c>: + 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> </section> <section> diff --git a/lib/sasl/doc/src/error_logging.xml b/lib/sasl/doc/src/error_logging.xml index 4b2c960bbb..e6c244c1b9 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>2016</year> + <year>1997</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -32,22 +32,52 @@ <rev>B</rev> <file>error_logging.xml</file> </header> + <note> + <p>The SASL error logging concept described in this section is + deprecated since Erlang/OTP 21.0, when the + new <seealso marker="kernel:logger_chapter">logging + API</seealso> was introduced.</p> + <p>The new default behaviour is that the SASL application no + longer affects which log events that are logged. + <seealso marker="#supervisor_report">Supervisor + reports</seealso> and <seealso marker="#crash_report">crash + reports</seealso> are logged via the default logger handler + which is setup by + Kernel. <seealso marker="#progress_report">Progress + reports</seealso> are by default not logged, but can be enabled + by setting the primary log level to <c>info</c>, for example by + using the Kernel configuration + parameter <seealso marker="kernel:kernel_app#logger_level"> + <c>logger_level</c></seealso>.</p> + <p>The old SASL error logging behaviour can be re-enabled by setting the + Kernel configuration + parameter <seealso marker="kernel:kernel_app#logger_sasl_compatible"> + <c>logger_sasl_compatible</c></seealso> to <c>true</c>.</p> + <p>The mechanism + for <seealso marker="#multi_file_logging">multi-file error report + logging</seealso> as described in this section is also kept for + backwards compatibility. However, the new logging API also + introduces <seealso marker="kernel:logger_disk_log_h"> + <c>logger_disk_log_h(3)</c></seealso>, which is a logger + handler that can print to multiple files + using <seealso marker="kernel:disk_log"><c>disk_log(3)</c></seealso>.</p> + </note> + + <section> + <title>SASL reports</title> <p>The SASL application introduces three types of reports:</p> <list type="bulleted"> <item>Supervisor report</item> <item>Progress report</item> <item>Crash report</item> </list> - <p>When the SASL application is started, it adds a handler that - formats and writes these reports, as specified in the configuration - parameters for SASL, 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> + <p>When the SASL application is started, it adds a Logger handler + that formats and writes these reports, as specified in + the <seealso marker="sasl_app#deprecated_error_logger_config">configuration + parameters for SASL</seealso>.</p> <section> + <marker id="supervisor_report"/> <title>Supervisor Report</title> <p>A supervisor report is issued when a supervised child terminates unexpectedly. A supervisor report contains the following @@ -68,6 +98,7 @@ </section> <section> + <marker id="progress_report"/> <title>Progress Report</title> <p>A progress report is issued when a supervisor starts or restarts a child. A progress report contains the following items:</p> @@ -82,6 +113,7 @@ </section> <section> + <marker id="crash_report"/> <title>Crash Report</title> <p>Processes started with functions <seealso marker="stdlib:proc_lib#spawn/1"><c>proc_lib:spawn</c></seealso> or @@ -105,6 +137,7 @@ crash. The information gathered is the same as the information for Crasher, described in the previous item.</p></item> </taglist> + </section> <section> <title>Example</title> @@ -163,6 +196,7 @@ </section> <section> + <marker id="multi_file_logging"/> <title>Multi-File Error Report Logging</title> <p>Multi-file error report logging is used to store error messages received by <c>error_logger</c>. The error messages @@ -171,7 +205,8 @@ of files exist at the same time. The logging is very fast, as each error message is written as a binary term.</p> <p>For more details, see the - <seealso marker="sasl_app"><c>sasl(6)</c></seealso> + <seealso marker="sasl_app#deprecated_error_logger_config"> + <c>sasl(6)</c></seealso> application in the Reference Manual.</p> </section> diff --git a/lib/sasl/doc/src/notes.xml b/lib/sasl/doc/src/notes.xml index 791e9c063a..982c874117 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>2017</year> + <year>2004</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -31,6 +31,120 @@ </header> <p>This document describes the changes made to the SASL application.</p> +<section><title>SASL 3.3</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p> + New <c>counters</c> and <c>atomics</c> modules supplies + access to highly efficient operations on mutable fixed + word sized variables.</p> + <p> + Own Id: OTP-13468</p> + </item> + </list> + </section> + +</section> + +<section><title>SASL 3.2.1</title> + + <section><title>Fixed Bugs and Malfunctions</title> + <list> + <item> + <p> + Improved documentation.</p> + <p> + Own Id: OTP-15190</p> + </item> + </list> + </section> + +</section> + +<section><title>SASL 3.2</title> + + <section><title>Improvements and New Features</title> + <list> + <item> + <p>A new logging API is added to Erlang/OTP, see the + <seealso + marker="kernel:logger"><c>logger(3)</c></seealso> manual + page, and section <seealso + marker="kernel:logger_chapter">Logging</seealso> in the + Kernel User's Guide.</p> + <p>Calls to <c>error_logger</c> are automatically + redirected to the new API, and legacy error logger event + handlers can still be used. It is, however, recommended + to use the Logger API directly when writing new code.</p> + <p>Notice the following potential incompatibilities:</p> + <list> <item><p>Kernel configuration parameters + <c>error_logger</c> still works, but is overruled if the + default handler's output destination is configured with + Kernel configuration parameter <c>logger</c>.</p> <p>In + general, parameters for configuring error logger are + overwritten by new parameters for configuring + Logger.</p></item> <item><p>The concept of SASL error + logging is deprecated, meaning that by default the SASL + application does not affect which log events are + logged.</p> <p>By default, supervisor reports and crash + reports are logged by the default Logger handler started + by Kernel, and end up at the same destination (terminal + or file) as other standard log event from Erlang/OTP.</p> + <p>Progress reports are not logged by default, but can be + enabled by setting the primary log level to info, for + example with the Kernel configuration parameter + <c>logger_level</c>.</p> <p>To obtain backwards + compatibility with the SASL error logging functionality + from earlier releases, set Kernel configuration parameter + <c>logger_sasl_compatible</c> to <c>true</c>. This + prevents the default Logger handler from logging any + supervisor-, crash-, or progress reports. Instead, SASL + adds a separate Logger handler during application start, + which takes care of these log events. The SASL + configuration parameters <c>sasl_error_logger</c> and + <c>sasl_errlog_type</c> specify the destination (terminal + or file) and severity level to log for these + events.</p></item></list> + <p> + Since Logger is new in Erlang/OTP 21.0, we do reserve the + right to introduce changes to the Logger API and + functionality in patches following this release. These + changes might or might not be backwards compatible with + the initial version.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-13295</p> + </item> + <item> + <p> + The old and outdated "Status Inspection" tool (modules + <c>si</c> and <c>si_sasl_sup</c>) is removed.</p> + <p> + *** POTENTIAL INCOMPATIBILITY ***</p> + <p> + Own Id: OTP-14469</p> + </item> + <item> + <p> + When creating the release tar file, systools now includes + sys.config.src if it exists in the + $ROOT/releases/<vsn>/ directory. This is to allow + adjustments, e.g. resolving environment variables, after + unpacking the release, but before installing it. This + functionality requires a custom tool which uses + sys.config.src as input and creates a correct sys.config + file.</p> + <p> + Own Id: OTP-14950 Aux Id: PR-1560 </p> + </item> + </list> + </section> + +</section> + <section><title>SASL 3.1.2</title> <section><title>Fixed Bugs and Malfunctions</title> diff --git a/lib/sasl/doc/src/rb.xml b/lib/sasl/doc/src/rb.xml index d5df4fd345..0ed7e91c11 100644 --- a/lib/sasl/doc/src/rb.xml +++ b/lib/sasl/doc/src/rb.xml @@ -32,7 +32,7 @@ <rev>A</rev> <file>rb.sgml</file> </header> - <module>rb</module> + <module since="">rb</module> <modulesummary>The Report Browser Tool</modulesummary> <description> <p>The Report Browser (RB) tool is used to browse and @@ -43,8 +43,8 @@ <funcs> <func> - <name>filter(Filters)</name> - <name>filter(Filters, Dates)</name> + <name since="OTP R13B04">filter(Filters)</name> + <name since="OTP R13B04">filter(Filters, Dates)</name> <fsummary>Filters reports and displays them on the screen.</fsummary> <type> <v>Filters = [filter()]</v> @@ -86,7 +86,7 @@ </func> <func> - <name>grep(RegExp)</name> + <name since="">grep(RegExp)</name> <fsummary>Searches the reports for a regular expression.</fsummary> <type> <v>RegExp = string() | {string(), Options} | re:mp() | {re:mp(), Options}</v> @@ -109,8 +109,8 @@ </func> <func> - <name>h()</name> - <name>help()</name> + <name since="">h()</name> + <name since="">help()</name> <fsummary>Displays help information.</fsummary> <desc> <p>Displays online help information.</p> @@ -118,8 +118,8 @@ </func> <func> - <name>list()</name> - <name>list(Type)</name> + <name since="">list()</name> + <name since="">list(Type)</name> <fsummary>Lists all reports.</fsummary> <type> <v>Type = type()</v> @@ -137,8 +137,8 @@ </func> <func> - <name>log_list()</name> - <name>log_list(Type)</name> + <name since="OTP R16B02">log_list()</name> + <name since="OTP R16B02">log_list(Type)</name> <fsummary>Logs report lists.</fsummary> <type> <v>Type = type()</v> @@ -157,8 +157,8 @@ </func> <func> - <name>rescan()</name> - <name>rescan(Options)</name> + <name since="">rescan()</name> + <name since="">rescan(Options)</name> <fsummary>Rescans the report directory.</fsummary> <type> <v>Options = [opt()]</v> @@ -171,8 +171,8 @@ </func> <func> - <name>show()</name> - <name>show(Report)</name> + <name since="">show()</name> + <name since="">show(Report)</name> <fsummary>Displays reports.</fsummary> <type> <v>Report = integer() | type()</v> @@ -186,8 +186,8 @@ </func> <func> - <name>start()</name> - <name>start(Options)</name> + <name since="">start()</name> + <name since="">start(Options)</name> <fsummary>Starts the <c>rb_server</c>.</fsummary> <type> <v>Options = [opt()]</v> @@ -256,7 +256,7 @@ </func> <func> - <name>start_log(FileName)</name> + <name since="">start_log(FileName)</name> <fsummary>Redirects all output to <c>FileName</c>.</fsummary> <type> <v>FileName = string() | atom() | pid()</v> @@ -268,7 +268,7 @@ </func> <func> - <name>stop()</name> + <name since="">stop()</name> <fsummary>Stops the <c>rb_server</c>.</fsummary> <desc> <p>Stops <c>rb_server</c>.</p> @@ -276,7 +276,7 @@ </func> <func> - <name>stop_log()</name> + <name since="">stop_log()</name> <fsummary>Stops logging to file.</fsummary> <desc> <p>Closes the log file. The output from the RB tool is diff --git a/lib/sasl/doc/src/release_handler.xml b/lib/sasl/doc/src/release_handler.xml index 8f073807fb..f8ee0306d8 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>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -28,7 +28,7 @@ <date></date> <rev></rev> </header> - <module>release_handler</module> + <module since="">release_handler</module> <modulesummary>Unpacking and Installation of Release Packages</modulesummary> <description> <p>The <em>release handler</em> process belongs to the SASL @@ -61,6 +61,7 @@ <list type="bulleted"> <item>A release upgrade file, <c>relup</c></item> <item>A system configuration file, <c>sys.config</c></item> + <item>A system configuration source file, <c>sys.config.src</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> @@ -167,8 +168,8 @@ <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> + <name since="">check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}</name> + <name since="OTP R14B04">check_install_release(Vsn,Opts) -> {ok, OtherVsn, Descr} | {error, Reason}</name> <fsummary>Checks installation of a release in the system.</fsummary> <type> <v>Vsn = OtherVsn = string()</v> @@ -201,7 +202,7 @@ </func> <func> - <name>create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}</name> + <name since="">create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason}</name> <fsummary>Creates an initial <c>RELEASES</c> file.</fsummary> <type> <v>Root = RelDir = RelFile = string()</v> @@ -232,7 +233,7 @@ </func> <func> - <name>install_file(Vsn, File) -> ok | {error, Reason}</name> + <name since="">install_file(Vsn, File) -> ok | {error, Reason}</name> <fsummary>Installs a release file in the release structure.</fsummary> <type> <v>Vsn = File = string()</v> @@ -251,8 +252,8 @@ </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> + <name since="">install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason}</name> + <name since="">install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_after_restart, OtherVsn, Descr} | {error, Reason}</name> <fsummary>Installs a release in the system.</fsummary> <type> <v>Vsn = OtherVsn = string()</v> @@ -382,7 +383,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). </func> <func> - <name>make_permanent(Vsn) -> ok | {error, Reason}</name> + <name since="">make_permanent(Vsn) -> ok | {error, Reason}</name> <fsummary>Makes the specified release version permanent.</fsummary> <type> <v>Vsn = string()</v> @@ -395,7 +396,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). </func> <func> - <name>remove_release(Vsn) -> ok | {error, Reason}</name> + <name since="">remove_release(Vsn) -> ok | {error, Reason}</name> <fsummary>Removes a release from the system.</fsummary> <type> <v>Vsn = string()</v> @@ -409,7 +410,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). </func> <func> - <name>reboot_old_release(Vsn) -> ok | {error, Reason}</name> + <name since="">reboot_old_release(Vsn) -> ok | {error, Reason}</name> <fsummary>Reboots the system from an old release.</fsummary> <type> <v>Vsn = string()</v> @@ -424,7 +425,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). </func> <func> - <name>set_removed(Vsn) -> ok | {error, Reason}</name> + <name since="">set_removed(Vsn) -> ok | {error, Reason}</name> <fsummary>Marks a release as removed.</fsummary> <type> <v>Vsn = string()</v> @@ -439,7 +440,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). </func> <func> - <name>set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}</name> + <name since="">set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason}</name> <fsummary>Marks a release as unpacked.</fsummary> <type> <v>RelFile = string()</v> @@ -465,7 +466,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). </func> <func> - <name>unpack_release(Name) -> {ok, Vsn} | {error, Reason}</name> + <name since="">unpack_release(Name) -> {ok, Vsn} | {error, Reason}</name> <fsummary>Unpacks a release package.</fsummary> <type> <v>Name = Vsn = string()</v> @@ -481,7 +482,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). </func> <func> - <name>which_releases() -> [{Name, Vsn, Apps, Status}]</name> + <name since="">which_releases() -> [{Name, Vsn, Apps, Status}]</name> <fsummary>Returns all known releases.</fsummary> <type> <v>Name = Vsn = string()</v> @@ -494,7 +495,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). </func> <func> - <name>which_releases(Status) -> [{Name, Vsn, Apps, Status}]</name> + <name since="OTP R15B">which_releases(Status) -> [{Name, Vsn, Apps, Status}]</name> <fsummary>Returns all known releases of a specific status.</fsummary> <type> <v>Name = Vsn = string()</v> @@ -536,7 +537,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). <funcs> <func> - <name>upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name> + <name since="">upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name> <fsummary>Upgrades to a new application version.</fsummary> <type> <v>App = atom()</v> @@ -585,8 +586,8 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). </func> <func> - <name>downgrade_app(App, Dir) -></name> - <name>downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name> + <name since="">downgrade_app(App, Dir) -></name> + <name since="">downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name> <fsummary>Downgrades to a previous application version.</fsummary> <type> <v>App = atom()</v> @@ -632,7 +633,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). </func> <func> - <name>upgrade_script(App, Dir) -> {ok, NewVsn, Script}</name> + <name since="">upgrade_script(App, Dir) -> {ok, NewVsn, Script}</name> <fsummary>Finds an application upgrade script.</fsummary> <type> <v>App = atom()</v> @@ -670,7 +671,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). </func> <func> - <name>downgrade_script(App, OldVsn, Dir) -> {ok, Script}</name> + <name since="">downgrade_script(App, OldVsn, Dir) -> {ok, Script}</name> <fsummary>Finds an application downgrade script.</fsummary> <type> <v>App = atom()</v> @@ -709,7 +710,7 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). </func> <func> - <name>eval_appup_script(App, ToVsn, ToDir, Script) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name> + <name since="">eval_appup_script(App, ToVsn, ToDir, Script) -> {ok, Unpurged} | restart_emulator | {error, Reason}</name> <fsummary>Evaluates an application upgrade or downgrade script.</fsummary> <type> <v>App = atom()</v> @@ -819,4 +820,3 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). <seealso marker="systools"><c>systools(3)</c></seealso></p> </section> </erlref> - diff --git a/lib/sasl/doc/src/sasl_app.xml b/lib/sasl/doc/src/sasl_app.xml index e0693fcb60..fc83f63fe6 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>2016</year> + <year>1996</year><year>2018</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -34,12 +34,9 @@ <p>The SASL application provides the following services:</p> <list type="bulleted"> <item><c>alarm_handler</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> @@ -47,51 +44,101 @@ </description> <section> - <title>Error Logger Event Handlers</title> - <p>The following error logger event handlers are used by - the SASL application.</p> + <title>Configuration</title> + <p>The following configuration parameters are defined for the SASL + 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[start_prg = string() ]]></c></tag> + <item> + <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()] ]]></c></tag> + <item> + <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() ]]></c></tag> + <item> + <p>This parameter specifies the client directory at the master + 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 ]]></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 parameters <c>masters</c> + and <c>client_directory</c> are not set.</p> + </item> + <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. + If this parameter is not set, the OS environment parameter + <c>RELDIR</c> is used. By default, this is + <c>$OTP_ROOT/releases</c>.</p> + </item> + </taglist> + </section> + + <section> + <marker id="deprecated_error_logger_config"/> + <title>Deprecated Error Logger Event Handlers and Configuration</title> + <p>In Erlang/OTP 21.0, a new API for logging was added. The + old <c>error_logger</c> event manager, and event handlers + running on this manager, still work, but they are not used + by default.</p> + <p>The error logger event handlers <c>sasl_report_tty_h</c> + and <c>sasl_report_file_h</c>, were earlier used for printing + the so called SASL reports, i.e. <em>supervisor + reports</em>, <em>crash reports</em>, and <em>progress + reports</em>. These reports are now also printed by the default + logger handler started by the Kernel application. Progress + reports are by default stopped by the primary log level, but can + be enabled by setting this level to <c>info</c>, for example by + using the Kernel configuration + parameter <seealso marker="kernel:kernel_app#logger_level"> + <c>logger_level</c></seealso>.</p> + <p>If the old error logger event handlers are still desired, they + must be added by + calling <c>error_logger:add_report_handler/1,2</c>.</p> <taglist> <tag><c>sasl_report_tty_h</c></tag> <item> <p>Formats and writes <em>supervisor reports</em>, <em>crash reports</em>, and <em>progress reports</em> to <c>stdio</c>. 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> + <seealso marker="kernel:kernel_app#deprecated-configuration-parameters"><c>error_logger_format_depth</c></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. 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. 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> + <seealso marker="kernel:kernel_app#deprecated-configuration-parameters"><c>error_logger_format_depth</c></seealso> + in the Kernel application to limit the details printed in + crash and supervisor reports.</p> </item> </taglist> - </section> - - <section> - <title>Configuration</title> - <p>The following configuration parameters are defined for the SASL - 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> + <p>A similar behaviour, but still using the new logger API, can be + obtained by setting the Kernel application environment + variable <seealso marker="kernel:kernel_app#logger_sasl_compatible"> + <c>logger_sasl_compatible</c></seealso> to <c>true</c>. This + adds a second instance of the standard Logger handler, + named <c>sasl</c>, which only prints the SASL reports. No SASL + reports are then printed by the Kernel logger handler.</p> + <p>The <c>sasl</c> handler is configured according to the values + of the following SASL application environment variables.</p> <taglist> <tag><c><![CDATA[sasl_error_logger = Value ]]></c></tag> <item> @@ -124,6 +171,25 @@ <c>sasl_error_logger</c> to error reports or progress reports, or both. Default is <c>all</c>.</p> </item> + <tag><marker id="utc_log"/><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 + <c>UTC</c> appended.</p> + </item> + </taglist> + + <p>The error logger event handler <c>log_mf_h</c> can also still + be used. This event handler 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:</p> + <taglist> <tag><c><![CDATA[error_logger_mf_dir = string() | false ]]></c></tag> <item> <p>Specifies in which directory <c>log_mf_h</c> is to store @@ -142,55 +208,19 @@ this parameter is undefined, the <c>log_mf_h</c> handler is not installed.</p> </item> - <tag><c><![CDATA[start_prg = string() ]]></c></tag> - <item> - <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()] ]]></c></tag> - <item> - <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() ]]></c></tag> - <item> - <p>This parameter specifies the client directory at the master - 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 ]]></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 parameters <c>masters</c> - and <c>client_directory</c> are not set.</p> - </item> - <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. - If this parameter is not set, the OS environment parameter - <c>RELDIR</c> is used. By default, this is - <c>$OTP_ROOT/releases</c>.</p> - </item> - <tag><c><![CDATA[utc_log = true | false ]]></c></tag> - <item> - <p>If set to <c>true</c>, all dates in textual log outputs are - displayed in Universal Coordinated Time with the string - <c>UTC</c> appended.</p> - </item> </taglist> + <p>The new <seealso marker="kernel:logger_disk_log_h"> + <c>logger_disk_log_h</c></seealso> might be an alternative + to <c>log_mf_h</c> if log rotation is desired. This does, + however, write the log events in clear text and not as binaries.</p> + </section> <section> <title>See Also</title> <p><seealso marker="alarm_handler"><c>alarm_handler(3)</c></seealso>, <seealso marker="kernel:error_logger"><c>error_logger(3)</c></seealso>, + <seealso marker="kernel:logger"><c>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>, diff --git a/lib/sasl/doc/src/systools.xml b/lib/sasl/doc/src/systools.xml index e7c3c499da..6facb8ddae 100644 --- a/lib/sasl/doc/src/systools.xml +++ b/lib/sasl/doc/src/systools.xml @@ -30,7 +30,7 @@ <date></date> <rev></rev> </header> - <module>systools</module> + <module since="">systools</module> <modulesummary>A Set of Release Handling Tools</modulesummary> <description> <p>This module contains functions to generate boot scripts @@ -40,8 +40,8 @@ <funcs> <func> - <name>make_relup(Name, UpFrom, DownTo) -> Result</name> - <name>make_relup(Name, UpFrom, DownTo, [Opt]) -> Result</name> + <name since="">make_relup(Name, UpFrom, DownTo) -> Result</name> + <name since="">make_relup(Name, UpFrom, DownTo, [Opt]) -> Result</name> <fsummary>Generates a release upgrade file <c>relup</c>.</fsummary> <type> <v>Name = string()</v> @@ -136,8 +136,8 @@ </func> <func> - <name>make_script(Name) -> Result</name> - <name>make_script(Name, [Opt]) -> Result</name> + <name since="">make_script(Name) -> Result</name> + <name since="">make_script(Name, [Opt]) -> Result</name> <fsummary>Generates a boot script <c>.script/.boot</c>.</fsummary> <type> <v>Name = string()</v> @@ -263,8 +263,8 @@ </func> <func> - <name>make_tar(Name) -> Result</name> - <name>make_tar(Name, [Opt]) -> Result</name> + <name since="">make_tar(Name) -> Result</name> + <name since="">make_tar(Name, [Opt]) -> Result</name> <fsummary>Creates a release package.</fsummary> <type> <v>Name = string()</v> @@ -349,10 +349,11 @@ myapp-1/ebin/myapp.app 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 + the files <c>relup</c> and <c>sys.config</c> or <c>sys.config.src</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 option <c>path</c>.</p> + specified using option <c>path</c>. In the case of <c>sys.config</c> + it is not included if <c>sys.config.src</c> is found.</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> @@ -368,7 +369,7 @@ myapp-1/ebin/myapp.app </func> <func> - <name>script2boot(File) -> ok | error</name> + <name since="">script2boot(File) -> ok | error</name> <fsummary>Generates a binary version of a boot script.</fsummary> <type> <v>File = string()</v> @@ -397,4 +398,3 @@ myapp-1/ebin/myapp.app <seealso marker="script"><c>script(4)</c></seealso></p> </section> </erlref> - |