From f84858101803153a04caeb1b300b80e376fc105d Mon Sep 17 00:00:00 2001 From: xsipewe Date: Fri, 2 Oct 2015 13:01:27 +0200 Subject: sasl: Editorial changes --- lib/sasl/doc/src/alarm_handler.xml | 84 ++-- lib/sasl/doc/src/appup.xml | 449 +++++++++++---------- lib/sasl/doc/src/book.xml | 4 +- lib/sasl/doc/src/error_logging.xml | 215 +++++----- lib/sasl/doc/src/overload.xml | 124 +++--- lib/sasl/doc/src/part.xml | 5 +- lib/sasl/doc/src/rb.xml | 285 +++++++------- lib/sasl/doc/src/ref_man.xml | 4 +- lib/sasl/doc/src/rel.xml | 91 ++--- lib/sasl/doc/src/release_handler.xml | 743 +++++++++++++++++++---------------- lib/sasl/doc/src/relup.xml | 70 ++-- lib/sasl/doc/src/sasl_app.xml | 178 +++++---- lib/sasl/doc/src/sasl_intro.xml | 38 +- lib/sasl/doc/src/script.xml | 157 ++++---- lib/sasl/doc/src/systools.xml | 347 ++++++++-------- 15 files changed, 1434 insertions(+), 1360 deletions(-) (limited to 'lib/sasl/doc') diff --git a/lib/sasl/doc/src/alarm_handler.xml b/lib/sasl/doc/src/alarm_handler.xml index b98f22d2a1..68076ba28d 100644 --- a/lib/sasl/doc/src/alarm_handler.xml +++ b/lib/sasl/doc/src/alarm_handler.xml @@ -37,94 +37,92 @@ alarm_handler An Alarm Handling Process -

The alarm handler process is a gen_event 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. -

+

The alarm handler process is a + gen_event + 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.

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. -

-

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. -

-

The alarm handler is part of the SASL application. -

+ 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.

+

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).

+

The alarm handler is part of the SASL application.

When writing new event handlers for the alarm handler, the - following events must be handled: -

+ following events must be handled:

{set_alarm, {AlarmId, AlarmDescr}}

This event is generated by - alarm_handler:set_alarm({AlarmId, AlarmDecsr}). -

+ alarm_handler:set_alarm({AlarmId, AlarmDecsr}).

 {clear_alarm, AlarmId}

This event is - generated by alarm_handler:clear_alarm(AlarmId). -

+ generated by alarm_handler:clear_alarm(AlarmId).

The default simple handler is called alarm_handler and - it may be exchanged by calling gen_event:swap_handler/3 - as gen_event:swap_handler(alarm_handler, {alarm_handler, swap}, {NewHandler, Args}). NewHandler:init({Args, {alarm_handler, Alarms}}) is called. Refer to gen_event(3) - for further details. -

+ it can be exchanged by calling + gen_event:swap_handler/3 + as gen_event:swap_handler(alarm_handler, {alarm_handler, swap}, + {NewHandler, Args}). NewHandler:init({Args, {alarm_handler, + Alarms}}) is called. For more details, see + gen_event(3) + in STDLIB.

 + clear_alarm(AlarmId) -> void() - Clear the specified alarms + Clears the specified alarms. AlarmId = term() -

Sends the clear_alarm event to all event handlers.

+

Sends event clear_alarm to all event handlers.

When receiving this event, the default simple handler - clears the latest received alarm with id AlarmId. -

+ clears the latest received alarm with id AlarmId.

 + get_alarms() -> [alarm()] - Get all active alarms + Gets all active alarms.

Returns a list of all active alarms. This function can only - be used when the simple handler is installed. -

+ be used when the simple handler is installed.

 + set_alarm(alarm()) - Set an alarm with an id + Sets an alarm with an id. alarm() = {AlarmId, AlarmDescription} AlarmId = term() AlarmDescription = term() -

Sends the set_alarm event to all event handlers.

+

Sends event set_alarm to all event handlers.

When receiving this event, the default simple handler - stores the alarm. The AlarmId identifies the alarm - and is used when the alarm is cleared. -

+ stores the alarm. AlarmId identifies the alarm + and is used when the alarm is cleared.
See Also -

error_logger(3), gen_event(3) -

+

error_logger(3), + gen_event(3)

diff --git a/lib/sasl/doc/src/appup.xml b/lib/sasl/doc/src/appup.xml index 72333960ec..b54d2adb19 100644 --- a/lib/sasl/doc/src/appup.xml +++ b/lib/sasl/doc/src/appup.xml @@ -29,78 +29,85 @@ appup - Application upgrade file. + Application upgrade file

The application upgrade file defines how an application is upgraded or downgraded in a running system.

-

This file is used by the functions in systools when - generating a release upgrade file relup.

+

This file is used by the functions in + systools + when generating a release upgrade file relup.
- FILE SYNTAX -

The application upgrade file should be called - Application.appup where Application is the name of - the application. The file should be located in the ebin + File Syntax +

The application upgrade file is to be called + Application.appup, where Application is the + application name. The file is to be located in the ebin directory for the application.

The .appup file contains one single Erlang term, which defines the instructions used to upgrade or downgrade - the application. The file has the following syntax:

+ the application. The file has the following syntax:

{Vsn, [{UpFromVsn, Instructions}, ...], - [{DownToVsn, Instructions}, ...]}. - - - -

Vsn = string() is the current version of - the application.

- - -

UpFromVsn = string() | binary() 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.

- - -

DownToVsn = string() | binary() 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.

- - -

Instructions is a list of release upgrade instructions, see below. It is recommended to use + [{DownToVsn, Instructions}, ...]}. + + Vsn = string() +

Current application version.

 + UpFromVsn = string() | binary() +

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.

 + DownToVsn = string() | binary() +

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.

 + Instructions +

A list of release upgrade instructions, see + Release + Upgrade Instructions. It is recommended to use high-level instructions only. These are automatically translated to low-level instructions by systools when - creating the relup file.

- - -

In order to avoid duplication of upgrade instructions it is - allowed to use regular expressions to specify the UpFromVsn - and DownToVsn. To be considered a regular expression, the - version identifier must be specified as a binary, e.g.

- <<"2\\.1\\.[0-9]+">> -

will match all versions 2.1.x, where x is any number.

-

Note that the regular expression must match the complete - version string, so the above example will work for for - e.g. 2.1.1, but not for 2.1.1.1

+ creating the relup file.

+ +

To avoid duplication of upgrade instructions, it is + allowed to use regular expressions to specify UpFromVsn + and DownToVsn. To be considered a regular expression, the + version identifier must be specified as a binary. For example, + the following match all versions 2.1.x, where x is + any number:

+ +<<"2\\.1\\.[0-9]+">> +

Notice that the regular expression must match the complete + version string, so this example works for, for example, + 2.1.1, but not for 2.1.1.1.

- RELEASE UPGRADE INSTRUCTIONS + + Release Upgrade Instructions

Release upgrade instructions are interpreted by the release handler when an upgrade or downgrade is made. For more - information about release handling, refer to OTP Design Principles.

-

A process is said to use a module Mod, if + information about release handling, see + OTP + Design Principles in System Documentation.

+

A process is said to use a module Mod if Mod is listed in the Modules part of the child - specification used to start the process, see supervisor(3). - In the case of gen_event, an event manager process is said to use - Mod if Mod is an installed event handler.

-

High-level instructions

+ specification used to start the process, see + supervisor(3). + In the case of + gen_event, + an event manager process is said to use Mod if Mod + is an installed event handler.

+ +
+ High-Level Instructions 
 {update, Mod}
 {update, Mod, supervisor}
@@ -116,52 +123,68 @@
   Change = soft | {advanced,Extra}
     Extra = term()
   PrePurge = PostPurge = soft_purge | brutal_purge
-  DepMods = [Mod]
-
-

Synchronized code replacement of processes using the module - Mod. All those processes are suspended using - sys:suspend, the new version of the module is loaded and - then the processes are resumed using sys:resume.

-

Change defaults to soft and defines the type of - code change. If it is set to {advanced,Extra}, processes - implemented using gen_server, gen_fsm or gen_event will transform - their internal state by calling the callback function - code_change. Special processes will call the callback + DepMods = [Mod] +

Synchronized code replacement of processes using module + Mod.

+

All those processes are suspended using + sys:suspend, + the new module version is loaded, and + then the processes are resumed using + sys:resume.

+ + Change +

Defaults to soft and defines the type of + code change. If it is set to {advanced,Extra}, implemented + processes using + gen_server, + gen_fsm, or + gen_event + transform their internal state by calling the callback function + code_change. Special processes call the callback function system_code_change/4. In both cases, the term - Extra is passed as an argument to the callback function.

-

PrePurge defaults to brutal_purge and controls - what action to take with processes that are executing old code - before loading the new version of the module. If the value + Extra is passed as an argument to the callback + function.

 + PrePurge +

Defaults to brutal_purge. It controls + what action to take with processes executing old code + before loading the new module version. If the value is brutal_purge, the processes are killed. If the value is - soft_purge, release_handler:install_release/1 - returns {error,{old_processes,Mod}}.

-

PostPurge defaults to brutal_purge and controls + soft_purge, + release_handler:install_release/1 + returns {error,{old_processes,Mod}}.

 + PostPurge +

Defaults to brutal_purge. 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 brutal_purge, the code is purged when the release is made permanent and the processes are killed. If the value is - soft_purge, the release handler will purge the old code - when no remaining processes execute the code.

-

DepMods defaults to [] and defines which other modules - Mod is dependent on. In relup, instructions for - suspending processes using Mod will come before + soft_purge, the release handler purges the old code + when no remaining processes execute the code.

 + DepMods +

Defaults to [] and defines other modules that + Mod is dependent on. In the relup file, instructions + for suspending processes using Mod come before instructions for suspending processes using modules in - DepMods when upgrading, and vice versa when downgrading. + DepMods when upgrading, and conversely when downgrading. In case of circular dependencies, the order of the instructions in - the appup script is kept.

-

Timeout defines the timeout when suspending processes. - If no value or default is given, the default value for - sys:suspend is used.

-

ModType defaults to dynamic 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 appup file is kept.

 + Timeout +

Defines the time-out when suspending processes. + If no value or default is specified, the default value for + sys:suspend + is used.

 + ModType +

Defaults to dynamic. 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.

+ dynamic.

 +

update with argument supervisor is used when changing the start specification of a supervisor.

@@ -170,239 +193,229 @@
 {load_module, Mod, PrePurge, PostPurge, DepMods}
   Mod = atom()
   PrePurge = PostPurge = soft_purge | brutal_purge
-  DepMods = [Mod]
-
+ DepMods = [Mod]

Simple code replacement of the module Mod.

-

See update above for a description of PrePurge and - PostPurge.

-

DepMods defaults to [] and defines which other modules - Mod is dependent on. In relup, instructions for - loading these modules will come before the instruction for loading - Mod when upgrading, and vice versa when downgrading.

+

For a description of PrePurge and PostPurge, + see update above.

+

DepMods defaults to [] and defines which other modules + Mod is dependent on. In the relup file, instructions for + loading these modules come before the instruction for loading + Mod when upgrading, and conversely when downgrading.

 {add_module, Mod}
 {add_module, Mod, DepMods}
   Mod = atom()
-  DepMods = [Mod]
-
+ DepMods = [Mod]

Loads a new module Mod.

-

DepMods defaults to [] and defines which other modules - Mod is dependent on. In relup, instructions - related to these modules will come before the instruction for - loading Mod when upgrading, and vice versa when +

DepMods defaults to [] and defines which other modules + Mod is dependent on. In the relup file, instructions + related to these modules come before the instruction for + loading Mod when upgrading, and conversely when downgrading.

 {delete_module, Mod}
 {delete_module, Mod, DepMods}
-  Mod = atom()
-
+ Mod = atom()

Deletes a module Mod using the low-level instructions remove and purge.

-

DepMods defaults to [] and defines which other modules - Mod is dependent on. In relup, instructions - related to these modules will come before the instruction for - removing Mod when upgrading, and vice versa when +

DepMods defaults to [] and defines which other modules + Mod is dependent on. In the relup file, instructions + related to these modules come before the instruction for + removing Mod when upgrading, and conversely when downgrading.

 {add_application, Application}
 {add_application, Application, Type}
   Application = atom()
-  Type = permanent | transient | temporary | load | none
-
+ Type = permanent | transient | temporary | load | none

Adding an application means that the modules defined by the modules key in the .app file are loaded using add_module.

