sys(3erl)						     Erlang Module Definition							 sys(3erl)

NAME

       sys - A Functional Interface to System Messages

DESCRIPTION

       This module contains functions for sending system messages used by programs, and messages used for debugging purposes.

       Functions  used	for  implementation  of processes should also understand system messages such as debugging messages and code change. These
       functions must be used to implement the use of system messages for a process; either directly, or  through  standard  behaviours,  such	as
       gen_server .

       The following types are used in the functions defined below:

	 * Name = pid() | atom() | {global, atom()}

	 * Timeout = int() >= 0 | infinity

	 * system_event() = {in, Msg} | {in, Msg, From} | {out, Msg, To} | term()

       The  default  timeout  is  5000 ms, unless otherwise specified. The timeout defines the time period to wait for the process to respond to a
       request. If the process does not respond, the function evaluates exit({timeout, {M, F, A}}) .

       The functions make reference to a debug structure. The debug structure is a list of dbg_opt() . dbg_opt() is an internal data type used	by
       the handle_system_msg/6 function. No debugging is performed if it is an empty list.

SYSTEM MESSAGES

       Processes which are not implemented as one of the standard behaviours must still understand system messages. There are three different mes-
       sages which must be understood:

	 * Plain system messages. These are received as {system, From, Msg} . The content and meaning of this message are not interpreted  by  the
	   receiving  process  module.	When a system message has been received, the function sys:handle_system_msg/6 is called in order to handle
	   the request.

	 * Shutdown messages. If the process traps exits, it must be able to handle an shut-down request from its parent, the supervisor. The mes-
	   sage  {'EXIT', Parent, Reason} from the parent is an order to terminate. The process must terminate when this message is received, nor-
	   mally with the same Reason as Parent .

	 * There is one more message which the process must understand if the modules used to implement the process change dynamically during run-
	   time.  An example of such a process is the gen_event processes. This message is {get_modules, From} . The reply to this message is From
	   ! {modules, Modules} , where Modules is a list of the currently active modules in the process.

	   This message is used by the release handler to find which processes execute a certain module. The process may at a later time  be  sus-
	   pended and ordered to perform a code change for one of its modules.

SYSTEM EVENTS

       When  debugging	a process with the functions of this module, the process generates system_events which are then treated in the debug func-
       tion. For example, trace formats the system events to the tty.

       There are three predefined system events which are used when a process receives or sends a message. The process can  also  define  its  own
       system events. It is always up to the process itself to format these events.

EXPORTS

       log(Name,Flag)
       log(Name,Flag,Timeout) -> ok | {ok, [system_event()]}

	      Types  Flag = true | {true, N} | false | get | print
		     N = integer() > 0

	      Turns  the  logging of system events On or Off. If On, a maximum of N events are kept in the debug structure (the default is 10). If
	      Flag is get , a list of all logged events is returned. If Flag is print , the logged events are printed to standard_io . The  events
	      are formatted with a function that is defined by the process that generated the event (with a call to sys:handle_debug/4 ).

       log_to_file(Name,Flag)
       log_to_file(Name,Flag,Timeout) -> ok | {error, open_file}

	      Types  Flag = FileName | false
		     FileName = string()

	      Enables or disables the logging of all system events in textual format to the file. The events are formatted with a function that is
	      defined by the process that generated the event (with a call to sys:handle_debug/4 ).

       statistics(Name,Flag)
       statistics(Name,Flag,Timeout) -> ok | {ok, Statistics}

	      Types  Flag = true | false | get
		     Statistics = [{start_time, {Date1, Time1}}, {current_time, {Date, Time2}}, {reductions, integer()}, {messages_in, integer()},
		     {messages_out, integer()}]
		     Date1 = Date2 = {Year, Month, Day}
		     Time1 = Time2 = {Hour, Min, Sec}

	      Enables or disables the collection of statistics. If Flag is get , the statistical collection is returned.

       trace(Name,Flag)
       trace(Name,Flag,Timeout) -> void()

	      Types  Flag = boolean()

	      Prints all system events on standard_io . The events are formatted with a function that is defined by the process that generated the
	      event (with a call to sys:handle_debug/4 ).

       no_debug(Name)
       no_debug(Name,Timeout) -> void()

	      Turns off all debugging for the process. This includes functions that have been installed explicitly with the install function,  for
	      example triggers.

       suspend(Name)
       suspend(Name,Timeout) -> void()

	      Suspends the process. When the process is suspended, it will only respond to other system messages, but not other messages.

       resume(Name)
       resume(Name,Timeout) -> void()

	      Resumes a suspended process.

       change_code(Name, Module, OldVsn, Extra)
       change_code(Name, Module, OldVsn, Extra, Timeout) -> ok | {error, Reason}

	      Types  OldVsn = undefined | term()
		     Module = atom()
		     Extra = term()

	      Tells  the  process  to  change  code. The process must be suspended to handle this message. The Extra argument is reserved for each
	      process to use as its own. The function Mod:system_code_change/4 is called. OldVsn is the old version of the Module .

       get_status(Name)
       get_status(Name,Timeout) -> {status, Pid, {module, Mod}, [PDict, SysState, Parent, Dbg, Misc]}

	      Types  PDict = [{Key, Value}]
		     SysState = running | suspended
		     Parent = pid()
		     Dbg = [dbg_opt()]
		     Misc = term()

	      Gets the status of the process.

	      The value of Misc varies for different types of processes. For example, a gen_server process returns the	callback  module's  state,
	      and  a gen_fsm process returns information such as its current state name. Callback modules for gen_server and gen_fsm can also cus-
	      tomise the value of Misc by exporting a format_status/2 function that contributes module-specific information;  see  gen_server:for-
	      mat_status/2 and gen_fsm:format_status/2 for more details.

       install(Name,{Func,FuncState})
       install(Name,{Func,FuncState},Timeout)

	      Types  Func = dbg_fun()
		     dbg_fun() = fun(FuncState, Event, ProcState) -> done | NewFuncState
		     FuncState = term()
		     Event = system_event()
		     ProcState = term()
		     NewFuncState = term()

	      This  function  makes  it  possible to install other debug functions than the ones defined above. An example of such a function is a
	      trigger, a function that waits for some special event and performs some action when the event is generated. This could, for example,
	      be turning on low level tracing.

	      Func  is called whenever a system event is generated. This function should return done , or a new func state. In the first case, the
	      function is removed. It is removed if the function fails.

       remove(Name,Func)
       remove(Name,Func,Timeout) -> void()

	      Types  Func = dbg_fun()

	      Removes a previously installed debug function from the process. Func must be the same as previously installed.

