.TH int 3erl "debugger 4.2.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 primarily intended to be used by Debugger, see the User\&'s Guide and \fB\fIdebugger(3erl)\fR\&\fR\&\&.
.LP
The following can be done from the shell:
.RS 2
.TP 2
*
Specify the modules to 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 through a third process, called the meta process\&. You can implement your own attached process\&. See \fIint\&.erl\fR\& for available functions and \fIdbg_wx_trace\&.erl\fR\& for possible messages\&.
.LP
The interpreter depends on the Kernel, STDLIB, and GS applications\&. This means that 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\&.
.SH "BREAKPOINTS"

.LP
Breakpoints are specified on a line basis\&. When a process executing code in an interpreted module reaches a breakpoint, it stops\&. This means that a breakpoint must be set at an executable line, that is, a code line containing an executable expression\&.
.LP
A breakpoint has the following:
.RS 2
.TP 2
*
A status, which is \fIactive\fR\& or \fIinactive\fR\&\&. An inactive breakpoint is ignored\&.
.LP
.TP 2
*
A trigger action\&. When a breakpoint is reached, the trigger action specifies if the breakpoint is to continue as active (\fIenable\fR\&), or to become inactive (\fIdisable\fR\&), or to be removed (\fIdelete\fR\&)\&.
.LP
.TP 2
*
Optionally an associated condition\&. A condition is a tuple \fI{Module,Name}\fR\&\&. When the breakpoint is reached, \fIModule:Name(Bindings)\fR\& is called\&. If it evaluates to \fItrue\fR\&, execution stops\&. If it evaluates to \fIfalse\fR\&, the breakpoint is ignored\&. \fIBindings\fR\& contains the current variable bindings\&. To retrieve the value for a specified variable, use \fIget_binding\fR\&\&.
.LP
.RE

.LP
By default, a breakpoint is active, has trigger action \fIenable\fR\&, and has no associated condition\&. For details about breakpoints, see the 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 can be specified by its module name (atom) or filename\&.
.LP
If specified 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 an \fIsrc\fR\& directory next to it\&.
.LP
If specified by its filename, the filename can include a path and the \fI\&.erl\fR\& extension can 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 requires both the source code and the object code\&. The object code \fImust\fR\& include debug information, that is, only modules compiled with option \fIdebug_info\fR\& set can be interpreted\&.

.LP
The functions returns \fI{module,Module}\fR\& if the module was interpreted, otherwise \fIerror\fR\& is returned\&.
.LP
The argument can also be a list of modules or filenames, in which case the function tries to interpret each module as specified earlier\&. The function then always returns \fIok\fR\&, but prints some information to \fIstdout\fR\& if a module cannot 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 can be specified by its module name or filename\&.
.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 filename \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 can be interpreted\&. The module can be specified by its module name \fIModule\fR\& or its source filename \fIFile\fR\&\&. If specified by a module name, the module is searched for in the code path\&.
.LP
The function returns \fItrue\fR\& if all of the following apply:
.RS 2
.TP 2
*
Both source code and object code for the module is found\&.
.LP
.TP 2
*
The module has been compiled with option \fIdebug_info\fR\& set\&.
.LP
.TP 2
*
The module does not belong to any of the applications Kernel, STDLIB, GS, or Debugger\&.
.LP
.RE

.LP
The function returns \fI{error,Reason}\fR\& if the module cannot be interpreted\&. \fIReason\fR\& can have the following values:
.RS 2
.TP 2
.B
\fIno_src\fR\&:
No source code is found\&. It is assumed that the source code and object code are located either in the same directory, or in \fIsrc\fR\& and \fIebin\fR\& directories next to each other\&.
.TP 2
.B
\fIno_beam\fR\&:
No object code is found\&. It is assumed that the source code and object code are located either in the same directory, or in \fIsrc\fR\& and \fIebin\fR\& directories next to each other\&.
.TP 2
.B
\fIno_debug_info\fR\&:
The module has not been compiled with option \fIdebug_info\fR\& set\&.
.TP 2
.B
\fIbadarg\fR\&:
\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 filename, which is the case not only for non-existing modules but also for modules that are preloaded or cover-compiled\&.
.TP 2
.B
\fI{app,App}\fR\&:
\fIApp\fR\& is \fIkernel\fR\&, \fIstdlib\fR\&, \fIgs\fR\&, or \fIdebugger\fR\& if \fIAbsModule\fR\& belongs to one of these applications\&.
.RE
.LP
Notice that the function can return \fItrue\fR\& for a module that in fact is not interpretable in the case where the module is marked as sticky or resides in a directory marked as sticky\&. The reason is that this is not discovered until the interpreter 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 attach automatically to a process executing code in interpreted modules\&. \fIfalse\fR\& means never attach automatically, this is the default\&. Otherwise automatic attach is defined by a list of flags and a function\&. The following flags can be specified:
.RS 2
.TP 2
*
\fIinit\fR\& - Attach when a process for the 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\& is 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\&. The following flags can be specified:
.RS 2
.TP 2
.B
\fIall\fR\&:
Save information about all current calls, that is, function calls that have not yet returned a value\&.
.TP 2
.B
\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 can be necessary to use for processes with long lifetimes and many tail recursive calls\&. This is the default\&.
.TP 2
.B
\fIfalse\fR\&:
Save no information about currentcalls\&.
.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 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 function \fIModule:Name/Arity\fR\&\&.
.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 function \fIModule:Name/Arity\fR\&\&.
.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 section \fBBreakpoints\fR\&\&.
.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\& - More information\&.
.LP
.RE

.LP
\fIStatus\fR\& is one of the following:
.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 is stopped, normally at a breakpoint\&. \fIInfo={Module,Line}\fR\&\&.
.LP
.TP 2
*
\fIexit\fR\& - The process is 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
Resumes process execution for \fIPid\fR\& or \fIc:pid(X,Y,Z)\fR\&\&.
.RE