Type defaults to permanent and specifies the start type of the application. If Type = permanent | transient | temporary, - the application will be loaded and started in the corresponding way, - see application(3). If Type = load, the application will - only be loaded. If Type = none, the application will be neither - loaded nor started, although the code for its modules will be loaded.

+ the application is loaded and started in the corresponding way, see + application(3). + If Type = load, the application is only loaded. + If Type = none, the application is not loaded and not + started, although the code for its modules is loaded.

 {remove_application, Application}
-  Application = atom()
-
+ Application = atom()

Removing an application means that the application is stopped, - the modules are unloaded using delete_module and then + the modules are unloaded using delete_module, and then the application specification is unloaded from the application controller.

 {restart_application, Application}
-  Application = atom()
-
+ Application = atom()

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 remove_application and add_application in sequence.

-

Low-level instructions

+
+ +
+ Low-Level Instructions 
 {load_object_code, {App, Vsn, [Mod]}}
   App = Mod = atom()
-  Vsn = string()
-
-

Reads each Mod from the directory App-Vsn/ebin 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 App.

+ Vsn = string() +

Reads each Mod from directory App-Vsn/ebin 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.

-point_of_no_return
-
+point_of_no_return

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 load_object_code instructions.

 {load, {Mod, PrePurge, PostPurge}}
   Mod = atom()
-  PrePurge = PostPurge = soft_purge | brutal_purge
-
+ PrePurge = PostPurge = soft_purge | brutal_purge

Before this instruction occurs, Mod must have been loaded using load_object_code. This instruction loads the module. - PrePurge is ignored. See the high-level instruction - update for a description of PostPurge.

+ PrePurge is ignored. For a description of PostPurge, + see the high-level instruction update earlier.

 {remove, {Mod, PrePurge, PostPurge}}
   Mod = atom()
-  PrePurge = PostPurge = soft_purge | brutal_purge
-
+ PrePurge = PostPurge = soft_purge | brutal_purge

Makes the current version of Mod old. - PrePurge is ignored. See the high-level instruction - update for a description of PostPurge.

+ PrePurge is ignored. For a description of PostPurge, + see the high-level instruction update earlier.

 {purge, [Mod]}
-  Mod = atom()
-
-

Purges each module Mod, that is removes the old code. - Note that any process executing purged code is killed.

+ Mod = atom() +

Purges each module Mod, that is, removes the old code. + Notice that any process executing purged code is killed.

 {suspend, [Mod | {Mod, Timeout}]}
   Mod = atom()
-  Timeout = int()>0 | default | infinity
-
+ Timeout = int()>0 | default | infinity

Tries to suspend all processes using a module Mod. 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 Timeout is specified or default is - given, the default value for sys:suspend is used.

+ specified, the default value for + sys:suspend + is used.

 {resume, [Mod]}
-  Mod = atom()
-
+ Mod = atom()

Resumes all suspended processes using a module Mod.

 {code_change, [{Mod, Extra}]}
 {code_change, Mode, [{Mod, Extra}]}
   Mod = atom()
   Mode = up | down
-  Extra = term()
-
+ Extra = term()

Mode defaults to up and specifies if it is an - upgrade or downgrade.

-

This instruction sends a code_change system message to - all processes using a module Mod by calling the function - sys:change_code, passing the term Extra as argument.

+ upgrade or downgrade. This instruction sends a code_change + system message to all processes using a module Mod by + calling function + sys:change_code, + passing term Extra as argument.

 {stop, [Mod]}
-  Mod = atom()
-
+ Mod = atom()

Stops all processes using a module Mod by calling - supervisor:terminate_child/2. The instruction is useful + supervisor:terminate_child/2. + This instruction is useful when the simplest way to change code is to stop and restart the - processes which run the code.

+ processes that run the code.

 {start, [Mod]}
-  Mod = atom()
-
+ Mod = atom()

Starts all stopped processes using a module Mod by calling - supervisor:restart_child/2.

+ supervisor:restart_child/2.

 {sync_nodes, Id, [Node]}
 {sync_nodes, Id, {M, F, A}}
   Id = term()
   Node = node()
   M = F = atom()
-  A = [term()]
-
+ A = [term()]

apply(M, F, A) must return a list of nodes.

-

The instruction synchronizes the release installation with other - nodes. Each Node must evaluate this command, with the same +

This instruction synchronizes the release installation with other + nodes. Each Node must evaluate this command with the same Id. 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.

 {apply, {M, F, A}}
   M = F = atom()
-  A = [term()]
-
-

Evaluates apply(M, F, A). If the instruction appears - before the point_of_no_return instruction, a failure is - caught. release_handler:install_release/1 then returns - {error,{'EXIT',Reason}}, unless {error,Error} is - thrown or returned. Then it returns {error,Error}.

-

If the instruction appears after the point_of_no_return - instruction, and the function call fails, the system is - restarted.

+ A = [term()] +

Evaluates apply(M, F, A).

+

If the instruction appears before instruction + point_of_no_return, a failure is caught. + release_handler:install_release/1 + then returns {error,{'EXIT',Reason}}, unless {error,Error} + is thrown or returned. Then it returns {error,Error}.

+

If the instruction appears after instruction + point_of_no_return and the function call fails, the + system is restarted.

-restart_new_emulator
-
-

This instruction is used when erts, kernel, stdlib or sasl is +restart_new_emulator +

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 restart_new_emulator - instruction is allowed in the relup, and it shall be placed - first. systools:make_relup/3,4 - 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.

-

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 restart_new_emulator instruction is allowed + in the relup file, and it must be placed first. + systools:make_relup/3,4 + ensures this when the relup file is generated. The rest of the + instructions in the relup file is executed after the + restart as a part of the boot script.

+

An info report is written when the upgrade is completed. + To programmatically determine if the upgrade is complete, call - release_handler:which_releases/0,1 and check if the + release_handler:which_releases/0,1 and check if the expected release has status current.

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.

-

As stated above, the restart_new_emulator - instruction causes the emulator to be restarted with new - versions of erts, kernel, stdlib and - sasl. 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.

+

As stated earlier, instruction restart_new_emulator + 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.

 
-restart_emulator
-
+restart_emulator

This instruction is similar to restart_new_emulator, - 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 relup 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, systools:make_relup/3,4 + reboot of the system is required.

+

When generating the relup file, + systools:make_relup/3,4 ensures that there is only one restart_emulator - instruction and that it is the last instruction of the - relup.

+ instruction and that it is the last instruction in the + relup file.

+
- SEE ALSO -

relup(4), - release_handler(3), - supervisor(3), - systools(3)

+ See Also +

release_handler(3), + relup(4), + supervisor(3), + systools(3)

diff --git a/lib/sasl/doc/src/book.xml b/lib/sasl/doc/src/book.xml index 2bb5339d94..624c32a66f 100644 --- a/lib/sasl/doc/src/book.xml +++ b/lib/sasl/doc/src/book.xml @@ -22,7 +22,7 @@ - System Application Support Libraries (SASL) + System Architecture Support Libraries (SASL) OTP Team 1999-04-22 @@ -31,7 +31,7 @@ - System Application Support Libraries (SASL) + System Architecture Support Libraries (SASL) diff --git a/lib/sasl/doc/src/error_logging.xml b/lib/sasl/doc/src/error_logging.xml index 7c45b1970e..46b12f3872 100644 --- a/lib/sasl/doc/src/error_logging.xml +++ b/lib/sasl/doc/src/error_logging.xml @@ -31,89 +31,93 @@ 1999-04-13 B error_logging.xml - -

The SASL application introduces three types of reports:

+ +

The SASL application introduces three types of reports:

- supervisor report - progress report - crash report. + Supervisor report + Progress report + Crash report -

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 - .app file of SASL. See - sasl(Application), and app(File) - in the Kernel Reference Manual - for the details.

+

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 + .app file of SASL. For details, see the + sasl(6) application in the + Reference Manual and the app(4) + file in the Kernel Reference Manual.

Supervisor Report -

A supervisor report is issued when a supervised child terminates in - an unexpected way. A supervisor report contains the following +

A supervisor report is issued when a supervised child terminates + unexpectedly. A supervisor report contains the following items:

- Supervisor. - The name of the reporting supervisor. - Context. - Indicates in which phase the child terminated + Supervisor +

Name of the reporting supervisor.

 + Context +

Indicates in which phase the child terminated from the supervisor's point of view. This can be - start_error, child_terminated, or - shutdown_error. - Reason. - The termination reason. - Offender. - The start specification for the child. + start_error, child_terminated, or + shutdown_error.

 + Reason +

Termination reason.

 + Offender +

Start specification for the child.
Progress Report -

A progress report is issued whenever a supervisor starts or - restarts. A progress report contains the following items:

+

A progress report is issued when a supervisor starts or + restarts a child. A progress report contains the following items:

- Supervisor. - The name of the reporting supervisor. - Started. - The start specification for the successfully - started child. + Supervisor +

Name of the reporting supervisor.

 + Started +

Start specification for the successfully + started child.
Crash Report -

Processes started with the proc_lib:spawn or - proc_lib:spawn_link functions are wrapped within a - catch. A crash report is issued whenever such a process - terminates with an unexpected reason, which is any reason other - than normal or shutdown. Processes using the - gen_server and gen_fsm behaviours are examples of - such processes. A crash report contains the following items:

+

Processes started with functions + proc_lib:spawn or + proc_lib:spawn_link + are wrapped within a catch. A crash report is issued when such + a process terminates with an unexpected reason, which is any reason + other than normal, shutdown, or {shutdown,Term}. + Processes using behaviors + gen_server or + gen_fsm + are examples of such processes. A crash report contains the following items:

- Crasher. - Information about the crashing process is reported, such - as initial function call, exit reason, and message queue. - Neighbours. - Information about processes which are linked to the crashing + Crasher +

Information about the crashing process, such + as initial function call, exit reason, and message queue.

 + Neighbours +

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. + for Crasher, described in the previous item.
- An Example -

The following example shows the reports which are generated - when a process crashes. The example process is an + Example +

The following example shows the reports generated + when a process crashes. The example process is a permanent process supervised by the test_sup 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 - proc_lib:spawn/3 function. The supervisor generates a - supervisor report showing the process that has crashed, and then a + generated, as the process was started using function + proc_lib:spawn/3. + The supervisor generates a + supervisor report showing the crashed process. A progress report is generated when the process is finally - re-started.

+ restarted.

         =ERROR REPORT==== 27-May-1996::13:38:56 ===
         <0.63.0>: Divide by zero !
@@ -146,7 +150,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 +157,66 @@
         {mfa,{test,t,[]}},
         {restart_type,permanent},
         {shutdown,200},
-        {child_type,worker}]
-
+ {child_type,worker}]
Multi-File Error Report Logging -

Multi-file error report logging is used to store error messages, - which are received by the error_logger. The error messages +

Multi-file error report logging is used to store error messages + received by error_logger. 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.

-

Refer to - sasl application in the Reference Manual for more details.

+

For more details, see the + sasl(6) + application in the Reference Manual.

Report Browser

The report browser is used to browse and format error reports - written by the error logger handler log_mf_h defined in - stdlib.

+ written by the error logger handler + log_mf_h + defined in STDLIB.

The log_mf_h handler writes all reports to a - report logging directory. This directory is specified when - configuring the SASL application.

+ report logging directory, which is specified when + configuring the SASL application.

If the report browser is - used off-line, the reports can be copied to another directory - which is specified when starting the browser. If no such directory - is specified, the browser reads reports from the SASL + 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 error_logger_mf_dir.

- Starting the Report Browser -

Start the rb_server with the function - rb:start([Options]) as shown in the following - example:

+ Starting Report Browser +

Start the rb_server with function + rb:start([Options]) + as shown in the following example:

-
-        5>rb:start([{max, 20}]).
+        5> rb:start([{max, 20}]).
         rb: reading report...done.
         rb: reading report...done.
         rb: reading report...done.
         rb: reading report...done.
-
+ {ok,<0.199.0>}
- On-line Help -

Enter the command rb:help(). to access the report - browser on-line help system.

+ Online Help +

Enter command + rb:help() + to access the report browser online help system.

- List Reports in the Server -

The function rb:list() lists all loaded reports:

+ List Reports in Server +

Use function + rb:list() + to list all loaded reports:

-
-        4>rb:list().
+        4> rb:list().
         No                Type          Process       Date     Time
         ==                ====          =======       ====     ====
         20            progress         <0.17.0> 1996-10-16 16:14:54
@@ -234,17 +239,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
-
+ ok
Show Reports -

To show details of a specific report, use the function - rb:show(Number):

+

Use function + rb:show(Number) + to show details of a specific report:

-
-10> rb:show(1).
 7> rb:show(4).
         
 PROGRESS REPORT  <0.20.0>                                   1996-10-16 16:16:36
