.TH int 3erl "debugger 4.0.1" "Ericsson AB" "Erlang Module Definition"
.SH NAME
int \- Interpreter Interface
.SH DESCRIPTION
.LP
The Erlang interpreter provides mechanisms for breakpoints and stepwise execution of code\&. It is mainly intended to be used by the \fIDebugger\fR\&, see Debugger User\&'s Guide and \fIdebugger(3erl)\fR\&\&.
.LP
From the shell, it is possible to:
.RS 2
.TP 2
*
Specify which modules should be interpreted\&.
.LP
.TP 2
*
Specify breakpoints\&.
.LP
.TP 2
*
Monitor the current status of all processes executing code in interpreted modules, also processes at other Erlang nodes\&. 
.LP
.RE

.LP
By \fIattaching to\fR\& 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 \fIint\&.erl\fR\& for available functions and \fIdbg_ui_trace\&.erl\fR\& for possible messages\&.
.LP
The interpreter depends on the Kernel, STDLIB and GS applications, which means modules belonging to any of these applications are not allowed to be interpreted as it could lead to a deadlock or emulator crash\&. This also applies to modules belonging to the Debugger application itself\&.
.SH "BREAKPOINTS"

.LP
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\&.
.LP
A breakpoint have a status, a trigger action and may have a condition associated with it\&. The status is either \fIactive\fR\& or \fIinactive\fR\&\&. An inactive breakpoint is ignored\&. When a breakpoint is reached, the trigger action specifies if the breakpoint should continue to be active (\fIenable\fR\&), if it should become inactive (\fIdisable\fR\&), or if it should be removed (\fIdelete\fR\&)\&. A condition is a tuple \fI{Module,Name}\fR\&\&. When the breakpoint is reached, \fIModule:Name(Bindings)\fR\& is called\&. If this evaluates to \fItrue\fR\&, execution will stop\&. If this evaluates to \fIfalse\fR\&, the breakpoint is ignored\&. \fIBindings\fR\& contains the current variable bindings, use \fIget_binding\fR\& to retrieve the value for a given variable\&.
.LP
By default, a breakpoint is active, has trigger action \fIenable\fR\& and has no condition associated with it\&. For more detailed information about breakpoints, refer to Debugger User\&'s Guide\&.
.SH EXPORTS
.LP
.B
i(AbsModule) -> {module,Module} | error
.br
.B
i(AbsModules) -> ok
.br
.B
ni(AbsModule) -> {module,Module} | error
.br
.B
ni(AbsModules) -> ok
.br
.RS
.LP
Types:

.RS 3
AbsModules = [AbsModule]
.br
AbsModule = Module | File | [Module | File]
.br
 Module = atom()
.br
 File = string()
.br
.RE
.RE
.RS
.LP
Interprets the specified module(s)\&. \fIi/1\fR\& interprets the module only at the current node\&. \fIni/1\fR\& interprets the module at all known nodes\&.
.LP
A module may be given by its module name (atom) or by its file name\&. If given by its module name, the object code \fIModule\&.beam\fR\& is searched for in the current path\&. The source code \fIModule\&.erl\fR\& is searched for first in the same directory as the object code, then in a \fIsrc\fR\& directory next to it\&.
.LP
If given by its file name, the file name may include a path and the \fI\&.erl\fR\& extension may be omitted\&. The object code \fIModule\&.beam\fR\& is searched for first in the same directory as the source code, then in an \fIebin\fR\& directory next to it, and then in the current path\&.
.LP

.RS -4
.B
Note:
.RE
The interpreter needs both the source code and the object code, and the object code \fImust\fR\& include debug information\&. That is, only modules compiled with the option \fIdebug_info\fR\& set can be interpreted\&.

.LP
The functions returns \fI{module,Module}\fR\& if the module was interpreted, or \fIerror\fR\& if it was not\&.
.LP
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 \fIok\fR\&, but prints some information to stdout if a module could not be interpreted\&.
.RE

.LP
.B
n(AbsModule) -> ok
.br
.B
nn(AbsModule) -> ok
.br
.RS
.LP
Types:

.RS 3
AbsModule = Module | File | [Module | File]
.br
 Module = atom()
.br
 File = string()
.br
.RE
.RE
.RS
.LP
Stops interpreting the specified module\&. \fIn/1\fR\& stops interpreting the module only at the current node\&. \fInn/1\fR\& stops interpreting the module at all known nodes\&.
.LP
As for \fIi/1\fR\& and \fIni/1\fR\&, a module may be given by either its module name or its file name\&.
.RE

.LP
.B
interpreted() -> [Module]
.br
.RS
.LP
Types:

.RS 3
Module = atom()
.br
.RE
.RE
.RS
.LP
Returns a list with all interpreted modules\&.
.RE

.LP
.B
file(Module) -> File | {error,not_loaded}
.br
.RS
.LP
Types:

.RS 3
Module = atom()
.br
File = string()
.br
.RE
.RE
.RS
.LP
Returns the source code file name \fIFile\fR\& for an interpreted module \fIModule\fR\&\&.
.RE

