Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
sys(3)			   Erlang Module Definition			sys(3)

NAME
       sys - A functional interface to system messages.

DESCRIPTION
       This module contains functions for sending system messages used by pro-
       grams, and messages used	for debugging purposes.

       Functions used for implementation of processes are also expected	to un-
       derstand	system messages, such as debug messages	and code change. These
       functions must be used to implement the use of system  messages	for  a
       process;	 either	 directly,  or	through	 standard  behaviors,  such as
       gen_server.

       The default time-out is 5000 ms,	unless	otherwise  specified.  timeout
       defines	the  time  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 references to	a debug	structure. The debug structure
       is a list of dbg_opt(), which is	an internal data type used by function
       handle_system_msg/6. No debugging is performed if it is an empty	list.

SYSTEM MESSAGES
       Processes  that	are  not  implemented as one of	the standard behaviors
       must still understand system messages.  The  following  three  messages
       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 is received, func-
	   tion	handle_system_msg/6 is called to handle	the request.

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

	 * If the modules used to implement  the  process  change  dynamically
	   during  runtime,  the  process must understand one more message. An
	   example is the gen_event processes. The message is {_Label,	{From,
	   Ref},  get_modules}.	The reply to this message is From ! {Ref, Mod-
	   ules}, 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
	   that	execute	a certain module. The process can later	 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 system_events,	which are then treated in the debug  function.
       For example, trace formats the system events to the terminal.

       Four predefined system events are used when a process receives or sends
       a message. The process can also define its own system events. It	is al-
       ways up to the process itself to	format these events.