@@ -259,7 +262,7 @@ started
 {child_type,worker}]
         
 ok
-8> rb:show(9).
+8> rb:show(9).
         
 CRASH REPORT  <0.24.0>                                      1996-10-16 16:16:21
 ===============================================================================
@@ -287,19 +290,17 @@ heap_size                                                                610
 stack_size                                                               142
 reductions                                                                54
 
-ok
-
+ok
- Search the Reports -

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 release_handler:mbj_func. We could - then show reports as follows:

+ Search Reports +

All reports containing a common pattern can be shown. + Suppose a process crashes because it tries to call a + non-existing function release_handler:mbj_func/1. + The reports can then be shown as follows:

-
-12>rb:grep("mbj_func").          
+12> rb:grep("mbj_func").
 Found match in report number 11
         
 ERROR REPORT  <0.24.0>                                      1996-10-16 16:16:21
@@ -368,19 +369,17 @@ restart_type                                                       permanent
 shutdown                                                                2000
 child_type                                                            worker
         
-ok
-
+ok
- Stop the Server -

Stop the rb_server with the function - rb:stop():

+ Stop Server +

Use function + rb:stop() + to stop the rb_server:

-
-13>rb:stop().
-ok
-
+13> rb:stop(). +ok
diff --git a/lib/sasl/doc/src/overload.xml b/lib/sasl/doc/src/overload.xml index 35877220ab..5c3d00afeb 100644 --- a/lib/sasl/doc/src/overload.xml +++ b/lib/sasl/doc/src/overload.xml @@ -35,98 +35,88 @@ overload An Overload Regulation Process -

overload is a process which indirectly regulates CPU +

overload is a process that indirectly regulates the CPU usage in the system. The idea is that a main application calls - the request/0 function before starting a major job, and + function + request/0 + before starting a major job and proceeds with the job if the return value is positive; otherwise - the job must not be started. -

-

overload is part of the sasl application, and all - configuration parameters are defined there. -

-

A set of two intensities are maintained, the total intensity and the accept intensity. For that purpose - there are two configuration parameters, the MaxIntensity - and the Weight value (both are measured in 1/second). -

+ the job must not be started.

+

overload is part of the SASL application and all + configuration parameters are defined there.

+

A set of two intensities are maintained, the total intensity + and the accept intensity. For that purpose, + there are two configuration parameters, MaxIntensity + and Weight; both are measured in 1/second.

Then total and accept intensities are calculated as follows. Assume that the time of the current call to - request/0 is T(n), and that the time of the - previous call was T(n-1). -

+ request/0 is T(n) and that the time of the + previous call was T(n-1).

The current total intensity, denoted - TI(n), is calculated according to the formula, -

-

