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

FreeBSD Manual Pages

  
 
  

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

NAME
       int - Interpreter Interface

DESCRIPTION
       The Erlang interpreter provides mechanisms for breakpoints and stepwise
       execution of code. It is	mainly intended	to be used  by	the  Debugger,
       see Debugger User's Guide and debugger(3).

       From the	shell, it is possible to:

	 * Specify which modules should	be interpreted.

	 * Specify breakpoints.

	 * Monitor  the	 current status	of all processes executing code	in in-
	   terpreted modules, also processes at	other Erlang nodes.

       By attaching to a process executing interpreted code, it	is possible to
       examine variable	bindings and order stepwise execution. This is done by
       sending and receiving information  to/from  the	process	 via  a	 third
       process,	 called	the meta process. It is	possible to implement your own
       attached	  process.   See   int.erl   for   available   functions   and
       dbg_wx_trace.erl	for possible messages.

       The  interpreter	 depends  on  the  Kernel, STDLIB and GS applications,
       which means modules belonging to	any of these applications are not  al-
       lowed  to  be  interpreted  as  it could	lead to	a deadlock or emulator
       crash. This also	applies	to modules belonging to	the Debugger  applica-
       tion itself.

BREAKPOINTS
       Breakpoints  are	 specified  on	a line basis. When a process executing
       code in an interpreted module reaches a breakpoint, it will stop.  This
       means  that  that  a breakpoint must be set at an executable line, that
       is, a line of code containing an	executable expression.

       A breakpoint have a status, a trigger action and	may have  a  condition
       associated  with	 it. The status	is either active or inactive. An inac-
       tive breakpoint is ignored. When	a breakpoint is	reached,  the  trigger
       action  specifies  if  the breakpoint should continue to	be active (en-
       able), if it should become inactive (disable), or if it should  be  re-
       moved  (delete).	 A condition is	a tuple	{Module,Name}. When the	break-
       point is	reached, Module:Name(Bindings) is called. If this evaluates to
       true,  execution	 will stop. If this evaluates to false,	the breakpoint
       is ignored.  Bindings  contains	the  current  variable	bindings,  use
       get_binding to retrieve the value for a given variable.

       By  default,  a breakpoint is active, has trigger action	enable and has
       no condition associated with it.	For more  detailed  information	 about
       breakpoints, refer to Debugger User's Guide.