DATA TYPES
       name() =
	   pid() | atom() | {global, term()} | {via, module(), term()}

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

       dbg_opt()

	      See the introduction of this manual page.

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

       format_fun() =
	   fun((Device :: io:device() |	file:io_device(),
		Event :: system_event(),
		Extra :: term()) ->
		   any())

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

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

	      Types:

		 Name =	name()
		 Module	= module()
		 OldVsn	= undefined | term()
		 Extra = term()
		 Timeout = timeout()
		 Reason	= term()

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

       get_state(Name) -> State

       get_state(Name, Timeout)	-> State

	      Types:

		 Name =	name()
		 Timeout = timeout()
		 State = term()

	      Gets the state of	the process.

	  Note:
	      These functions are intended only	to help	with  debugging.  They
	      are  provided for	convenience, allowing developers to avoid hav-
	      ing to create their own  state  extraction  functions  and  also
	      avoid  having to interactively extract the state from the	return
	      values of	get_status/1 or	get_status/2 while debugging.

	      The value	of State varies	for different types of	processes,  as
	      follows:

		* For a	gen_server process, the	returned State is the state of
		  the callback module.

		* For  a  gen_statem  process,	State  is  the	 tuple	 {Cur-
		  rentState,CurrentData}.

		* For  a  gen_event  process, State is a list of tuples, where
		  each tuple corresponds to an event handler registered	in the
		  process and contains {Module,	Id, HandlerState}, as follows:

		  Module:
		    The	module name of the event handler.

		  Id:
		    The	ID of the handler (which is false if it	was registered
		    without an ID).

		  HandlerState:
		    The	state of the handler.

	      If the callback module exports a function	system_get_state/1, it
	      is  called  in the target	process	to get its state. Its argument
	      is the same as the Misc value returned  by  get_status/1,2,  and
	      function	Module:system_get_state/1  is  expected	to extract the
	      state  of	 the  callback	 module	  from	 it.   Function	  sys-
	      tem_get_state/1  must  return  {ok,  State},  where State	is the
	      state of the callback module.

	      If the callback module  does  not	 export	 a  system_get_state/1
	      function,	get_state/1,2 assumes that the Misc value is the state
	      of the callback module and returns it directly instead.

	      If the callback module's system_get_state/1 function crashes  or
	      throws   an  exception,  the  caller  exits  with	 error	{call-
	      back_failed, {Module, system_get_state}, {Class, Reason}}, where
	      Module  is  the name of the callback module and Class and	Reason
	      indicate details of the exception.

	      Function system_get_state/1 is primarily useful for user-defined
	      behaviors	 and modules that implement OTP	special	processes. The
	      gen_server, gen_statem, and gen_event OTP	behavior  modules  ex-
	      port this	function, so callback modules for those	behaviors need
	      not to supply their own.

	      For more information about a process, including its  state,  see
	      get_status/1 and get_status/2.

       get_status(Name)	-> Status

       get_status(Name,	Timeout) -> Status

	      Types:

		 Name =	name()
		 Timeout = timeout()
		 Status	=
		     {status,  Pid  ::	pid(),	{module,  Module :: module()},
		 [SItem]}
		 SItem =
		     (PDict :: [{Key ::	term(),	Value :: term()}]) |
		     (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 state of the callback mod-
		  ule.

		* A gen_statem process returns information, such as  its  cur-
		  rent state name and state data.

		* A  gen_event	process	 returns information about each	of its
		  registered handlers.

	      Callback modules for gen_server, gen_statem, and	gen_event  can
	      also  change  the	 value	of  Misc  by exporting a function for-
	      mat_status/2, which contributes module-specific information. For
	      details,	see gen_server:format_status/2,	gen_statem:format_sta-
	      tus/2, and gen_event:format_status/2.

       install(Name, FuncSpec) -> ok

       install(Name, FuncSpec, Timeout)	-> ok

	      Types:

		 Name =	name()
		 FuncSpec = {Func, FuncState} |	{FuncId, Func, FuncState}
		 FuncId	= term()
		 Func =	dbg_fun()
		 FuncState = term()
		 Timeout = timeout()

	      Enables installation of alternative debug	functions. 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	gener-
	      ated. For	example, turning on low-level tracing.

	      Func  is called whenever a system	event is generated. This func-
	      tion is to return	done, or a new Func state. In the first	 case,
	      the  function  is	 removed.  It  is also removed if the function
	      fails. If	one debug function should be installed more  times,  a
	      unique FuncId must be specified for each installation.

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

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

	      Types:

		 Name =	name()
		 Flag  =  true	|  {true, N :: integer() >= 1} | false | get |
		 print
		 Timeout = timeout()

	      Turns the	logging	of system events on or off. If on,  a  maximum
	      of N events are kept in the debug	structure (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  handle_de-
	      bug/4).

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

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

	      Types:

		 Name =	name()
		 Flag =	(FileName :: string()) | false
		 Timeout = timeout()

	      Enables  or  disables  the  logging of all system	events in text
	      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 handle_debug/4). The file	is opened with encoding	UTF-8.

       no_debug(Name) -> ok

       no_debug(Name, Timeout) -> ok

	      Types:

		 Name =	name()
		 Timeout = timeout()

	      Turns off	all debugging for the process. This includes functions
	      that are installed explicitly with function install/2,3, for ex-
	      ample, triggers.

       remove(Name, FuncOrFuncId :: Func | FuncId) -> ok

       remove(Name, FuncOrFuncId :: Func | FuncId, Timeout) -> ok

	      Types:

		 Name =	name()
		 Func =	dbg_fun()
		 FuncId	= term()
		 Timeout = timeout()

	      Removes an installed debug function from the  process.  Func  or
	      FuncId must be the same as previously installed.

       replace_state(Name, StateFun) ->	NewState

       replace_state(Name, StateFun, Timeout) -> NewState

	      Types:

		 Name =	name()
		 StateFun = fun((State :: term()) -> NewState :: term())
		 Timeout = timeout()
		 NewState = term()

	      Replaces the state of the	process, and returns the new state.

	  Note:
	      These  functions	are  intended only to help with	debugging, and
	      are not to be called from	normal code.  They  are	 provided  for
	      convenience, allowing developers to avoid	having to create their
	      own custom state replacement functions.

	      Function StateFun	provides a new state for the process. Argument
	      State and	the NewState return value of StateFun vary for differ-
	      ent types	of processes as	follows:

		* For a	gen_server process, State is the state of the callback
		  module and NewState is a new instance	of that	state.

		* For	a   gen_statem	process,  State	 is  the  tuple	 {Cur-
		  rentState,CurrentData}, and NewState	is  a  similar	tuple,
		  which	 can  contain  a new current state, new	state data, or
		  both.

		* For a	gen_event process, State is  the  tuple	 {Module,  Id,
		  HandlerState}	as follows:

		  Module:
		    The	module name of the event handler.

		  Id:
		    The	ID of the handler (which is false if it	was registered
		    without an ID).

		  HandlerState:
		    The	state of the handler.

		  NewState is a	similar	tuple where Module and Id are to  have
		  the  same  values as in State, but the value of HandlerState
		  can be different. Returning a	NewState, whose	Module	or  Id
		  values  differ  from those of	State, leaves the state	of the
		  event	handler	unchanged. For a gen_event  process,  StateFun
		  is  called  once  for	 each  event handler registered	in the
		  gen_event process.

	      If a StateFun function decides  not  to  effect  any  change  in
	      process  state,  then  regardless	of process type, it can	return
	      its State	argument.

	      If a StateFun function crashes or	throws an exception, the orig-
	      inal  state  of  the  process  is	 unchanged for gen_server, and
	      gen_statem processes. For	gen_event  processes,  a  crashing  or
	      failing  StateFun	function means that only the state of the par-
	      ticular event handler it	was  working  on  when	it  failed  or
	      crashed  is  unchanged;  it  can	still  succeed in changing the
	      states of	other event handlers registered	in the same  gen_event
	      process.

	      If  the  callback	 module	exports	a system_replace_state/2 func-
	      tion, it is called in the	target process to  replace  its	 state
	      using  StateFun.	Its two	arguments are StateFun and Misc, where
	      Misc is the same as the Misc value returned by get_status/1,2. A
	      system_replace_state/2  function is expected to return {ok, New-
	      State, NewMisc}, where NewState is the new state of the callback
	      module,  obtained	by calling StateFun, and NewMisc is a possibly
	      new value	used to	replace	the original Misc  (required  as  Misc
	      often contains the state of the callback module within it).

	      If  the callback module does not export a	system_replace_state/2
	      function,	replace_state/2,3 assumes that Misc is	the  state  of
	      the  callback  module, passes it to StateFun and uses the	return
	      value as both the	new state and as the new value of Misc.

	      If the callback module's function	system_replace_state/2 crashes
	      or  throws  an  exception,  the  caller  exits with error	{call-
	      back_failed, {Module, system_replace_state},  {Class,  Reason}},
	      where  Module  is	 the name of the callback module and Class and
	      Reason indicate details of the exception.	If the callback	module
	      does  not	provide	a system_replace_state/2 function and StateFun
	      crashes or throws	an exception,  the  caller  exits  with	 error
	      {callback_failed,	StateFun, {Class, Reason}}.

	      Function system_replace_state/2 is primarily useful for user-de-
	      fined behaviors and modules  that	 implement  OTP	 special  pro-
	      cesses.  The  OTP	 behavior  modules gen_server, gen_statem, and
	      gen_event	export this function, so callback  modules  for	 those
	      behaviors	need not to supply their own.

       resume(Name) -> ok

       resume(Name, Timeout) ->	ok

	      Types:

		 Name =	name()
		 Timeout = timeout()

	      Resumes a	suspended process.

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

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

	      Types:

		 Name =	name()
		 Flag =	true | false | get
		 Statistics = [StatisticsTuple]	| no_statistics
		 StatisticsTuple =
		     {start_time, DateTime1} |
		     {current_time, DateTime2} |
		     {reductions, integer() >= 0} |
		     {messages_in, integer() >=	0} |
		     {messages_out, integer() >= 0}
		 DateTime1 = DateTime2 = file:date_time()
		 Timeout = timeout()

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

       suspend(Name) ->	ok

       suspend(Name, Timeout) -> ok

	      Types:

		 Name =	name()
		 Timeout = timeout()

	      Suspends the process. When the process is	suspended, it only re-
	      sponds to	other system messages, but not other messages.

       terminate(Name, Reason) -> ok

       terminate(Name, Reason, Timeout)	-> ok

	      Types:

		 Name =	name()
		 Reason	= term()
		 Timeout = timeout()

	      Orders  the  process to terminate	with the specified Reason. The
	      termination is done asynchronously, so it	is not guaranteed that
	      the process is terminated	when the function returns.

       trace(Name, Flag) -> ok

       trace(Name, Flag, Timeout) -> ok

	      Types:

		 Name =	name()
		 Flag =	boolean()
		 Timeout = timeout()

	      Prints  all system events	on standard_io.	The events are format-
	      ted with a function that is defined by the process  that	gener-
	      ated the event (with a call to handle_debug/4).

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