TI(n) = exp(-Weight*(T(n) - T(n-1)) * TI(n-1) + Weight, -

-

where TI(n-1) is the previous total intensity. -

+ TI(n), is calculated according to the formula

+

TI(n) = exp(-Weight*(T(n) - T(n-1)) * TI(n-1) + Weight,

+

where TI(n-1) is the previous total intensity.

The current accept intensity, denoted - AI(n), is determined by the formula, -

-

AI(n) = exp(-Weight*(T(n) - T(n-1)) * AI(n-1) + Weight, -

-

where AI(n-1) is the previous accept intensity, - provided that the value of exp(-Weight*(T(n) - T(n-1)) * AI(n-1) is less than MaxIntensity; otherwise the - value is -

-

AI(n) = exp(-Weight*(T(n) - T(n-1)) * AI(n-1). -

+ AI(n), is determined by the formula

+

AI(n) = exp(-Weight*(T(n) - T(n-1)) * AI(n-1) + Weight,

+

where AI(n-1) is the previous accept intensity, + if the value of exp(-Weight*(T(n) - T(n-1)) * AI(n-1) + is less than MaxIntensity. Otherwise the value is

+

AI(n) = exp(-Weight*(T(n) - T(n-1)) * AI(n-1)

The value of configuration parameter Weight controls the - speed with which the calculations of intensities will react to + speed with which the calculations of intensities react to changes in the underlying input intensity. The inverted value of - Weight, -

-

T = 1/Weight

-

can be thought of as the "time constant" - of the intensity calculation formulas. For example, if Weight = 0.1, then a change in the underlying input intensity will be - reflected in the total and accept intensities within - approximately 10 seconds. -

+ Weight, T = 1/Weight, can be thought of as the + "time constant" of the intensity calculation formulas. For example, + if Weight = 0.1, a change in the underlying input intensity is + reflected in total intensity and accept intensity within + about 10 seconds.

The overload process defines one alarm, which it sets using - alarm_handler:set_alarm(Alarm). Alarm is defined - as: -

+ alarm_handler:set_alarm(Alarm). Alarm is defined + as follows:

{overload, []} -

This alarm is set when the current accept intensity exceeds - MaxIntensity. -

+

This alarm is set when the current accept intensity exceeds + MaxIntensity.

 -

A new overload alarm is not set until the current accept - intensity has fallen below MaxIntensity. 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 MaxIntensity, and it is not until then that - the alarm can be set again. -

+

A new request is not accepted until the current accept + intensity has fallen below MaxIntensity. To prevent the + overload process from generating many set/reset alarms, the + alarm is not reset until the current accept intensity has fallen + below 75% of MaxIntensity; it is not until then that + the alarm can be set again.

 + request() -> accept | reject - Request to proceed with current job + Requests to proceed with current job.

Returns accept or reject depending on the - current value of the accept intensity.

+ current value of the accept intensity.

The application - calling this function should be processed with the job in + calling this function is to proceed with the job in question if the return value is accept; otherwise it - should not continue with that job. -

+ is not to continue with that job.

 + get_overload_info() -> OverloadInfo - Return current overload information data + Returns current overload information data. - OverloadInfo = [{total_intensity, TotalIntensity}, {accept_intensity, AcceptIntensity}, {max_intensity, MaxIntensity}, {weight, Weight}, {total_requests, TotalRequests}, {accepted_requests, AcceptedRequests}]. + OverloadInfo = [{total_intensity, TotalIntensity}, + {accept_intensity, AcceptIntensity}, {max_intensity, + MaxIntensity}, {weight, Weight}, {total_requests, + TotalRequests}, {accepted_requests, AcceptedRequests}]. TotalIntensity = float() > 0 AcceptIntensity = float() > 0 MaxIntensity = float() > 0 @@ -135,18 +125,22 @@ AcceptedRequests = integer() -

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).

+

Returns:

+ + Current total and accept intensities + Configuration parameters + Absolute counts of the total number of requests + Accepted number of requests (since the overload + process was started) +
See Also -

alarm_handler(3), sasl(3) -

+

alarm_handler(3), + sasl(6)

diff --git a/lib/sasl/doc/src/part.xml b/lib/sasl/doc/src/part.xml index bcd345a7c4..2f47a8ad80 100644 --- a/lib/sasl/doc/src/part.xml +++ b/lib/sasl/doc/src/part.xml @@ -30,8 +30,9 @@ part.xml -

The System Architecture Support Libraries, SASL, - provides support for alarm and release handling etc.

+

The System Architecture Support Libraries SASL application + provides support for alarm handling, release handling, and + related functions.

 diff --git a/lib/sasl/doc/src/rb.xml b/lib/sasl/doc/src/rb.xml index 85252fc088..e16e9f5a62 100644 --- a/lib/sasl/doc/src/rb.xml +++ b/lib/sasl/doc/src/rb.xml @@ -35,241 +35,252 @@ rb The Report Browser Tool -

The Report Browser (RB) tool makes it possible to browse and +

The Report Browser (RB) tool is used to browse and format error reports written by the error logger handler - log_mf_h. -

+ log_mf_h + in STDLIB.

 + filter(Filters) filter(Filters, Dates) - Filter reports and displays them on the screen + Filters reports and displays them on the screen. Filters = [filter()] - filter() = {Key, Value} | {Key, Value, no} | {Key, RegExp, re} | {Key, RegExp, re, no} + filter() = {Key, Value} | {Key, Value, no} | {Key, RegExp, re} | + {Key, RegExp, re, no} Key = term() Value = term() - RegExp = string() | {string, Options} | mp(), {mp(), Options} + RegExp = string() | {string(), Options} | re:mp() | {re:mp(), Options} Dates = {DateFrom, DateTo} | {DateFrom, from} | {DateTo, to} - DateFrom = DateTo = {date(), time()} - date() and time() are the same type as in the calendar module + DateFrom = DateTo = calendar:datetime() -

This function displays the reports that match the provided filters.

-

- When a filter includes the no atom it will exclude the reports that match - that filter. -

-

- The reports are matched using the proplists module. The report must be a proplist - to be matched against any of the filters(). -

-

- If the filter is of the form {Key, RegExp, re} the report must contain an element with - key = Key and Value must match the RegExp regular expression. -

-

- If the Dates parameter is provided, then the reports are filtered according to the date - when they occurred. If Dates is of the form {DateFrom, from} then reports that occurred - after DateFrom are displayed. -

-

- If Dates is of the form {DateTo, to} then reports that occurred before DateTo - are displayed. -

-

- If two Dates are provided, then reports that occurred between those dates are returned. -

-

- If you only want to filter only by dates, then you can provide the empty list as the Filters - parameter. -

-

- See rb:grep/1 for more information on the RegExp parameter. -

+

Displays the reports that match the provided filters.

+

When a filter includes the no atom, it excludes the + reports that match that filter.

+

The reports are matched using the + proplists + module in STDLIB. The report must be a proplist + to be matched against any of the filters.

+

If the filter has the form {Key, RegExp, re}, the + report must contain an element with key equal to Key and + the value must match the regular expression RegExp.

+

If parameter Dates is specified, the reports are filtered + according to the date when they occurred. If Dates has + the form {DateFrom, from}, reports that occurred after + DateFrom are displayed.

+

If Dates has the form {DateTo, to}, reports that + occurred before DateTo are displayed.

+

If two Dates are specified, reports that occurred between + those dates are returned.

+

To filter only by dates, specify the empty list as the Filters + parameter.

+

For details about parameter RegExp, see rb:grep/1.

+

For details about data type mp(), see + re:mp().

+

For details about data type datetime(), see + calendar:datetime().

 + grep(RegExp) - Search the reports for a regular expression + Searches the reports for a regular expression. - RegExp = string() | {string, Options} | mp(), {mp(), Options} + RegExp = string() | {string(), Options} | re:mp() | {re:mp(), Options} -

All reports containing the regular expression RegExp - are printed. -

-

RegExp 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 re and specially the function re:run/3 - for a definition of valid regular expressions and options. -

+

All reports matching the regular expression RegExp + are displayed. RegExp can be any of the following:

+ + 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 + +

For a definition of valid regular expressions and options, see + the re module in + STDLIB and in particular function re:run/3.

+

For details about data type mp(), see + re:mp().

 + h() help() - Print help information + Displays help information. -

Prints the on-line help information. -

+

Displays online help information.

 + list() list(Type) - List all reports + Lists all reports. Type = type() type() = error | error_report | info_msg | info_report | - warning_msg | warning_report | crash_report | - supervisor_report | progress + warning_msg | warning_report | crash_report | + supervisor_report | progress -

This function lists all reports loaded in the +

Lists all reports loaded in rb_server. Each report is given a unique number that - can be used as a reference to the report in the - show/1 function. -

-

If no Type is given, all reports are listed. -

+ can be used as a reference to the report in function + show/1.

+

If no Type is specified, all reports are listed.

 + log_list() log_list(Type) - Log reports list + Logs report lists. Type = type() type() = error | error_report | info_msg | info_report | - warning_msg | warning_report | crash_report | - supervisor_report | progress + warning_msg | warning_report | crash_report | + supervisor_report | progress -

Same as list/0 or list/1 functions - but result is printed to logfile, if set, otherwise to standard_io. -

-

If no Type is given, all reports are listed. -

+

Same as functions + list/0 or + list/1, + but the result is printed to a log file, if set; otherwise + to standard_io.

+

If no Type is specified, all reports are listed.

 + rescan() rescan(Options) - Rescan the report directory + Rescans the report directory. Options = [opt()]

Rescans the report directory. Options is the same as - for start(). -

+ for function + start/1.

 + show() show(Report) - Show reports + Displays reports. - Report = int() | type() + Report = integer() | type() -

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. -

+

If argument type 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.

 + start() start(Options) - Start the RB server + Starts the rb_server. Options = [opt()] - opt() = {start_log, FileName} | {max, MaxNoOfReports} | {report_dir, DirString} | {type, ReportType} | {abort_on_error, Bool} + opt() = {start_log, FileName} | {max, MaxNoOfReports} | + {report_dir, DirString} | {type, ReportType} | + {abort_on_error, Bool} FileName = string() | atom() | pid() - MaxNoOfReports = int() | all + MaxNoOfReports = integer() | all DirString = string() ReportType = type() | [type()] | all - Bool = true | false + Bool = boolean() -

The function start/1 starts the rb_server - with the specified options, while start/0 starts with - default options. The rb_server must be started before - reports can be browsed. When the rb_server is +

Function start/1 starts rb_server with the + specified options, whereas function start/0 starts with + default options. rb_server must be started before + reports can be browsed. When rb_server is started, the files in the specified directory are scanned. The other functions assume that the server has - started. -

-

{start_log, FileName} starts logging to file, - registered name or io_device. All reports will be printed - to the named file. The default is standard_io. - The option {start_log, standard_error} is not allowed and - will be replaced by default standard_io. -

-

{max, MaxNoOfReports}. Controls how many reports the - rb_server should read on start-up. This option is - useful as the directory may contain 20.000 reports. If this - option is given, the MaxNoOfReports latest reports - will be read. The default is 'all'. -

-

{report_dir, DirString}. Defines the directory where - the error log files are located. The default is {sasl, error_logger_mf_dir}.

-

{type, ReportType}. Controls what kind of reports the - rb_server should read on start-up. ReportType - is a supported type, 'all', or a list of supported - types. The default is 'all'. -

-

{abort_on_error, Bool}. 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 - error_logger function error_msg or - info_msg has been called with an invalid format string). - If Bool is true, 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 Bool is false (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 - * UNPRINTABLE REPORT * in the log file at the location of an - unprintable report. -

+ started.

+

Options:

+ + {start_log, FileName} +

Starts logging to file, + registered name, or io_device. All reports are printed + to the specified destination. Default is standard_io. + Option {start_log, standard_error} is not allowed and + will be replaced by default standard_io.

 + {max, MaxNoOfReports} +

Controls how many reports + rb_server 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 MaxNoOfReports latest reports + are read. Default is all.

 + {report_dir, DirString} +

Defines the directory where + the error log files are located. Default is + the directory specified by application environment + variable error_logger_mf_dir, + see sasl(6).

 + {type, ReportType} +

Controls what kind of reports + rb_server is to read at startup. ReportType + is a supported type, all, or a list of supported + types. Default is all.

 + {abort_on_error, Bool} +

Specifies if + logging is to be ended if rb encounters an unprintable + report. (You can get a report with an incorrect form if function + error_logger, error_msg, or + info_msg has been called with an invalid format string)

+ + If Bool is true, rb stops logging + (and prints an error message to stdout) if it encounters + a badly formatted report. If logging to file is enabled, an + error message is appended to the log file as well. + If Bool is false (the default value), rb + prints an error message to stdout for every bad report it + encounters, but the logging process is never ended. All printable + reports are written. If logging to file is enabled, rb prints + * UNPRINTABLE REPORT * in the log file at the location of an + unprintable report. + + + start_log(FileName) - Redirect all output to FileName + Redirects all output to FileName. FileName = string() | atom() | pid()

Redirects all report output from the RB tool to the - specified file, registered name or io_device. -

+ specified file, registered name, or io_device.

 + stop() - Stop the RB server + Stops the rb_server. -

Stops the rb_server. -

+

Stops rb_server.

 + stop_log() - Stop logging to file + Stops logging to file. -

Closes the log file. The output from the RB tool will be - directed to standard_io. -

+

Closes the log file. The output from the RB tool is + directed to standard_io.

 diff --git a/lib/sasl/doc/src/ref_man.xml b/lib/sasl/doc/src/ref_man.xml index 2b608c7c51..a80e5a2a00 100644 --- a/lib/sasl/doc/src/ref_man.xml +++ b/lib/sasl/doc/src/ref_man.xml @@ -30,8 +30,8 @@ application.xml -

The System Architecture Support Libraries application, SASL, - provides support for alarm and release handling etc.

+

The SASL application provides support for alarm handling, + release handling, and related functions.

 diff --git a/lib/sasl/doc/src/rel.xml b/lib/sasl/doc/src/rel.xml index a16db24295..d5f3c7310a 100644 --- a/lib/sasl/doc/src/rel.xml +++ b/lib/sasl/doc/src/rel.xml @@ -33,74 +33,65 @@ rel Release resource file -

The release resource file specifies which applications are +

The release resource file specifies which applications are included in a release (system) based on Erlang/OTP.

-

This file is used by the functions in systools when generating - start scripts (.script, .boot) and release upgrade - files (relup).

+

This file is used by the functions in + systools + when generating start scripts (.script, .boot) and + release upgrade files (relup).
- FILE SYNTAX -

The release resource file should be called Name.rel.

+ File Syntax +

The release resource file is to be called Name.rel.

The .rel file contains one single Erlang term, which is - called a release specification. The file has the + called a release specification. The file has the following syntax:

{release, {RelName,Vsn}, {erts, EVsn}, [{Application, AppVsn} | {Application, AppVsn, Type} | {Application, AppVsn, IncApps} | - {Application, AppVsn, Type, IncApps}]}. - - - -

RelName = string() is the name of the release.

- - -

Vsn = string() is the version of the release.

- - -

EVsn = string() is the version of ERTS the release is - intended for.

- - -

Application = atom() is the name of an application - included in the release.

- - -

AppVsn = string() is the version of an application - included in the release.

- - -

Type = permanent | transient | temporary | load | none - is the start type of an application included in the release.

-

If Type = permanent | transient | temporary, - the application will be loaded and started in the corresponding - way, see application(3). If Type = load, - the application will only be loaded. If Type = none, - the application will be neither loaded nor started, although - the code for its modules will be loaded. - Defaults to permanent

- - -

IncApps = [atom()] is a list of applications that are - included by an application included in the release.

-

The list must be a subset of the included applications + {Application, AppVsn, Type, IncApps}]}. + + RelName = string() +

Release name.

 + Vsn = string() +

Release version.

 + EVsn = string() +

ERTS version the release is intended for.

 + Application = atom() +

Name of an application included in the release.

 + AppVsn = string() +

Version of an application included in the release.

 + Type = permanent | transient | temporary | load | none +

Start type of an application included in the release.

+

If Type = permanent | transient | temporary, the + application is loaded and started in the corresponding way, see + application(3).

+

If Type = load, the application is only loaded.

+

If Type = none, the application is not loaded and not + started, although the code for its modules is loaded.

+

Defaults to permanent

 + IncApps = [atom()] +

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 (Application.app) and overrides this value. Defaults - to the same value as in the application resource file.

- - + to the same value as in the application resource file.

+ -

The list of applications must contain the kernel and - stdlib applications.

+

The list of applications must contain the Kernel and + STDLIB applications.
- SEE ALSO -

application(3), relup(4), systools(3)

+ See Also +

application(3), + relup(4), + systools(3)

diff --git a/lib/sasl/doc/src/release_handler.xml b/lib/sasl/doc/src/release_handler.xml index 692159d7bf..162707676c 100644 --- a/lib/sasl/doc/src/release_handler.xml +++ b/lib/sasl/doc/src/release_handler.xml @@ -31,109 +31,115 @@ release_handler Unpacking and Installation of Release Packages -

The release handler is a process belonging to the SASL - application which is responsible for release handling, +

The release handler process belongs to the SASL + application, which is responsible for release handling, that is, unpacking, installation, and removal of release packages.

-

An introduction to release handling and a usage example can be - found in - Design Principles. -

+

An introduction to release handling and an example is provided in + OTP Design + Principles in System Documentation.

A release package is a compressed tar file containing code for a certain version of a release, created by calling - systools:make_tar/1,2. - The release package should be placed in the $ROOT/releases - directory of the previous version of the release where + systools:make_tar/1,2. + The release package is to be located in the $ROOT/releases + directory of the previous version of the release, where $ROOT is the installation root directory, - code:root_dir(). - Another releases directory can be specified using the SASL - configuration parameter releases_dir, or the OS environment + code:root_dir(). + Another releases directory can be specified using the SASL + configuration parameter releases_dir or the OS environment variable RELDIR. 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 RELEASES.

-

A release package should always contain the release resource file - Name.rel and a boot script Name.boot. It may contain - a release upgrade file relup and a system configuration - file sys.config. The .rel file contains information - about the release: its name, version, and which ERTS and - application versions it uses. The relup file contains - scripts for how to upgrade to, or downgrade from, this version of - the release.

+

A release package is always to contain:

+ + A release resource file, Name.rel + A boot script, Name.boot + +

The .rel file contains information about the release: its name, + version, and which ERTS and application versions it uses.

+

A release package can also contain:

+ + A release upgrade file, relup + A system configuration file, sys.config + +

The relup file contains instructions for how to upgrade + to, or downgrade from, this version of the release.

The release package can be unpacked, which extracts the files. An unpacked release can be installed. The currently used version of the release is then upgraded or downgraded to the specified version by evaluating the instructions - in relup. An installed release can be made - permanent. There can only be one permanent release in - the system, and this is the release that is used if the system + in the relup file. An installed release can be made + permanent. 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 removed. When a release is removed, all files - that belong to that release only are deleted.

-

Each version of the release has a status. The status can be + belonging to that release only are deleted.

+

Each release version has a status, which can be unpacked, current, permanent, or old. - There is always one latest release which either has status - permanent (normal case), or current (installed, but - not yet made permanent). The following table illustrates - the meaning of the status values:

+ There is always one latest release, which either has status + permanent (normal case) or current (installed, but + not yet made permanent). The meaning of the status values are + illustrated in the following table:

-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                  -
-
+ 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 -

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.

-

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 +

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 Embedded System. In this case, the system configuration file - sys.config is mandatory.

-

The installation of a new release may restart the system. Which - program to use is specified by the SASL configuration - parameter start_prg which defaults + started as an embedded system. Read about this in + Embedded System in + System Documentation. In this case, the system + configuration file sys.config is mandatory.

+

The installation of a new release can restart the system. Which + program to use is specified by the SASL configuration + parameter start_prg, which defaults to $ROOT/bin/start.

The emulator restart on Windows NT expects that the system is started using the erlsrv program (as a service). - Furthermore the release handler expects that the service is named - NodeName_Release, where NodeName is - the first part of the Erlang nodename (up to, but not including - the "@") and Release is the current version of - the release. The release handler furthermore expects that a + Furthermore, the release handler expects that the service is named + NodeName_Release, where NodeName is + the first part of the Erlang node name (up to, but not including + the "@") and Release is the current release version. + The release handler furthermore expects that a program like start_erl.exe is specified as "machine" to - erlsrv. 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 + erlsrv. 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.

-

The release handler at a node which runs on a diskless machine, +

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 sasl configuration parameters (see - sasl(6) for details):

+ using the following SASL configuration parameters (for + details, see sasl(6)):

masters -

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 +

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.

 client_directory @@ -145,24 +151,25 @@ old reboot_old permanent

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.

 -

It is also possible to use the release handler to unpack and +

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.

-

There are additional functions for using another file structure + the system must be restarted.

+

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.

 + check_install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason} check_install_release(Vsn,Opts) -> {ok, OtherVsn, Descr} | {error, Reason} - Check installation of a release in the system. + Checks installation of a release in the system. Vsn = OtherVsn = string() Opts = [Opt] @@ -173,27 +180,29 @@ old reboot_old permanent

Checks if the specified version Vsn of the release can be installed. The release must not have status - current. Issues warnings if relup or - sys.config are not present. If relup is present, + current. Issues warnings if relup file or + sys.config is not present. If relup file is present, its contents are checked and {error,Reason} is returned if an error is found. Also checks that all required - applications are present and that all new code can be loaded, - or {error,Reason} is returned.

-

This function evaluates all instructions that occur before + applications are present and that all new code can be loaded; + {error,Reason} is returned if an error is found.

+

Evaluates all instructions that occur before the point_of_no_return instruction in the release upgrade script.

-

Returns the same as install_release/1. Descr - defaults to "" if no relup file is found.

-

If the option purge 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 +

Returns the same as + install_release/1. + Descr defaults to "" if no relup file is found.

+

If option purge 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 install_release.

+ marker="#install_release/1">install_release/1.

 + create_RELEASES(Root, RelDir, RelFile, AppDirs) -> ok | {error, Reason} - Create an initial RELEASES file. + Creates an initial RELEASES file. Root = RelDir = RelFile = string() AppDirs = [{App, Vsn, Dir}] @@ -202,52 +211,55 @@ old reboot_old permanent Reason = term() -

Creates an initial RELEASES file to be used by the release - handler. This file must exist in order to install new +

Creates an initial RELEASES file to be used by the + release handler. This file must exist to install new releases.

Root is the root of the installation ($ROOT) as - described above. RelDir is the the directory where - the RELEASES file should be created (normally + described earlier. RelDir is the directory where + the RELEASES file is to be created (normally $ROOT/releases). RelFile is the name of the .rel file that describes the initial release, including the extension .rel.

AppDirs can be used to specify from where the modules - for the specified applications should be loaded. App is + for the specified applications are to be loaded. App is the name of an application, Vsn is the version, and Dir is the name of the directory where App-Vsn - is located. The corresponding modules should be located under + is located. The corresponding modules are to be located under Dir/App-Vsn/ebin. The directories for applications not specified in AppDirs are assumed to be located in $ROOT/lib.

 + install_file(Vsn, File) -> ok | {error, Reason} - Install a release file in the release structure. + Installs a release file in the release structure. Vsn = File = string() Reason = term() -

Installs a release dependent file in the release structure. - A release dependent file is a file that must be in +

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: - start.boot, relup and sys.config.

+ start.boot, relup, and sys.config.

The function can be called, for example, when these files - are generated at the target. It should be called after - set_unpacked/2 has been called.

+ are generated at the target. The function is to be called after + set_unpacked/2 + has been called.

 + install_release(Vsn) -> {ok, OtherVsn, Descr} | {error, Reason} install_release(Vsn, [Opt]) -> {ok, OtherVsn, Descr} | {continue_after_restart, OtherVsn, Descr} | {error, Reason} - Install a release in the system. + Installs a release in the system. Vsn = OtherVsn = string() Opt = {error_action, Action} | {code_change_timeout, Timeout}    | {suspend_timeout, Timeout} | {update_paths, Bool}  Action = restart | reboot -  Timeout = default | infinity | int()>0 +  Timeout = default | infinity | pos_integer()  Bool = boolean() Descr = term() Reason = {illegal_option, Opt} | {already_installed, Vsn} | {change_appl_data, term()} | {missing_base_app, OtherVsn, App} | {could_not_create_hybrid_boot, term()} | term() @@ -262,7 +274,7 @@ old reboot_old permanent version and a script {Vsn,Descr2,Instructions2} in this file for downgrading to Vsn.

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 .app files and sys.config belonging to the release version Vsn.

After the application specifications have been updated, @@ -271,101 +283,120 @@ old reboot_old permanent OtherVsn and Descr are the version (UpFromVsn or Vsn) and description (Descr1 or Descr2) as specified in the script.

-

If {continue_after_restart,OtherVsn,Descr} 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 +

If {continue_after_restart,OtherVsn,Descr} 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.

If a recoverable error occurs, the function returns {error,Reason} and the original application specifications are restored. If a non-recoverable error occurs, the system is restarted.

-

The option error_action defines if the node should be - restarted (init:restart()) or rebooted - (init:reboot()) in case of an error during - the installation. Default is restart.

-

The option code_change_timeout defines the timeout - for all calls to sys:change_code. If no value is - specified or default is given, the default value - defined in sys is used.

-

The option suspend_timeout defines the timeout for - all calls to sys:suspend. If no value is specified, - the values defined by the Timeout parameter of - the upgrade or suspend instructions are used. - If default is specified, the default value defined in - sys is used.

-

The option {update_paths,Bool} indicates if all - application code paths should be updated (Bool==true), - or if only code paths for modified applications should be - updated (Bool==false, default). This option only has - effect for other application directories than the default - $ROOT/lib/App-Vsn, that is, application directories - provided in the AppDirs argument in a call to - create_RELEASES/4 or set_unpacked/2.

-

Example: In the current version CurVsn of a release, - the application directory of myapp is - $ROOT/lib/myapp-1.0. A new version NewVsn is - unpacked outside the release handler, and the release handler - is informed about this with a call to:

- +

Options:

+ + error_action +

Defines if the node is to be + restarted + (init:restart()) + or rebooted + (init:reboot()) + if there is an error during + the installation. Default is restart.

 + code_change_timeout +

Defines the time-out + for all calls to + stdlib:sys:change_code. + If no value is specified or default is specified, the + default value defined in sys is used.

 + suspend_timeout +

Defines the time-out for + all calls to + stdlib:sys:suspend. + If no value is specified, the values defined by the Timeout + parameter of the upgrade or suspend instructions are used. + If default is specified, the default value defined in + sys is used.

 + {update_paths,Bool} +

Indicates if all + application code paths are to be updated (Bool==true) + or if only code paths for modified applications are to be + updated (Bool==false, default). This option has only + effect for other application directories than the default + $ROOT/lib/App-Vsn, that is, application directories + specified in argument AppDirs in a call to + create_RELEASES/4 or + set_unpacked/2.

+

Example:

+

In the current version CurVsn of a release, the + application directory of myapp is + $ROOT/lib/myapp-1.0. A new version NewVsn is + unpacked outside the release handler and the release + handler is informed about this with a call as follows:

+ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). -=> {ok,NewVsn} - -

If NewVsn is installed with the option - {update_paths,true}, afterwards - code:lib_dir(myapp) will return - /home/user/myapp-1.0.

+=> {ok,NewVsn} +

If NewVsn is installed with option + {update_paths,true}, then + kernel:code:lib_dir(myapp) + returns /home/user/myapp-1.0.

+ -

Installing a new release might be quite time consuming if +

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.

-

If you wish to speed up the execution of - install_release, then you may call check_install_release - first, using the option purge. 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 install_release will not need to do the +

To speed up the execution of + install_release, + first call check_install_release, + using option purge. 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 + install_release + does not need to do the checks.

-

Obviously, this will not reduce the overall time for the - upgrade, but it will allow checks and purge to be executed +

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.

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 Design - Principles for more information about emulator - upgrade from pre OTP R15 versions.

+ 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 + Design + Principles in System Documentation.

 + make_permanent(Vsn) -> ok | {error, Reason} - Make the specified release version permanent. + Makes the specified release version permanent. Vsn = string() Reason = {bad_status, Status} | term() -

Makes the specified version Vsn of the release +

Makes the specified release version Vsn permanent.

 + remove_release(Vsn) -> ok | {error, Reason} - Remove a release from the system. + Removes a release from the system. Vsn = string() Reason = {permanent, Vsn} | client_node | term() @@ -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.

+ reboot_old_release(Vsn) -> ok | {error, Reason} - Reboot the system from an old release. + Reboots the system from an old release. Vsn = string() Reason = {bad_status, Status} | term()

Reboots the system by making the old release permanent, and - calls init:reboot() directly. The release must have - status old.

+ calls + init:reboot() + directly. The release must have status old.

 + set_removed(Vsn) -> ok | {error, Reason} - Mark a release as removed. + Marks a release as removed. Vsn = string() Reason = {permanent, Vsn} | term() @@ -403,9 +437,10 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). not delete any files.

 + set_unpacked(RelFile, AppDirs) -> {ok, Vsn} | {error, Reason} - Mark a release as unpacked. + Marks a release as unpacked. RelFile = string() AppDirs = [{App, Vsn, Dir}] @@ -419,18 +454,19 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). the release is unpacked. Vsn is extracted from the release resource file RelFile.

AppDirs can be used to specify from where the modules - for the specified applications should be loaded. App is + for the specified applications are to be loaded. App is the name of an application, Vsn is the version, and Dir is the name of the directory where App-Vsn - is located. The corresponding modules should be located under + is located. The corresponding modules are to be located under Dir/App-Vsn/ebin. The directories for applications not specified in AppDirs are assumed to be located in $ROOT/lib.

 + unpack_release(Name) -> {ok, Vsn} | {error, Reason} - Unpack a release package. + Unpacks a release package. Name = Vsn = string() Reason = client_node | term() @@ -438,14 +474,15 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).

Unpacks a release package Name.tar.gz located in the releases directory.

-

Performs some checks on the package - for example checks - that all mandatory files are present - and extracts its +

Performs some checks on the package, for example, checks + that all mandatory files are present, and extracts its contents.

 + which_releases() -> [{Name, Vsn, Apps, Status}] - Return all known releases + Returns all known releases. Name = Vsn = string() Apps = ["App-Vsn"] @@ -455,16 +492,18 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).