.LP
.B
interpretable(AbsModule) -> true | {error,Reason}
.br
.RS
.LP
Types:

.RS 3
AbsModule = Module | File
.br
 Module = atom()
.br
 File = string()
.br
Reason = no_src | no_beam | no_debug_info | badarg | {app,App}
.br
 App = atom()
.br
.RE
.RE
.RS
.LP
Checks if a module is possible to interpret\&. The module can be given by its module name \fIModule\fR\& or its source file name \fIFile\fR\&\&. If given by a module name, the module is searched for in the code path\&.
.LP
The function returns \fItrue\fR\& if both source code and object code for the module is found, the module has been compiled with the option \fIdebug_info\fR\& set and does not belong to any of the applications Kernel, STDLIB, GS or Debugger itself\&.
.LP
The function returns \fI{error,Reason}\fR\& if the module for some reason is not possible to interpret\&.
.LP
\fIReason\fR\& is \fIno_src\fR\& if no source code is found or \fIno_beam\fR\& if no object code is found\&. It is assumed that the source- and object code are located either in the same directory, or in \fIsrc\fR\& and \fIebin\fR\& directories next to each other\&.
.LP
\fIReason\fR\& is \fIno_debug_info\fR\& if the module has not been compiled with the option \fIdebug_info\fR\& set\&.
.LP
\fIReason\fR\& is \fIbadarg\fR\& if \fIAbsModule\fR\& is not found\&. This could be because the specified file does not exist, or because \fIcode:which/1\fR\& 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\&.
.LP
\fIReason\fR\& is \fI{app,App}\fR\& where \fIApp\fR\& is \fIkernel\fR\&, \fIstdlib\fR\&, \fIgs\fR\& or \fIdebugger\fR\& if \fIAbsModule\fR\& belongs to one of these applications\&.
.LP
Note that the function can return \fItrue\fR\& 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\&.
.RE

.LP
.B
auto_attach() -> false | {Flags,Function}
.br
.B
auto_attach(false)
.br
.B
auto_attach(Flags, Function)
.br
.RS
.LP
Types:

.RS 3
Flags = [init | break | exit]
.br
Function = {Module,Name,Args}
.br
 Module = Name = atom()
.br
 Args = [term()]
.br
.RE
.RE
.RS
.LP
Gets and sets when and how to automatically attach to a process executing code in interpreted modules\&. \fIfalse\fR\& means never automatically attach, this is the default\&. Otherwise automatic attach is defined by a list of flags and a function\&. The following flags may be specified:
.RS 2
.TP 2
*
\fIinit\fR\& - attach when a process for the very first time calls an interpreted function\&.
.LP
.TP 2
*
\fIbreak\fR\& - attach whenever a process reaches a breakpoint\&.
.LP
.TP 2
*
\fIexit\fR\& - attach when a process terminates\&.
.LP
.RE

.LP
When the specified event occurs, the function \fIFunction\fR\& will be called as:
.LP
.nf

spawn(Module, Name, [Pid | Args])
	
.fi
.LP
\fIPid\fR\& is the pid of the process executing interpreted code\&.
.RE

.LP
.B
stack_trace() -> Flag
.br
.B
stack_trace(Flag)
.br
.RS
.LP
Types:

.RS 3
Flag = all | no_tail | false
.br
.RE
.RE
.RS
.LP
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 exception of class error) occurs\&.
.RS 2
.TP 2
*
\fIall\fR\& - save information about all current calls, that is, function calls that have not yet returned a value\&. 
.LP
.TP 2
*
\fIno_tail\fR\& - 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\&.
.LP
.TP 2
*
\fIfalse\fR\& - do not save any information about current calls\&.
.LP
.RE

.RE

.LP
.B
break(Module, Line) -> ok | {error,break_exists}
.br
.RS
.LP
Types:

.RS 3
Module = atom()
.br
Line = int()
.br
.RE
.RE
.RS
.LP
Creates a breakpoint at \fILine\fR\& in \fIModule\fR\&\&.
.RE

.LP
.B
delete_break(Module, Line) -> ok
.br
.RS
.LP
Types:

.RS 3
Module = atom()
.br
Line = int()
.br
.RE
.RE
.RS
.LP
Deletes the breakpoint located at \fILine\fR\& in \fIModule\fR\&\&.
.RE

.LP
.B
break_in(Module, Name, Arity) -> ok | {error,function_not_found}
.br
.RS
.LP
Types:

.RS 3
Module = Name = atom()
.br
Arity = int()
.br
.RE
.RE
.RS
.LP
Creates a breakpoint at the first line of every clause of the \fIModule:Name/Arity\fR\& function\&.
.RE

.LP
.B
del_break_in(Module, Name, Arity) -> ok | {error,function_not_found}
.br
.RS
.LP
Types:

.RS 3
Module = Name = atom()
.br
Arity = int()
.br
.RE
.RE
.RS
.LP
Deletes the breakpoints at the first line of every clause of the \fIModule:Name/Arity\fR\& function\&.
.RE

.LP
.B
no_break() -> ok
.br
.B
no_break(Module) -> ok
.br
.RS
.LP
Deletes all breakpoints, or all breakpoints in \fIModule\fR\&\&.
.RE

