.TH int 3 "debugger  3.1.1.3" "Ericsson AB" "ERLANG MODULE DEFINITION"
.SH MODULE
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(3)\fR\&.
.LP
From the shell, it is possible to:
.RS 2
.TP 2
*
Specify which modules should be interpreted\&.
.TP 2
*
Specify breakpoints\&.
.TP 2
*
Monitor the current status of all processes executing code in interpreted modules, also processes at other Erlang nodes\&.
.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
.TP
Types
AbsModules = [AbsModule]
.br
AbsModule = Module | File | [Module | File]
.br
Module = atom()
.br
File = string()
.br
.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\&.
.SS Note:
.LP
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
.TP
Types
AbsModule = Module | File | [Module | File]
.br
Module = atom()
.br
File = string()
.br
.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
.TP
Types
Module = atom()
.br
.RE
.RS
.LP
Returns a list with all interpreted modules\&.
.RE
.LP
.B
file(Module) -> File | {error,not_loaded}
.br
.RS
.TP
Types
Module = atom()
.br
File = string()
.br
.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
.TP
Types
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
.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
.TP
Types
Flags = [init | break | exit]
.br
Function = {Module, Name, Args}
.br
Module = Name = atom()
.br
Args = [term()]
.br
.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\&.
.TP 2
*
\fIbreak\fR - attach whenever a process reaches a breakpoint\&.
.TP 2
*
\fIexit\fR - attach when a process terminates\&.
.RE
.LP
When the specified event occurs, the function \fIFunction\fR will be called as:

.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
.TP
Types
Flag = all | no_tail | false
.br
.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\&. This is the default\&.
.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\&.
.TP 2
*
\fIfalse\fR - do not save any information about current calls\&.
.RE
.RE
.LP
.B
break(Module, Line) -> ok | {error,break_exists}
.br
.RS
.TP
Types
Module = atom()
.br
Line = int()
.br
.RE
.RS
.LP
Creates a breakpoint at \fILine\fR in \fIModule\fR\&.
.RE
.LP
.B
delete_break(Module, Line) -> ok
.br
.RS
.TP
Types
Module = atom()
.br
Line = int()
.br
.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
.TP
Types
Module = Name = atom()
.br
Arity = int()
.br
.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
.TP
Types
Module = Name = atom()
.br
Arity = int()
.br
.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
.TP
Types
Module = atom()
.br
Line = int()
.br
.RE
.RS
.LP
Makes the breakpoint at \fILine\fR in \fIModule\fR inactive\&.
.RE
.LP
.B
enable_break(Module, Line) -> ok
.br
.RS
.TP
Types
Module = atom()
.br
Line = int()
.br
.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
.TP
Types
Module = atom()
.br
Line = int()
.br
Action = enable | disable | delete
.br
.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
.TP
Types
Module = atom()
.br
Line = int()
.br
Function = {Module, Name}
.br
Name = atom()
.br
.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
.TP
Types
Var = atom()
.br
Bindings = term()
.br
Value = term()
.br
.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
.TP
Types
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
.RS
.LP
Gets all breakpoints, or all breakpoints in \fIModule\fR\&. 
.RE
.LP
.B
snapshot() -> [Snapshot]
.br
.RS
.TP
Types
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
.RS
.LP
Gets information about all processes executing interpreted code\&. 
.RS 2
.TP 2
*
\fIPid\fR - process identifier\&.
.TP 2
*
\fIFunction\fR - first interpreted function called by the process\&.
.TP 2
*
\fIStatus\fR - current status of the process\&.
.TP 2
*
\fIInfo\fR - additional information\&.
.RE
.LP
\fIStatus\fR is one of:
.RS 2
.TP 2
*
\fIidle\fR - the process is no longer executing interpreted code\&. \fIInfo={}\fR\&.
.TP 2
*
\fIrunning\fR - the process is running\&. \fIInfo={}\fR\&.
.TP 2
*
\fIwaiting\fR - the process is waiting at a \fIreceive\fR\&. \fIInfo={}\fR\&.
.TP 2
*
\fIbreak\fR - process execution has been stopped, normally at a breakpoint\&. \fIInfo={Module, Line}\fR\&.
.TP 2
*
\fIexit\fR - the process has terminated\&. \fIInfo=ExitReason\fR\&.
.TP 2
*
\fIno_conn\fR - the connection is down to the node where the process is running\&. \fIInfo={}\fR\&.
.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
.TP
Types
Pid = pid()
.br
X = Y = Z = int()
.br
.RE
.RS
.LP
Resume process execution for \fIPid\fR, or for \fIc:pid(X, Y, Z)\fR\&.
.RE