Returns all releases known to the release handler.

 + which_releases(Status) -> [{Name, Vsn, Apps, Status}] - Return all known releases of a specific status + Returns all known releases of a specific status. Name = Vsn = string() Apps = ["App-Vsn"] Status = unpacked | current | permanent | old -

Returns all releases known to the release handler of a specific status.

+

Returns all releases, known to the release handler, of a + specific status.

 @@ -473,7 +512,8 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). Application Upgrade/Downgrade

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 relup is created + release). A script corresponding to the instructions in the + relup file is created on-the-fly, based on the .appup file for the application, and evaluated exactly in the same way as release_handler does.

@@ -482,20 +522,22 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]). of .appup files. They are not run within the context of the release_handler process. They must therefore not be used together with calls to - install_release/1,2, as this will cause + install_release/1,2, + as this causes the release_handler to end up in an inconsistent state.

-

No persistent information is updated, why these functions can +

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.

-

If the upgrade or downgrade fails, the application may end up +

If the upgrade or downgrade fails, the application can end up in an inconsistent state.

+ upgrade_app(App, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason} - Upgrade to a new application version + Upgrades to a new application version. App = atom() Dir = string() @@ -506,39 +548,46 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).

Upgrades an application App from the current version to a new version located in Dir according to - the .appup script.

+ the .appup file.

App is the name of the application, which must be started. Dir is the new library directory of - App, the corresponding modules as well as - the .app and .appup files should be located + App. The corresponding modules as well as + the .app and .appup files are to be located under Dir/ebin.

The function looks in the .appup file and tries to find an upgrade script from the current version of the application using - upgrade_script/2. + upgrade_script/2. This script is evaluated using - eval_appup_script/4, + eval_appup_script/4, exactly in the same way as - install_release/1,2 + install_release/1,2 does.

-

Returns {ok, Unpurged} if evaluating the script is - successful, where Unpurged is a list of unpurged - modules, or restart_emulator if this instruction is - encountered in the script, or {error, Reason} if - an error occurred when finding or evaluating the script.

+

Returns one of the following:

+ + {ok, Unpurged} if evaluating the script is + successful, where Unpurged is a list of unpurged + modules + restart_emulator if this instruction is + encountered in the script + {error, Reason} if an error occurred when + finding or evaluating the script +

If the restart_new_emulator instruction is found in - the script, upgrade_app/2 will return - {error,restart_new_emulator}. 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 - install_release/1,2.

+ the script, + upgrade_app/2 + returns {error,restart_new_emulator}. This because + restart_new_emulator 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 + install_release/1,2.

 + downgrade_app(App, Dir) -> downgrade_app(App, OldVsn, Dir) -> {ok, Unpurged} | restart_emulator | {error, Reason} - Downgrade to a previous application version + Downgrades to a previous application version. App = atom() Dir = OldVsn = string() @@ -549,110 +598,124 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).

Downgrades an application App from the current version to a previous version OldVsn located in - Dir according to the .appup script.

+ Dir according to the .appup file.

App is the name of the application, which must be - started. OldVsn is the previous version of - the application and can be omitted if Dir is of + started. OldVsn is the previous application version + and can be omitted if Dir is of the format "App-OldVsn". Dir is the library - directory of this previous version of App, - the corresponding modules as well as the old .app file - should be located under Dir/ebin. The .appup - file should be located in the ebin directory of + directory of the previous version of App. + The corresponding modules and the old .app file + are to be located under Dir/ebin. The .appup + file is to be located in the ebin directory of the current library directory of the application - (code:lib_dir(App)).

+ (code:lib_dir(App)).

The function looks in the .appup 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 - downgrade_script/3. + downgrade_script/3. This script is evaluated using - eval_appup_script/4, + eval_appup_script/4, exactly in the same way as - install_release/1,2 + install_release/1,2 does.

-

Returns {ok, Unpurged} if evaluating the script is - successful, where Unpurged is a list of unpurged - modules, or restart_emulator if this instruction is - encountered in the script, or {error, Reason} if - an error occurred when finding or evaluating the script.

+

Returns one of the following:

+ + {ok, Unpurged} if evaluating the script is + successful, where Unpurged is a list of unpurged + modules + restart_emulator if this instruction is + encountered in the script + {error, Reason} if an error occurred when + finding or evaluating the script + + upgrade_script(App, Dir) -> {ok, NewVsn, Script} - Find an application upgrade script + Finds an application upgrade script. App = atom() Dir = string() NewVsn = string() - Script = Instructions -- see appup(4) + Script = Instructions

