👤
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 sys (linux section 3erl)

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 under-
       stand system messages. There are three different messages 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 message {'EXIT', Parent, Reason} from the
	   parent  is  an  order  to  terminate.  The process must terminate when this message is
	   received, normally 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 runtime. 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 suspended 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  sys-
       tem_events  which  are  then treated in the debug function. 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 gen-
	      erated 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 gener-
	      ated 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,  inte-
		     ger()}]
		     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:han-
	      dle_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 mes-
	      sage. The Extra argument is reserved for each process to use as its own. The  func-
	      tion 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  customise the value of Misc by exporting a format_status/2
	      function that contributes module-specific information;  see  gen_server:format_sta-
	      tus/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 stan-
       dard 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 func-
	      tions.

       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 print-
	      ing 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 FormFunc(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  mes-
	      sages.  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 execution, or Module:system_termi-
	      nate(Reason, Parent, Debug, Misc) if the process should terminate. The Module  must
	      export  system_continue/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 handle_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  con-
	      tinue  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 termi-
	      nate.  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 func-
	      tion 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 unde-
	      fined is sent.

Ericsson AB				  stdlib 1.17.3 				sys(3erl)


All times are GMT -4. The time now is 05:14 PM.

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