EXPORTS
       debug_options(Options) -> [dbg_opt()]

	      Types:

		 Options = [Opt]
		 Opt =
		     trace |
		     log |
		     {log, integer() >=	1} |
		     statistics	|
		     {log_to_file, FileName} |
		     {install, FuncSpec}
		 FileName = file:name()
		 FuncSpec = {Func, FuncState} |	{FuncId, Func, FuncState}
		 FuncId	= term()
		 Func =	dbg_fun()
		 FuncState = term()

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

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

	      Types:

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

	      Gets  the	 data  associated  with	a debug	option.	Default	is re-
	      turned if	Item is	not found. Can be used by the process  to  re-
	      trieve debug data	for printing before it terminates.

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

	      Types:

		 Debug = [dbg_opt()]
		 FormFunc = format_fun()
		 Extra = term()
		 Event = system_event()

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

       handle_system_msg(Msg, From, Parent, Module, Debug, Misc) ->
			    no_return()

	      Types:

		 Msg = term()
		 From =	{pid(),	Tag :: term()}
		 Parent	= pid()
		 Module	= module()
		 Debug = [dbg_opt()]
		 Misc =	term()

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

	      This function never returns. It calls either  of	the  following
	      functions:

		* Module:system_continue(Parent,   NDebug,  Misc),  where  the
		  process continues the	execution.

		* Module:system_terminate(Reason, Parent, Debug, Misc),	if the
		  process is to	terminate.

	      Module must export the following:

		* system_continue/3

		* system_terminate/4

		* system_code_change/4

		* system_get_state/1

		* system_replace_state/2

	      Argument	Misc  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)	-> ok

	      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.

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

	      Types:

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

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

       Module:system_continue(Parent, Debug, Misc) -> none()

	      Types:

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

	      Called from handle_system_msg/6 when the process is to  continue
	      its  execution  (for example, after it has been suspended). This
	      function never returns.

       Module:system_get_state(Misc) ->	{ok, State}

	      Types:

		 Misc =	term()
		 State = term()

	      Called from handle_system_msg/6 when the process is to return  a
	      term  that  reflects  its	 current state.	State is the value re-
	      turned by	get_state/2.

       Module:system_replace_state(StateFun, Misc) -> {ok, NState, NMisc}

	      Types:

		 StateFun = fun((State :: term()) -> NState)
		 Misc =	term()
		 NState	= term()
		 NMisc = term()

	      Called from handle_system_msg/6 when the process is  to  replace
	      its   current  state.  NState  is	 the  value  returned  by  re-
	      place_state/3.

       Module:system_terminate(Reason, Parent, Debug, Misc) -> none()

	      Types:

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

	      Called from handle_system_msg/6 when the process	is  to	termi-
	      nate.  For  example, this	function is called when	the process is
	      suspended	and its	parent orders shutdown.	It gives the process a
	      chance to	do a cleanup. This function never returns.

Ericsson AB			  stdlib 3.8				sys(3)

NAME | DESCRIPTION | SYSTEM MESSAGES | SYSTEM EVENTS | DATA TYPES | EXPORTS | PROCESS IMPLEMENTATION FUNCTIONS | EXPORTS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sys&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help