Tries to find an application upgrade script for App from the current version to a new version located in Dir.

The upgrade script can then be evaluated using - eval_appup_script/4. + eval_appup_script/4. It is recommended to use - upgrade_app/2 - instead, but this function is useful in order to inspect - the contents of the script.

+ upgrade_app/2 + instead, but this function (upgrade_script) is useful + to inspect the contents of the script.

App is the name of the application, which must be started. Dir is the new library directory of - App, the corresponding modules as well as - the .app and .appup files should be located + App. The corresponding modules as well as + the .app and .appup files are to be located under Dir/ebin.

The function looks in the .appup 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 relup script.

+ 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 relup file.

Returns {ok, NewVsn, Script} if successful, where - NewVsn is the new application version.

+ NewVsn is the new application version. + For details about Script, see + appup(4).

Failure: If a script cannot be found, the function fails with an appropriate error reason.

 + downgrade_script(App, OldVsn, Dir) -> {ok, Script} - Find an application downgrade script + Finds an application downgrade script. App = atom() OldVsn = Dir = string() - Script = Instructions -- see appup(4) + Script = Instructions

Tries to find an application downgrade script for App from the current version to a previous version OldVsn located in Dir.

The downgrade script can then be evaluated using - eval_appup_script/4. + eval_appup_script/4. It is recommended to use - downgrade_app/2,3 - instead, but this function is useful in order to inspect - the contents of the script.

+ downgrade_app/2,3 + instead, but this function (downgrade_script) is useful + to inspect the contents of the script.

App is the name of the application, which must be started. Dir is the previous library directory of - App, the corresponding modules as well as - the old .app file should be located under - Dir/ebin. The .appup file should be located in + App. The corresponding modules and + the old .app file are to be located under + Dir/ebin. The .appup file is to be located in the ebin directory of the current library - directory of the application (code:lib_dir(App)).

+ directory of the application + (code:lib_dir(App)).

The function looks in the .appup 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 relup script.

-

Returns {ok, Script} if successful.

+ 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 relup file.

+

Returns {ok, Script} if successful. + For details about Script, see + appup(4).

Failure: If a script cannot be found, the function fails with an appropriate error reason.

 + eval_appup_script(App, ToVsn, ToDir, Script) -> {ok, Unpurged} | restart_emulator | {error, Reason} - Evaluate an application upgrade or downgrade script + Evaluates an application upgrade or downgrade script. App = atom() ToVsn = ToDir = string() - Script -- see upgrade_script/2, downgrade_script/3 + Script + See upgrade_script/2, downgrade_script/3 Unpurged = [Module]  Module = atom() Reason = term() @@ -660,114 +723,100 @@ release_handler:set_unpacked(RelFile, [{myapp,"1.0","/home/user"},...]).

Evaluates an application upgrade or downgrade script Script, the result from calling - upgrade_script/2 or - downgrade_script/3, + upgrade_script/2 or + downgrade_script/3, exactly in the same way as - install_release/1,2 + install_release/1,2 does.

App is the name of the application, which must be started. ToVsn is the version to be upgraded/downgraded to, and ToDir is the library directory of this version. The corresponding modules as well as the .app and - .appup files should be located under Dir/ebin.

-

Returns {ok, Unpurged} if evaluating the script is - successful, where Unpurged is a list of unpurged - modules, or restart_emulator if this instruction is - encountered in the script, or {error, Reason} if - an error occurred when evaluating the script.

-

If the restart_new_emulator instruction is found in - the script, eval_appup_script/4 will return - {error,restart_new_emulator}. 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 - install_release/1,2.

+ .appup files are to be located under Dir/ebin.

+

Returns one of the following:

+ + {ok, Unpurged} if evaluating the script is + successful, where Unpurged is a list of unpurged + modules + restart_emulator if this instruction is + encountered in the script + {error, Reason} if an error occurred when + finding or evaluating the script + +

If the restart_new_emulator instruction is found in + the script, + eval_appup_script/4 + returns {error,restart_new_emulator}. This because + restart_new_emulator 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 + install_release/1,2.
Typical Error Reasons - - -

{bad_masters, Masters} - The master nodes - Masters are not alive.

- - -

{bad_rel_file, File} - Specified .rel file - File can not be read, or does not contain a single - term.

- - -

{bad_rel_data, Data} - Specified .rel file - does not contain a recognized release specification, but - another term Data.

- - -

{bad_relup_file, File} - Specified relup file - Relup contains bad data.

- - -

{cannot_extract_file, Name, Reason} - Problems when - extracting from a tar file, erl_tar:extract/2 returned - {error, {Name, Reason}}.

- - -

{existing_release, Vsn} - Specified release version - Vsn is already in use.

- - -

{Master, Reason, When} - Some operation, indicated by - the term When, failed on the master node Master - with the specified error reason Reason.

- - -

{no_matching_relup, Vsn, CurrentVsn} - Cannot find a - script for up/downgrading between CurrentVsn and - Vsn.

- - -

{no_such_directory, Path} - The directory Path - does not exist.

- - -

{no_such_file, Path} - The path Path (file or - directory) does not exist.

- - -

{no_such_file, {Master, Path}} - The path Path - (file or directory) does not exist at the master node - Master.

- - -

{no_such_release, Vsn} - The specified version - Vsn of the release does not exist.

- - -

{not_a_directory, Path} - Path exists, but is - not a directory.

- - -

{Posix, File} - Some file operation failed for - File. Posix is an atom named from the Posix - error codes, such as enoent, eacces or - eisdir. See file(3).

- - -

Posix - Some file operation failed, as above.

- - + + {bad_masters, Masters} +

The master nodes Masters are not alive.

 + {bad_rel_file, File} +

Specified .rel file File cannot be read or + does not contain a single term.

 + {bad_rel_data, Data} +

Specified .rel file does not contain a recognized + release specification, but another term Data.

 + {bad_relup_file, File} +

Specified relup file Relup contains bad + data.

 + {cannot_extract_file, Name, Reason} +

Problems when extracting from a tar file, + erl_tar:extract/2 + returned {error, {Name, Reason}}.

 + {existing_release, Vsn} +

Specified release version Vsn is already + in use.

 + {Master, Reason, When} +

Some operation, indicated by the term When, failed + on the master node Master with the specified error + reason Reason.

 + {no_matching_relup, Vsn, CurrentVsn} +

Cannot find a script for upgrading/downgrading between + CurrentVsn and Vsn.

 + {no_such_directory, Path} +

The directory Pathdoes not exist.

 + {no_such_file, Path} +

The path Path (file or directory) does not + exist.

 + {no_such_file, {Master, Path}} +

The path Path (file or directory) does not exist at + the master node Master.

 + {no_such_release, Vsn} +

The specified release version Vsn does not + exist.

 + {not_a_directory, Path} +

Path exists but is not a directory.

 + {Posix, File} +

Some file operation failed for File. Posix + is an atom named from the Posix error codes, such as + enoent, eacces, or eisdir. See + file(3) + in Kernel.

 + Posix +

Some file operation failed, as for the previous item in + the list.

 +
- SEE ALSO -

OTP Design Principles, - config(4), - relup(4), - rel(4), - script(4), - sys(3), - systools(3)

+ See Also +

OTP Design Principles, + config(4), + rel(4), + relup(4), + script(4), + sys(3), + systools(3)

diff --git a/lib/sasl/doc/src/relup.xml b/lib/sasl/doc/src/relup.xml index 8eecf3fce2..58918fc8e8 100644 --- a/lib/sasl/doc/src/relup.xml +++ b/lib/sasl/doc/src/relup.xml @@ -36,59 +36,53 @@

The release upgrade file describes how a release is upgraded in a running system.

This file is automatically generated by - systools:make_relup/3,4, using a release resource file - (.rel), application resource files (.app) and + systools:make_relup/3,4, + using a release resource file + (.rel), application resource files (.app), and application upgrade files (.appup) as input.

- FILE SYNTAX -

In a target system, the release upgrade file should be located in - the OTP_ROOT/erts-EVsn/Vsn directory.

+ File Syntax +

In a target system, the release upgrade file is to be located in + directory $ROOT/releases/Vsn.

The relup file contains one single Erlang term, which defines the instructions used to upgrade the release. The file has the following syntax:

{Vsn, [{UpFromVsn, Descr, Instructions}, ...], - [{DownToVsn, Descr, Instructions}, ...]}. - - - -

Vsn = string() is the current version of the release.

- - -

UpFromVsn = string() is an earlier version of the release - to upgrade from.

- - -

Descr = term() is a user defined parameter passed - from the systools:make_relup/3,4 function. It will - be used in the return value of - release_handler:install_release/1,2.

- - -

Instructions is a list of low-level release upgrade - instructions, see appup(4).

-

It consists of the release upgrade instructions from + [{DownToVsn, Descr, Instructions}, ...]}. + + Vsn = string() +

Current release version.

 + UpFromVsn = string() +

Earlier version of the release to upgrade from.

 + Descr = term() +

A user-defined parameter passed + from the function + systools:make_relup/3,4. + It is used in the return value of + release_handler:install_release/1,2.

 + Instructions +

A list of low-level release upgrade instructions, see + appup(4). + 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.

- - -

DownToVsn = string() is an earlier version of the release - to downgrade to.

- - -

When upgrading from UpFromVsn with - release_handler:install_release/1,2, there does not have to be - an exact match of versions, but UpFromVsn can be a sub-string - of the current release version.

+ as in the start script.

+ DownToVsn = string() +

Earlier version of the release to downgrade to.

 +
- SEE ALSO -

app(4), appup(4), rel(4), release_handler(3), systools(3)

+ See Also +

app(4), + appup(4), + rel(4), + release_handler(3), + systools(3)

diff --git a/lib/sasl/doc/src/sasl_app.xml b/lib/sasl/doc/src/sasl_app.xml index fe38e69ce3..8d79251c7e 100644 --- a/lib/sasl/doc/src/sasl_app.xml +++ b/lib/sasl/doc/src/sasl_app.xml @@ -27,12 +27,11 @@ - - sasl - The SASL Application - -

This section describes the SASL (System Architecture Support Libraries) - application which provides the following services:

+ + sasl + The SASL application + +

The SASL application provides the following services:

alarm_handler overload @@ -40,138 +39,147 @@ release_handler systools -

The SASL application also includes error_logger event - handlers for formatting SASL error and crash reports.

- +

The SASL application also includes error_logger event + handlers for formatting SASL error and crash reports.

-

The SASL application in OTP has nothing to do with +

The SASL application in OTP has nothing to do with "Simple Authentication and Security Layer" (RFC 4422).

 -
Error Logger Event Handlers

The following error logger event handlers are used by - the SASL application.

+ the SASL application.

sasl_report_tty_h -

Formats and writes supervisor reports, crash reports and progress reports to stdio. - This error logger event handler will use +

Formats and writes supervisor reports, crash + reports, and progress reports to stdio. + This error logger event handler uses error_logger_format_depth - in the Kernel application to limit how much detail are printed to - for crash and supervisor reports.

+ in the Kernel application to limit how much detail is + printed in crash and supervisor reports.

 sasl_report_file_h -

Formats and writes supervisor reports, crash report and progress report to a single file. - This error logger event handler will use +

Formats and writes supervisor reports, crash + report, and progress report to a single file. + This error logger event handler uses error_logger_format_depth - in the Kernel application to limit how much detail are printed to - for crash and supervisor reports.

+ in the Kernel application to limit the details + printed in crash and supervisor reports.

 log_mf_h -

This error logger writes all events sent to - the error logger to disk.

-

To activate this event handler, the following three sasl - configuration parameters must be set: - error_logger_mf_dir, error_logger_mf_maxbytes - and error_logger_mf_maxfiles. See below for more - information about the configuration parameters.

+

This error logger writes all 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 the STDLIB Reference + Manual.

+

To activate this event handler, three SASL + configuration parameters must be set, + error_logger_mf_dir, error_logger_mf_maxbytes, + and error_logger_mf_maxfiles. The next section provides + more information about the configuration parameters.
Configuration -

The following configuration parameters are defined for the SASL - application. See app(4) for more information about - configuration parameters:

+

The following configuration parameters are defined for the SASL + application. For more information about configuration parameters, see + app(4) in Kernel.

+

All configuration parameters are optional.

- ]]> + -

Value is one of:

+

Value is one of the following:

tty - Installs sasl_report_tty_h in the error logger. - This is the default option. +

Installs sasl_report_tty_h in the error logger. + This is the default option.

 {file,FileName} - Installs sasl_report_file_h in the error logger. - This makes all reports go to the file FileName. - FileName is a string. +

