👤
Home Man
Search
Today's Posts
Register

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:
Select Section of Man Page:
Select Man Page Repository:

Linux 2.6 - man page for appup (linux section 5)

appup(5)				      Files					 appup(5)

NAME
       appup - Application upgrade file.

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

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 directory for the applica-
       tion.

       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:

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

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

	 * UpFromVsn = string() is an earlier version of the application to upgrade from.

	 * DownToVsn = string() is an earlier version of the application to downgrade to.

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

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

       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(3erl) . 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}
       {update, Mod, Change}
       {update, Mod, DepMods}
       {update, Mod, Change, DepMods}
       {update, Mod, Change, PrePurge, PostPurge, DepMods}
       {update, Mod, Timeout, Change, PrePurge, PostPurge, DepMods}
       {update, Mod, ModType, Timeout, Change, PrePurge, PostPurge, DepMods}
	 Mod = atom()
	 ModType = static | dynamic
	 Timeout = int()>0 | default | infinity
	 Change = soft | {advanced,Extra}
	   Extra = term()
	 PrePurge = PostPurge = soft_purge | brutal_purge
	 DepMods = [Mod]

       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 pro-
       cesses 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 pro-
       cesses  will  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 is bru-
       tal_purge ,  the  processes  are  killed.  If  the  value  is  soft_purge  ,  release_han-
       dler:install_release/1 returns {error,{old_processes,Mod}} .

       PostPurge  defaults  to	brutal_purge and controls what action to take with processes that
       are executing old code when the new version of the module has been loaded. If the value is
       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 instructions for suspend-
       ing processes using modules in DepMods when upgrading, and vice versa 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 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.

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

       {load_module, Mod}
       {load_module, Mod, DepMods}
       {load_module, Mod, PrePurge, PostPurge, DepMods}
	 Mod = atom()
	 PrePurge = PostPurge = soft_purge | brutal_purge
	 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.

       {add_module, Mod}
	 Mod = atom()

       Loads a new module Mod .

       {delete_module, Mod}
	 Mod = atom()

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

       {add_application, Application}
       {add_application, Application, Type}
	 Application = atom()
	 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 = per-
       manent | transient | temporary , the application will be loaded and started in the  corre-
       sponding  way,  see  application(3erl)  .  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.

       {remove_application, Application}
	 Application = atom()

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

       {restart_application, Application}
	 Application = atom()

       Restarting  an  application  means  that the application is stopped and then started again
       similar to using the instructions remove_application and add_application in sequence.

       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 .

       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 placed after all load_object_code instructions.

       {load, {Mod, PrePurge, PostPurge}}
	 Mod = atom()
	 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 .

       {remove, {Mod, PrePurge, PostPurge}}
	 Mod = atom()
	 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 .

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

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

       {suspend, [Mod | {Mod, Timeout}]}
	 Mod = atom()
	 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 the process to die, either because  it  crashes	when  it  sponta-
       neously switches to new code, or as a result of a purge operation. If no Timeout is speci-
       fied or default is given, the default value for sys:suspend is used.

       {resume, [Mod]}
	 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()

       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.

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

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

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

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

       {sync_nodes, Id, [Node]}
       {sync_nodes, Id, {M, F, A}}
	 Id = term()
	 Node = node()
	 M = F = atom()
	 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 Id . The local node waits  for  all  other	nodes  to
       evaluate  the instruction before execution continues. In case a node goes down, it is con-
       sidered to be an unrecoverable error, and  the  local  node  is	restarted  from  the  old
       release. There is no timeout for this instruction, which means that it may hang forever.

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

       restart_new_emulator

       Shuts  down  the current emulator and starts a ne one. All processes are terminated grace-
       fully. The new release must still be made permanent when the new emulator is up	and  run-
       ning.  Otherwise, the old emulator is started in case of a emulator restart. This instruc-
       tion should be used when a new emulator is introduced, or if a complete reboot of the sys-
       tem should be done.

SEE ALSO
       relup(5) , release_handler(3erl) , supervisor(3erl), systools(3erl)

Ericsson AB				   sasl 2.1.9.3 				 appup(5)


All times are GMT -4. The time now is 04:19 AM.

Unix & Linux Forums Content Copyrightę1993-2018. All Rights Reserved.
×
UNIX.COM Login
Username:
Password:  
Show Password