EXPORTS
       i(AbsModule) -> {module,Module} | error
       i(AbsModules) ->	ok
       ni(AbsModule) ->	{module,Module}	| error
       ni(AbsModules) -> ok

	      Types:

		 AbsModules = [AbsModule]
		 AbsModule = Module | File | [Module | File]
		  Module = atom()
		  File = string()

	      Interprets  the  specified  module(s). i/1 interprets the	module
	      only at the current node.	ni/1  interprets  the  module  at  all
	      known nodes.

	      A	 module	 may be	given by its module name (atom)	or by its file
	      name. If given by	its module name, the object  code  Module.beam
	      is  searched for in the current path. The	source code Module.erl
	      is searched for first in the same	directory as the object	 code,
	      then in a	src directory next to it.

	      If  given	by its file name, the file name	may include a path and
	      the .erl extension may be	omitted. The object  code  Module.beam
	      is  searched for first in	the same directory as the source code,
	      then in an ebin directory	next to	it, and	then  in  the  current
	      path.

	  Note:
	      The  interpreter needs both the source code and the object code,
	      and the object code must include	debug  information.  That  is,
	      only  modules compiled with the option debug_info	set can	be in-
	      terpreted.

	      The functions returns {module,Module} if the module  was	inter-
	      preted, or error if it was not.

	      The  argument may	also be	a list of modules/file names, in which
	      case the function	tries to interpret each	 module	 as  specified
	      above.  The function then	always returns ok, but prints some in-
	      formation	to stdout if a module could not	be interpreted.

       n(AbsModule) -> ok
       nn(AbsModule) ->	ok

	      Types:

		 AbsModule = Module | File | [Module | File]
		  Module = atom()
		  File = string()

	      Stops interpreting the specified module. n/1 stops  interpreting
	      the module only at the current node. nn/1	stops interpreting the
	      module at	all known nodes.

	      As for i/1 and ni/1, a module may	be given by either its	module
	      name or its file name.

       interpreted() ->	[Module]

	      Types:

		 Module	= atom()

	      Returns a	list with all interpreted modules.

       file(Module) -> File | {error,not_loaded}

	      Types:

		 Module	= atom()
		 File =	string()

	      Returns the source code file name	File for an interpreted	module
	      Module.

       interpretable(AbsModule)	-> true	| {error,Reason}

	      Types:

		 AbsModule = Module | File
		  Module = atom()
		  File = string()
		 Reason	 =  no_src  |  no_beam	|  no_debug_info  |  badarg  |
		 {app,App}
		  App =	atom()

	      Checks  if  a module is possible to interpret. The module	can be
	      given by its module name Module or its source file name File. If
	      given  by	 a module name,	the module is searched for in the code
	      path.

	      The function returns true	if both	source code  and  object  code
	      for  the	module is found, the module has	been compiled with the
	      option debug_info	set and	does not belong	to any of the applica-
	      tions Kernel, STDLIB, GS or Debugger itself.

	      The  function returns {error,Reason} if the module for some rea-
	      son is not possible to interpret.

	      Reason is	no_src if no source code is found or no_beam if	no ob-
	      ject  code  is  found. It	is assumed that	the source- and	object
	      code are located either in the same directory,  or  in  src  and
	      ebin directories next to each other.

	      Reason is	no_debug_info if the module has	not been compiled with
	      the option debug_info set.

	      Reason is	badarg if AbsModule is not found. This	could  be  be-
	      cause the	specified file does not	exist, or because code:which/1
	      does not return a	beam file name,	which is the case not only for
	      non-existing modules but also for	modules	which are preloaded or
	      cover compiled.

	      Reason is	{app,App} where	App is kernel, stdlib, gs or  debugger
	      if AbsModule belongs to one of these applications.

	      Note  that  the  function	 can return true for a module which in
	      fact is not interpretable	in the case where the module is	marked
	      as sticky	or resides in a	directory marked as sticky, as this is
	      not discovered until the interpreter actually tries to load  the
	      module.

       auto_attach() ->	false |	{Flags,Function}
       auto_attach(false)
       auto_attach(Flags, Function)

	      Types:

		 Flags = [init | break | exit]
		 Function = {Module,Name,Args}
		  Module = Name	= atom()
		  Args = [term()]

	      Gets  and	sets when and how to automatically attach to a process
	      executing	code in	interpreted modules. false means  never	 auto-
	      matically	 attach,  this is the default. Otherwise automatic at-
	      tach is defined by a list	of flags and a function. The following
	      flags may	be specified:

		* init	-  attach when a process for the very first time calls
		  an interpreted function.

		* break	- attach whenever a process reaches a breakpoint.

		* exit - attach	when a process terminates.

	      When the specified event occurs, the function Function  will  be
	      called as:

	      spawn(Module, Name, [Pid | Args])

	      Pid is the pid of	the process executing interpreted code.

       stack_trace() ->	Flag
       stack_trace(Flag)

	      Types:

		 Flag =	all | no_tail |	false

	      Gets  and	sets how to save call frames in	the stack. Saving call
	      frames makes it possible to inspect the call chain of a process,
	      and  is also used	to emulate the stack trace if an error (an ex-
	      ception of class error) occurs.

		* all -	save information about all  current  calls,  that  is,
		  function calls that have not yet returned a value.

		* no_tail  - save information about current calls, but discard
		  previous information when a tail  recursive  call  is	 made.
		  This option consumes less memory and may be necessary	to use
		  for processes	with long lifetimes and	 many  tail  recursive
		  calls. This is the default.

		* false	- do not save any information about current calls.

       break(Module, Line) -> ok | {error,break_exists}

	      Types:

		 Module	= atom()
		 Line =	int()

	      Creates a	breakpoint at Line in Module.

       delete_break(Module, Line) -> ok

	      Types:

		 Module	= atom()
		 Line =	int()

	      Deletes the breakpoint located at	Line in	Module.

       break_in(Module,	Name, Arity) ->	ok | {error,function_not_found}

	      Types:

		 Module	= Name = atom()
		 Arity = int()

	      Creates  a  breakpoint  at the first line	of every clause	of the
	      Module:Name/Arity	function.

       del_break_in(Module, Name, Arity) -> ok | {error,function_not_found}

	      Types:

		 Module	= Name = atom()
		 Arity = int()

	      Deletes the breakpoints at the first line	of every clause	of the
	      Module:Name/Arity	function.

       no_break() -> ok
       no_break(Module)	-> ok

	      Deletes all breakpoints, or all breakpoints in Module.

       disable_break(Module, Line) -> ok

	      Types:

		 Module	= atom()
		 Line =	int()

	      Makes the	breakpoint at Line in Module inactive.

       enable_break(Module, Line) -> ok

	      Types:

		 Module	= atom()
		 Line =	int()

	      Makes the	breakpoint at Line in Module active.

       action_at_break(Module, Line, Action) ->	ok

	      Types:

		 Module	= atom()
		 Line =	int()
		 Action	= enable | disable | delete

	      Sets  the	 trigger action	of the breakpoint at Line in Module to
	      Action.

       test_at_break(Module, Line, Function) ->	ok

	      Types:

		 Module	= atom()
		 Line =	int()
		 Function = {Module,Name}
		  Name = atom()

	      Sets the conditional test	of the breakpoint at Line in Module to
	      Function.	 The  function must fulfill the	requirements specified
	      in the section Breakpoints above.

       get_binding(Var,	Bindings) -> {value,Value} | unbound

	      Types:

		 Var = atom()
		 Bindings = term()
		 Value = term()

	      Retrieves	the binding of Var. This function is  intended	to  be
	      used by the conditional function of a breakpoint.

       all_breaks() -> [Break]
       all_breaks(Module) -> [Break]

	      Types:

		 Break = {Point,Options}
		  Point	= {Module,Line}
		  Module = atom()
		  Line = int()
		  Options = [Status,Trigger,null,Cond|]
		  Status = active | inactive
		  Trigger = enable | disable | delete
		  Cond = null |	Function
		  Function = {Module,Name}
		  Name = atom()

	      Gets all breakpoints, or all breakpoints in Module.

       snapshot() -> [Snapshot]

	      Types:

		 Snapshot = {Pid, Function, Status, Info}
		  Pid =	pid()
		  Function = {Module,Name,Args}
		  Module = Name	= atom()
		  Args = [term()]
		  Status = idle	| running | waiting | break | exit | no_conn
		  Info = {} | {Module,Line} | ExitReason
		  Line = int()
		  ExitReason = term()

	      Gets information about all processes executing interpreted code.

		* Pid -	process	identifier.

		* Function - first interpreted function	called by the process.

		* Status - current status of the process.

		* Info - additional information.

	      Status is	one of:

		* idle	- the process is no longer executing interpreted code.
		  Info={}.

		* running - the	process	is running. Info={}.

		* waiting - the	process	is waiting at a	receive. Info={}.

		* break	- process execution has	been stopped,  normally	 at  a
		  breakpoint. Info={Module,Line}.

		* exit - the process has terminated. Info=ExitReason.

		* no_conn  -  the  connection  is  down	 to the	node where the
		  process is running. Info={}.

       clear() -> ok

	      Clears information about processes executing interpreted code by
	      removing all information about terminated	processes.

       continue(Pid) ->	ok | {error,not_interpreted}
       continue(X,Y,Z) -> ok | {error,not_interpreted}

	      Types:

		 Pid = pid()
		 X = Y = Z = int()

	      Resume process execution for Pid,	or for c:pid(X,Y,Z).

Ericsson AB			debugger 4.0.3				int(3)

NAME | DESCRIPTION | BREAKPOINTS | EXPORTS

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

home | help