Installs sasl_report_file_h in the error logger. + All reports go to file FileName, which is a + string.

 {file,FileName,Modes} - Same as {file,FileName} except that the Modes - allows to specify the modes used for opening the FileName - given to the file:open/2 - call. When not specified, the Modes defaults to [write]. - Use [append] for having the FileName open in append mode. - FileName is a string. +

Same as {file,FileName}, except that Modes + allows you to specify the modes used for opening the FileName + given to the file:open/2 + call. When not specified, Modes defaults to [write]. + Use [append] to have the FileName open in append mode. + FileName is a string.

 false - -

No SASL error logger handler is installed.

- +

No SASL error logger handler is installed.

 - ]]> +

Restricts the error logging performed by the specified - sasl_error_logger to error reports, progress reports, + sasl_error_logger to error reports or progress reports, or both. Default is all.

 - ]]> + -

Specifies in which directory the files are stored. If this - parameter is undefined or false, +

Specifies in which directory log_mf_h is to store + its files. If this parameter is undefined or false, the log_mf_h handler is not installed.

 - ]]> + -

Specifies how large each individual file can be. If this - parameter is undefined, the log_mf_h handler is not - installed.

+

Specifies the maximum size of each individual file written + by log_mf_h. If this parameter is undefined, + the log_mf_h handler is not installed.

 - ]]> + -

Specifies how many files are used. If this parameter is - undefined, the log_mf_h handler is not installed.

+

Specifies the number of files used by log_mf_h. If + this parameter is undefined, the log_mf_h handler is + not installed.

 - 0 ]]> + 0 ]]> -

Specifies the maximum intensity for overload. Default +

Specifies the maximum intensity + for overload. Default is 0.8.

 - 0 ]]> + 0 ]]> -

Specifies the overload weight. Default is 0.1.

+

Specifies the overload + weight. Default is 0.1.

 - ]]> + -

Specifies which program should be used when restarting - the system. Default is $OTP_ROOT/bin/start.

+

Specifies the program to be used when restarting the system + during release installation. Default is + $OTP_ROOT/bin/start.

 - ]]> + -

Specifies which nodes this node uses to read/write release - information. This parameter is ignored if - the client_directory parameter is not set.

+

Specifies the nodes used by this node to read/write release + information. This parameter is ignored if parameter + client_directory is not set.

 - ]]> +

This parameter specifies the client directory at the master - nodes. Refer to Release Handling in OTP Design Principles for more information. This parameter is - ignored if the masters parameter is not set.

+ nodes. For details, see + Release Handling + in OTP Design Principles. This parameter is + ignored if parameter masters is not set.

 - ]]> +

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 masters - and client_directory parameters are not set.

+ new emulator, as the executable files are written into memory + statically. This parameter is ignored if parameters masters + and client_directory are not set.

 - ]]> +

Indicates where the releases directory is located. The release handler writes all its files to this directory. @@ -179,7 +187,7 @@ RELDIR is used. By default, this is $OTP_ROOT/releases.

 - ]]> +

If set to true, all dates in textual log outputs are displayed in Universal Coordinated Time with the string @@ -190,13 +198,13 @@

See Also -

alarm_handler(3), - error_logger(3), - log_mf_h(3), - overload(3), - rb(3), - release_handler(3), - systools(3)

+

alarm_handler(3), + error_logger(3), + log_mf_h(3), + overload(3), + rb(3), + release_handler(3), + systools(3)

diff --git a/lib/sasl/doc/src/sasl_intro.xml b/lib/sasl/doc/src/sasl_intro.xml index 2dc3efebc1..bbc9457103 100644 --- a/lib/sasl/doc/src/sasl_intro.xml +++ b/lib/sasl/doc/src/sasl_intro.xml @@ -31,22 +31,32 @@
- About This Document -

The SASL (System Architecture Support Libraries) - application provides support for:

+ Scope +

The SASL application provides support for:

- error logging - alarm handling - overload regulation - release handling - report browsing. + Error logging + Alarm handling + Overload regulation + Release handling + Report browsing -

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 rb.

-

The chapters about release structure and release handling have - been moved to OTP Design Principles.

+

Section + SASL Error Logging + 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).

+

The sections about release structure and release handling have + been moved to section + OTP Design Principles + in System Documentation.

+ +
+ Prerequisites +

It is assumed that the reader is familiar with the Erlang + programming language.

+
+ diff --git a/lib/sasl/doc/src/script.xml b/lib/sasl/doc/src/script.xml index 838efe69bb..db3ea0f487 100644 --- a/lib/sasl/doc/src/script.xml +++ b/lib/sasl/doc/src/script.xml @@ -37,25 +37,21 @@ script Boot script -

The boot script describes how the Erlang runtime system is - started. It contains instructions on which code to load and - which processes and applications to start. -

-

The command erl -boot Name starts the system with a boot +

The boot script describes how the Erlang runtime system + is started. It contains instructions on which code to load and + which processes and applications to start.

+

Command erl -boot Name starts the system with a boot file called Name.boot, which is generated from the - Name.script file, using systools:script2boot/1. -

+ Name.script file, using + systools:script2boot/1.

The .script file is generated by systools from a - .rel file and .app files. -

+ .rel file and from .app files.
- FILE SYNTAX -

The boot script is stored in a file with the extension - .script

-

The file has the following syntax: -

+ File Syntax +

The boot script is stored in a file with extension + .script. The file has the following syntax:

{script, {Name, Vsn}, [ @@ -70,100 +66,97 @@ ... {apply, {Mod, Func, Args}}, ... - {progress, started}]}. - - Name = string() defines the name of the system. - - Vsn = string() defines the version of the system. - - {progress, Term} sets the "progress" of the - initialization program. The function init:get_status() - returns the current value of the progress, which is - {InternalStatus,Term}. - - -

{path, [Dir]} where Dir is a string. This + {progress, started}]}. + + Name = string() +

Defines the system name.

 + Vsn = string() +

Defines the system version.

 + {progress, Term} +

Sets the "progress" of the initialization + program. The + init:get_status/0 + function returns the current value of the progress, which is + {InternalStatus,Term}.

 + {path, [Dir]} +

Dir is a string. This argument sets the load path of the system to [Dir]. 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:

-pa Dir1 Dir2 ... DirN adds the directories Dir1, Dir2, ..., DirN to the front of the initial - load path. - + load path. -pz Dir1 Dir2 ... DirN adds the directories Dir1, Dir2, ..., DirN to the end of the initial - load path. - + load path.

-path Dir1 Dir2 ... DirN defines a set of - directories Dir1, Dir2, ..., DirN which replaces + directories Dir1, Dir2, ..., DirN, which replace the search path given in the script file. Directory names in the path are interpreted as follows:

Directory names starting with / are assumed - to be absolute path names. - + to be absolute path names. Directory names not starting with / are - assumed to be relative the current working directory. - + assumed to be relative the current working directory. The special $ROOT 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. - + directory. - - {primLoad, [Mod]} loads the modules [Mod] - from the directories specified in Path. The script - interpreter fetches the appropriate module by calling the - function erl_prim_loader:get_file(Mod). A fatal error - which terminates the system will occur if the module cannot be - located. - - {kernel_load_completed} indicates that all modules - which must be loaded before any processes - are started are loaded. In interactive mode, all - {primLoad,[Mod]} commands interpreted after this - command are ignored, and these modules are loaded on demand. - In embedded mode, kernel_load_completed is ignored, and - all modules are loaded during system start. - - {kernelProcess, Name, {Mod, Func, Args}} starts a - "kernel process". The kernel process Name is started - by evaluating apply(Mod, Func, Args) which is expected - to return {ok, Pid} or ignore. The init - process monitors the behaviour of Pid and terminates - the system if Pid dies. Kernel processes are key - components of the runtime system. Users do not normally add - new kernel processes. - - {apply, {Mod, Func, Args}}. The init process simply - evaluates apply(Mod, Func, Args). The system - terminates if this results in an error. The boot procedure - hangs if this function never returns. - - + + {primLoad, [Mod]} +

Loads the modules [Mod] + from the directories specified in Path. The script + interpreter fetches the appropriate module by calling + + erl_prim_loader:get_file(Mod). A fatal error + that terminates the system occurs if the module cannot be + located.

 + {kernel_load_completed} +

Indicates that all modules + that must be loaded before any processes + are started are loaded. In interactive mode, all + {primLoad,[Mod]} commands interpreted after this + command are ignored, and these modules are loaded on demand. + In embedded mode, kernel_load_completed is ignored, and + all modules are loaded during system start.

 + {kernelProcess, Name, {Mod, Func, Args}} +

Starts the + "kernel process" Name + by evaluating apply(Mod, Func, Args). The start function is + to return {ok, Pid} or ignore. The init + process monitors the behavior of Pid and terminates + the system if Pid dies. Kernel processes are key + components of the runtime system. Users do not normally add + new kernel processes.

 + {apply, {Mod, Func, Args}}. +

The init process + evaluates apply(Mod, Func, Args). The system + terminates if this results in an error. The boot procedure + hangs if this function never returns.

 + -

In the interactive system the code loader provides - demand driven code loading, but in the embedded system - the code loader loads all the code immediately. The same - version of code is used in both cases. The code server - calls init:get_argument(mode) to find out if it should - run in demand mode, or non-demand driven mode. -

+

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 code + is used in both cases. The code server calls + init:get_argument(mode) + to determine if it is to run in demand mode or non-demand + driven mode.
- SEE ALSO -

systools(3) -

+ See Also +

systools(3)

diff --git a/lib/sasl/doc/src/systools.xml b/lib/sasl/doc/src/systools.xml index 11d99fa595..1a5119a5cf 100644 --- a/lib/sasl/doc/src/systools.xml +++ b/lib/sasl/doc/src/systools.xml @@ -31,17 +31,18 @@ systools - A Set of Release Handling Tools. + A Set of Release Handling Tools

This module contains functions to generate boot scripts - (.boot, .script), release upgrade scripts + (.boot, .script), a release upgrade file (relup), and release packages.

 + make_relup(Name, UpFrom, DownTo) -> Result make_relup(Name, UpFrom, DownTo, [Opt]) -> Result - Generate a release upgrade file relup. + Generates a release upgrade file relup. Name = string() UpFrom = DownTo = [Name | {Name,Descr}] @@ -50,93 +51,94 @@ | warnings_as_errors  Dir = string() Result = ok | error | {ok,Relup,Module,Warnings} | {error,Module,Error} -  Relup - see relup(4) +  Relup, see relup(4)  Module = atom()  Warnings = Error = term() -

Generates a release upgrade file relup 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 - release_handler when installing a new version of a - release in run-time.

-

By default, relup is placed in the current working - directory. If the option {outdir,Dir} is provided, - relup is placed in Dir instead.

+

Generates a release upgrade file relup containing instructions + for upgrading from or downgrading to one or more previous releases. + The instructions are used by + release_handler + when installing a new version of a release in runtime.

+

By default, relup file is located in the current working + directory. If option {outdir,Dir} is specified, + the relup file is located in Dir instead.

The release resource file Name.rel is compared with - all release resource files Name2.rel specified in - UpFrom and DownTo. For each such pair, it is - deducted:

+ all release resource files Name2.rel, specified in + UpFrom and DownTo. For each such pair, the + following is deducted:

-

Which applications should be deleted, that is - applications which are listed in Name.rel but not - in Name2.rel.

+

Which applications to be deleted, that is, + applications listed in Name.rel but not + in Name2.rel

 -

Which applications should be added, that is applications - which are listed in Name2.rel but not in - Name.rel.

+

Which applications to be added, that is, applications + listed in Name2.rel but not in Name.rel

 -

Which applications should be upgraded/downgraded, that - is applications listed in both Name.rel and - Name2.rel, but with different versions.

+

Which applications to be upgraded/downgraded, that + is, applications listed in both Name.rel and + Name2.rel but with different versions

If the emulator needs to be restarted after upgrading or - downgrading, that is if the ERTS version differs between - Name.rel and Name2.rel.

+ downgrading, that is, if the ERTS version differs + between Name.rel and Name2.rel

 -

Instructions for this are added to the relup script in +

Instructions for this are added to the relup file in the above order. Instructions for upgrading or downgrading between application versions are fetched from the relevant application upgrade files App.appup, sorted in the same order as when generating a boot script, see - make_script/1,2. High-level instructions are translated - into low-level instructions and the result is printed to - relup.

-

The optional Descr parameter is included as-is in - the relup script, see relup(4). Defaults to + make_script/1,2. + High-level instructions are translated + into low-level instructions and the result is printed to the + relup file.

+

The optional Descr parameter is included "as is" in + the relup file, see + relup(4). Defaults to the empty list.