.LP
.B
disable_break(Module, Line) -> ok
.br
.RS
.LP
Types:

.RS 3
Module = atom()
.br
Line = int()
.br
.RE
.RE
.RS
.LP
Makes the breakpoint at \fILine\fR\& in \fIModule\fR\& inactive\&.
.RE

.LP
.B
enable_break(Module, Line) -> ok
.br
.RS
.LP
Types:

.RS 3
Module = atom()
.br
Line = int()
.br
.RE
.RE
.RS
.LP
Makes the breakpoint at \fILine\fR\& in \fIModule\fR\& active\&.
.RE

.LP
.B
action_at_break(Module, Line, Action) -> ok
.br
.RS
.LP
Types:

.RS 3
Module = atom()
.br
Line = int()
.br
Action = enable | disable | delete
.br
.RE
.RE
.RS
.LP
Sets the trigger action of the breakpoint at \fILine\fR\& in \fIModule\fR\& to \fIAction\fR\&\&.
.RE

.LP
.B
test_at_break(Module, Line, Function) -> ok
.br
.RS
.LP
Types:

.RS 3
Module = atom()
.br
Line = int()
.br
Function = {Module,Name}
.br
 Name = atom()
.br
.RE
.RE
.RS
.LP
Sets the conditional test of the breakpoint at \fILine\fR\& in \fIModule\fR\& to \fIFunction\fR\&\&. The function must fulfill the requirements specified in the section \fIBreakpoints\fR\& above\&.
.RE

.LP
.B
get_binding(Var, Bindings) -> {value,Value} | unbound
.br
.RS
.LP
Types:

.RS 3
Var = atom()
.br
Bindings = term()
.br
Value = term()
.br
.RE
.RE
.RS
.LP
Retrieves the binding of \fIVar\fR\&\&. This function is intended to be used by the conditional function of a breakpoint\&.
.RE

.LP
.B
all_breaks() -> [Break]
.br
.B
all_breaks(Module) -> [Break]
.br
.RS
.LP
Types:

.RS 3
Break = {Point,Options}
.br
 Point = {Module,Line}
.br
 Module = atom()
.br
 Line = int()
.br
 Options = [Status,Trigger,null,Cond|]
.br
 Status = active | inactive
.br
 Trigger = enable | disable | delete
.br
 Cond = null | Function
.br
 Function = {Module,Name}
.br
 Name = atom()
.br
.RE
.RE
.RS
.LP
Gets all breakpoints, or all breakpoints in \fIModule\fR\&\&.
.RE

.LP
.B
snapshot() -> [Snapshot]
.br
.RS
.LP
Types:

.RS 3
Snapshot = {Pid, Function, Status, Info}
.br
 Pid = pid()
.br
 Function = {Module,Name,Args}
.br
 Module = Name = atom()
.br
 Args = [term()]
.br
 Status = idle | running | waiting | break | exit | no_conn
.br
 Info = {} | {Module,Line} | ExitReason
.br
 Line = int()
.br
 ExitReason = term()
.br
.RE
.RE
.RS
.LP
Gets information about all processes executing interpreted code\&.
.RS 2
.TP 2
*
\fIPid\fR\& - process identifier\&.
.LP
.TP 2
*
\fIFunction\fR\& - first interpreted function called by the process\&.
.LP
.TP 2
*
\fIStatus\fR\& - current status of the process\&.
.LP
.TP 2
*
\fIInfo\fR\& - additional information\&.
.LP
.RE

.LP
\fIStatus\fR\& is one of:
.RS 2
.TP 2
*
\fIidle\fR\& - the process is no longer executing interpreted code\&. \fIInfo={}\fR\&\&.
.LP
.TP 2
*
\fIrunning\fR\& - the process is running\&. \fIInfo={}\fR\&\&. 
.LP
.TP 2
*
\fIwaiting\fR\& - the process is waiting at a \fIreceive\fR\&\&. \fIInfo={}\fR\&\&.
.LP
.TP 2
*
\fIbreak\fR\& - process execution has been stopped, normally at a breakpoint\&. \fIInfo={Module,Line}\fR\&\&.
.LP
.TP 2
*
\fIexit\fR\& - the process has terminated\&. \fIInfo=ExitReason\fR\&\&.
.LP
.TP 2
*
\fIno_conn\fR\& - the connection is down to the node where the process is running\&. \fIInfo={}\fR\&\&.
.LP
.RE

.RE

.LP
.B
clear() -> ok
.br
.RS
.LP
Clears information about processes executing interpreted code by removing all information about terminated processes\&.
.RE

.LP
.B
continue(Pid) -> ok | {error,not_interpreted}
.br
.B
continue(X,Y,Z) -> ok | {error,not_interpreted}
.br
.RS
.LP
Types:

.RS 3
Pid = pid()
.br
X = Y = Z = int()
.br
.RE
.RE
.RS
.LP
Resume process execution for \fIPid\fR\&, or for \fIc:pid(X,Y,Z)\fR\&\&.
.RE