PROCESS IMPLEMENTATION FUNCTIONS

       The following functions are used when implementing a special process. This is an ordinary process which does not use a standard	behaviour,
       but a process which understands the standard system messages.

EXPORTS

       debug_options(Options) -> [dbg_opt()]

	      Types  Options = [Opt]
		     Opt = trace | log | statistics | {log_to_file, FileName} | {install, {Func, FuncState}}
		     Func = dbg_fun()
		     FuncState = term()

	      This  function  can be used by a process that initiates a debug structure from a list of options. The values of the Opt argument are
	      the same as the corresponding functions.

       get_debug(Item,Debug,Default) -> term()

	      Types  Item = log | statistics
		     Debug = [dbg_opt()]
		     Default = term()

	      This function gets the data associated with a debug option. Default is returned if the Item is not found. Can be used by the process
	      to retrieve debug data for printing before it terminates.

       handle_debug([dbg_opt()],FormFunc,Extra,Event) -> [dbg_opt()]

	      Types  FormFunc = dbg_fun()
		     Extra = term()
		     Event = system_event()

	      This  function  is  called by a process when it generates a system event. FormFunc is a formatting function which is called as Form-
	      Func(Device, Event, Extra) in order to print the events, which is necessary if tracing is activated. Extra is any extra  information
	      which the process needs in the format function, for example the name of the process.

       handle_system_msg(Msg,From,Parent,Module,Debug,Misc)

	      Types  Msg = term()
		     From = pid()
		     Parent = pid()
		     Module = atom()
		     Debug = [dbg_opt()]
		     Misc = term()

	      This  function  is  used by a process module that wishes to take care of system messages. The process receives a {system, From, Msg}
	      message and passes the Msg and From to this function.

	      This function never returns. It calls the function Module:system_continue(Parent, NDebug, Misc) where the process continues the exe-
	      cution,  or Module:system_terminate(Reason, Parent, Debug, Misc) if the process should terminate. The Module must export system_con-
	      tinue/3 , system_terminate/4 , and system_code_change/4 (see below).

	      The Misc argument can be used to save internal data in a process, for example its state. It is sent to  Module:system_continue/3	or
	      Module:system_terminate/4

       print_log(Debug) -> void()

	      Types  Debug = [dbg_opt()]

	      Prints  the  logged  system  events  in the debug structure using FormFunc as defined when the event was generated by a call to han-
	      dle_debug/4 .

       Mod:system_continue(Parent, Debug, Misc)

	      Types  Parent = pid()
		     Debug = [dbg_opt()]
		     Misc = term()

	      This function is called from sys:handle_system_msg/6 when the process should continue its execution (for example after it  has  been
	      suspended). This function never returns.

       Mod:system_terminate(Reason, Parent, Debug, Misc)

	      Types  Reason = term()
		     Parent = pid()
		     Debug = [dbg_opt()]
		     Misc = term()

	      This  function  is  called from sys:handle_system_msg/6 when the process should terminate. For example, this function is called when
	      the process is suspended and its parent orders shut-down. It gives the process a chance  to  do  a  clean-up.  This  function  never
	      returns.

       Mod:system_code_change(Misc, Module, OldVsn, Extra) -> {ok, NMisc}

	      Types  Misc = term()
		     OldVsn = undefined | term()
		     Module = atom()
		     Extra = term()
		     NMisc = term()

	      Called  from  sys:handle_system_msg/6  when the process should perform a code change. The code change is used when the internal data
	      structure has changed. This function converts the Misc argument to the new data structure. OldVsn is the vsn attribute  of  the  old
	      version of the Module . If no such attribute was defined, the atom undefined is sent.

Ericsson AB							   stdlib 1.17.3							 sys(3erl)