All the files are searched for in the code path. It is - assumed that the .app and .appup file for an - application is located in the same directory.

-

If the option {path,[Dir]} is provided, this path is - appended to the current path. The wildcard * is - expanded to all matching directories. - Example: lib/*/ebin.

-

If the restart_emulator option is supplied, a + assumed that the .app and .appup files for an + application are located in the same directory.

+

If option {path,[Dir]} is specified, this path is + appended to the current path. Wildcard * is + expanded to all matching directories, for example, + lib/*/ebin.

+

If option restart_emulator is specified, a low-level instruction to restart the emulator is appended to - the relup scripts. This ensures that a complete reboot of + the relup file. This ensures that a complete reboot of the system is done when the system is upgraded or downgraded.

-

If an upgrade includes a change from an emulator earlier - than OTP R15 to OTP R15 or later, the warning - pre_R15_emulator_upgrade is issued. See Design - Principles for more information about this.

+

If an upgrade includes a change from an emulator earlier + than OTP R15 to OTP R15 or later, the warning + pre_R15_emulator_upgrade is issued. For more information + about this, see + Design + Principles in System Documentation.

By default, errors and warnings are printed to tty and - the function returns ok or error. If the option - silent is provided, the function instead returns - {ok,Relup,Module,Warnings} where Relup is - the release upgrade script, or it returns - {error,Module,Error}. Warnings and errors can be - converted to strings by calling + the function returns ok or error. If option + silent is specified, the function instead either returns + {ok,Relup,Module,Warnings}, where Relup is + the release upgrade file, or {error,Module,Error}. + Warnings and errors can be converted to strings by calling Module:format_warning(Warnings) or Module:format_error(Error).

-

If the option noexec is provided, the function returns +

If option noexec is specified, the function returns the same values as for silent but no relup file is created.

-

If the option warnings_as_errors is provided, warnings - are treated as errors.

+

If option warnings_as_errors is specified, warnings + are treated as errors.

 + make_script(Name) -> Result make_script(Name, [Opt]) -> Result - Generate a boot script .script/.boot. + Generates a boot script .script/.boot. Name = string() Opt = src_tests | {path,[Dir]} | local | {variables,[Var]} | exref | @@ -153,114 +155,117 @@

Generates a boot script Name.script and its binary version, the boot file Name.boot. The boot file - specifies which code should be loaded and which applications - should be started when the Erlang runtime system is started. - See script(4).

-

The release resource file Name.rel is read to find - out which applications are included in the release. Then - the relevant application resource files App.app are - read to find out which modules should be loaded and if and - how the application should be started. (Keys modules - and mod, see app(4)).

-

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 script(4).

+

The release resource file Name.rel is read to determine + which applications are included in the release. Then + the relevant application resource files App.app are read + to determine which modules to be loaded, and if and + how the applications are to be started. (Keys modules + and mod, see + app(4).

+

By default, the boot script and boot file are located in the same directory as Name.rel. That is, in the current working directory unless Name contains a path. If - the option {outdir,Dir} is provided, they are placed + option {outdir,Dir} is specified, they are located in Dir instead.

-

The correctness of each application is checked:

+

The correctness of each application is checked as follows:

The version of an application specified in - the .rel file should be the same as the version + the .rel file is to be the same as the version specified in the .app file.

 -

There should be no undefined applications, that is, - dependencies to applications which are not included in - the release. (Key applications in .app +

There are to be no undefined applications, that is, + dependencies to applications that are not included in + the release. (Key applications in the .app file).

 -

There should be no circular dependencies among +

There are to be no circular dependencies among the applications.

 -

There should be no duplicated modules, that is, modules with +

There are to be no duplicated modules, that is, modules with the same name but belonging to different applications.

 -

If the src_tests option is specified, a +

If option src_tests is specified, a warning is issued if the source code for a module is - missing or newer than the object code.

+ missing or is newer than the object code.

The applications are sorted according to the dependencies between the applications. Where there are no dependencies, the order in the .rel file is kept.

-

The function will fail if the mandatory - applications kernel and stdlib are not - included in the .rel file and have start - type permanent (default).

-

If sasl is not included as an application in - the .rel file, a warning is emitted because such a - release can not be used in an upgrade. To turn off this - warning, add the option no_warn_sasl.

+

The function fails if the mandatory + applications Kernel and STDLIB are not + included in the .rel file and have start + type permanent (which is default).

+

If SASL is not included as an application in + the .rel file, a warning is issued because such a + release cannot be used in an upgrade. To turn off this + warning, add option no_warn_sasl.

All files are searched for in the current path. It is assumed that the .app and .beam files for an - application is located in the same directory. The .erl + application are located in the same directory. The .erl files are also assumed to be located in this directory, unless - it is an ebin directory in which case they may be + it is an ebin directory in which case they can be located in the corresponding src directory.

-

If the option {path,[Dir]} is provided, this path is +

If option {path,[Dir]} is specified, this path is appended to the current path. A directory in the path can be - given with a wildcard *, this is expanded to all + specified with a wildcard *, this is expanded to all matching directories. Example: "lib/*/ebin".

In the generated boot script all application directories are - structured as App-Vsn/ebin and assumed to be located + structured as App-Vsn/ebin. They are assumed to be located in $ROOT/lib, where $ROOT is the root directory - of the installed release. If the local option is - supplied, the actual directories where the applications were + of the installed release. If option local 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.

-

The variables option can be used to specify an +

Option variables can be used to specify an installation directory other than $ROOT/lib for some of the applications. If a variable {VarName,Prefix} is specified and an application is found in a directory - Prefix/Rest/App[-Vsn]/ebin, this application will get + Prefix/Rest/App[-Vsn]/ebin, this application gets the path VarName/Rest/App-Vsn/ebin in the boot script. If an application is found in a directory Prefix/Rest, - the path will be VarName/Rest/App-Vsn/ebin. When + the path is VarName/Rest/App-Vsn/ebin. When starting Erlang, all variables VarName are given - values using the boot_var command line flag.

-

Example: If the option {variables,[{"TEST","lib"}]} is - supplied, and myapp.app is found in - lib/myapp/ebin, then the path to this application in - the boot script will be "$TEST/myapp-1/ebin". If - myapp.app is found in lib/test, then the path - will be $TEST/test/myapp-1/ebin.

+ values using command-line flag boot_var.

+

Example: If option {variables,[{"TEST","lib"}]} + is specified and myapp.app is found in + lib/myapp/ebin, the path to this application in + the boot script is "$TEST/myapp-1/ebin". If + myapp.app is found in lib/test, the path + is $TEST/test/myapp-1/ebin.

The checks performed before the boot script is generated can be extended with some cross reference checks by specifying - the exref option. These checks are performed with + option exref. These checks are performed with the Xref tool. All applications, or the applications specified with {exref,[App]}, are checked by Xref and - warnings are generated for calls to undefined functions.

+ warnings are issued for calls to undefined functions.

By default, errors and warnings are printed to tty and - the function returns ok or error. If the option - silent is provided, the function instead returns + the function returns ok or error. If option + silent is specified, the function instead returns {ok,Module,Warnings} or {error,Module,Error}. Warnings and errors can be converted to strings by calling Module:format_warning(Warnings) or Module:format_error(Error).

-

If the option warnings_as_errors is provided, warnings - are treated as errors.

-

If the option no_dot_erlang is provided, the instruction to - load the .erlang file during boot is NOT included.

+

If option warnings_as_errors is specified, warnings + are treated as errors.

+

If option no_dot_erlang is specified, the instruction to + load the .erlang file during boot is not + included.

 + make_tar(Name) -> Result make_tar(Name, [Opt]) -> Result - Create a release package. + Creates a release package. Name = string() Opt = {dirs,[IncDir]} | {path,[Dir]} | {variables,[Var]} | {var_tar,VarTar} | {erts,Dir} | src_tests | exref | {exref,[App]} | silent | {outdir,Dir} @@ -276,90 +281,91 @@  Warning = Error = term() -

Creates a release package file Name.tar.gz. file. +

Creates a release package file Name.tar.gz. This file must be uncompressed and unpacked on the target - system using the release_handler, before the new - release can be installed.

-

The release resource file Name.rel is read to find out + system using + release_handler + before the new release can be installed.

+

The release resource file Name.rel is read to determine which applications are included in the release. Then the relevant application resource files App.app are - read to find out the version and modules of each application. - (Keys vsn and modules, see app(4)).

-

By default, the release package file is placed in the same + read to determine the version and modules of each application + (keys vsn and modules, see + app(4)).

+

By default, the release package file is located in the same directory as Name.rel. That is, in the current working - directory unless Name contains a path. If the option - {outdir,Dir} is provided, it is placed in Dir + directory unless Name contains a path. If option + {outdir,Dir} is specified, it is located in Dir instead.

By default, the release package contains the directories lib/App-Vsn/ebin and lib/App-Vsn/priv for each - included application. If more directories, the option - dirs is supplied. Example: + included application. If more directories are to be included, + option dirs is specified, for example, {dirs,[src,examples]}.

All these files are searched for in the current path. If - the option {path,[Dir]} is provided, this path is - appended to the current path. The wildcard * is + option {path,[Dir]} is specified, this path is + appended to the current path. Wildcard * is expanded to all matching directories. Example: "lib/*/ebin".

-

The variables option can be used to specify an +

Option variables can be used to specify an installation directory other than lib for some of - the applications. If a variable {VarName,Prefix} is - specified and an application is found in a directory - Prefix/Rest/App[-Vsn]/ebin, this application will be + the applications. If variable {VarName,Prefix} is + specified and an application is found in directory + Prefix/Rest/App[-Vsn]/ebin, this application is packed into a separate VarName.tar.gz file as Rest/App-Vsn/ebin.

-

Example: If the option {variables,[{"TEST","lib"}]} is - supplied, and myapp.app is found in - lib/myapp-1/ebin, the the application myapp is +

Example: If option {variables,[{"TEST","lib"}]} + is specified and myapp.app is located in + lib/myapp-1/ebin, application myapp is included in TEST.tar.gz:

 % tar tf TEST.tar
 myapp-1/ebin/myapp.app
-...
-
-

The {var_tar,VarTar} option can be used to specify if - and where a separate package should be stored. In this option, - VarTar is:

- - -

include. Each separate (variable) package is - included in the main ReleaseName.tar.gz file. This - is the default.

- - -

ownfile. Each separate (variable) package is - generated as separate files in the same directory as - the ReleaseName.tar.gz file.

- - -

omit. No separate (variable) packages are - generated and applications which are found underneath a - variable directory are ignored.

- - -

A directory called releases is also included in +... +

Option {var_tar,VarTar} can be used to specify if + and where a separate package is to be stored. In this option + VarTar is one of the following:

+ + include +

Each separate (variable) package is included in the + main ReleaseName.tar.gz file. This is the + default.

 + ownfile +

Each separate (variable) package is + generated as a separate file in the same directory as + the ReleaseName.tar.gz file.

 + omit +

No separate (variable) packages are + generated. Applications that are found underneath a + variable directory are ignored.

 + +

A directory releases is also included in the release package, containing Name.rel and a - subdirectory called RelVsn. RelVsn is + subdirectory RelVsn. RelVsn is the release version as specified in Name.rel.

releases/RelVsn contains the boot script Name.boot renamed to start.boot and, if found, the files relup and sys.config. These files are searched for in the same directory as Name.rel, in the current working directory, and in any directories - specified using the path option.

-

If the release package should contain a new Erlang runtime + specified using option path.

+

If the release package is to contain a new Erlang runtime system, the bin directory of the specified runtime system {erts,Dir} is copied to erts-ErtsVsn/bin.

-

All checks performed with the make_script function - are performed before the release package is created. The - src_tests and exref options are also +

All checks with function + make_script + are performed before the release package is created. + Options src_tests and exref are also valid here.

The return value and the handling of errors and warnings - are the same as described for make_script above.

+ are the same as described for + make_script.

 + script2boot(File) -> ok | error - Generate a binary version of a boot script. + Generates a binary version of a boot script. File = string() @@ -367,17 +373,24 @@ myapp-1/ebin/myapp.app

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 File.script boot script - to a binary term which is stored in the file File.boot.

-

A boot script generated using the make_script - function is already transformed to the binary form.

+ to a binary term, which is stored in the File.boot + file.

+

A boot script generated using + make_script + is already transformed to the binary form.
- SEE ALSO -

app(4), appup(4), erl(1), rel(4), release_handler(3), relup(4), - script(4)

+ See Also +

app(4), + appup(4), + erl(1), + rel(4), + release_handler(3), + relup(4), + script(4)

-- cgit v1.2.3