int

MODULE

int

MODULE SUMMARY

Interpreter (Debugger) Interface.

DESCRIPTION

The module int provides an interface for the Erlang interpreter (debugger). The graphical interface can be opened, but there are also commands available for interacting with the interpreter from the Erlang shell.

The purpose of the interpreter is to provide mechanisms which makes it possible to monitor what is going on while processes execute specified modules, or when processes crash.

The following features are provided to assist the user to catch bugs:

        o Specify which module(s) to be interpreted.

        o Make processes stop on specified break points.

        o Examine what has happened when a process has
          stopped, or crashed, by means of process attachment.
          This includes inspecting variable bindings.

        o Change processes, so that you can experiment
          by correcting the effects of one bug and proceed to
          the next one.

        o Single step the execution.

        o Monitor the current status of all interpreted
          processes. Processes spread over several Erlang 
          nodes can all be monitored and attached.
    

If a network of Erlang nodes, break points are always updated on all nodes.

EXPORTS

m() -> pid()

Starts a new graphical monitor. This is the main window of the interpreter. All interpreter functionality is accessed from the monitor window. The monitor window displays the status of all processes that are running interpreted modules.

i(AbsModule) -> {module, Module} | error

Types:
AbsModule = atom() | string() | [atom() | string()]
Module = atom()

Marks Module as being interpreted. The Module parameter can either be a single module name, or a list of module names. Module is compiled into an abstract form which is loaded into the interpreter. The actual paths are searched for the corresponding source file(s) (Module.erl). Module can be given with an absolute path.

If Module is a list of modules, the result of the last module is returned.

If an interpreted module is compiled using the c:c function, this module is reloaded into the interpreter.

i(AbsModule,Options) -> {module, Module} | error

Types:
AbsModule = atom() | string() | [atom() | string()]
Module = atom()
Options = [opt()]
opt() = verbose | {i,dir()} | {d,macro()} | {d,macro(),term()}
dir() = string()
macro() = atom()

As above, but verbose information is given in Options is one of:

verbose

Print verbose information.


{i,Dir}

Add Dir to the list of directories to be searched when including a file.


{d,Macro}

{d,Macro,Value}

Defines a macro Macro to have the value Value. The default is true).

a(AbsModule) -> {module, Module} | error

Types:
AbsModule = atom() | string() | [atom() | string()]
Module = atom()

Obsolete function. It has the same functionality as int:i/1.

a(AbsModule,Options) -> {module, Module} | error

Types:
AbsModule = atom() | string() | [atom() | string()]
Module = atom()
Options = [opt()]
opt() = verbose | {i,dir()} | {d,macro()} | {d,macro(),term()}
dir() = string()
macro() = atom()

Obsolete function. It has the same functionality as int:i/2.

n(Module) -> ok

Types:
Module = atom() | string() | [atom() | string()]

Does not interpret Module. The Module parameter can either be a single module name, or a list of module names. Module is removed from the set of modules currently being interpreted.

ni(AbsModule) -> {module,Module} | error | ok
ni(AbsModule,Options) -> {module,Module} | error | ok
na(AbsModule) -> {module,Module} | error | ok
na(AbsModule,Options) -> {module,Module} | error | ok
nn(Module) -> ok

Behaves as the corresponding i/1,i/2,a/1,a/2,n/1 functions described above, but on all nodes in the network. These functions always return ok if we are alive, otherwise as above.

interpreted() -> [Module]

Types:
Module = atom()

Returns a list of all modules currently being interpreted.

version() -> atom()

Returns the current version number of the interpreter.

auto_attach(Flag) -> true

Types:
Flag = FlagItem | [FlagItem]
FlagItem = init | break | exit | false

Interpreted processes can be attached automatically, without the need to attach to a process using the monitor window int:m(). An attachment window - not described here - pops up for the attached process. Flag specifies at which point interpreted processes are automatically attached.

Flag is one of:

• init. Attach to a process the very first time it calls an interpreted function.
  


• break. Attach to a process whenever it reaches a break point.
  


• exit. Attach to a process when it terminates.
  


• false. Deactivate the automatic attach facility.
  



If several conditions are to be active, a list of flags must be given.

auto_attach(Flag,Function) -> true

Types:
Flag = FlagItem | [FlagItem]
FlagItem = init | break | exit | false
Function = {Mod,Func}
Mod = atom()
Fun = atom()

As above, but instead of using the default attachment window, the specified Function is used in order to start the interaction with the attached process. The Function parameter must be the tuple {Mod,Func}, and this function should implement the corresponding functionality in the same way as the int_show:a_start/3,4 functions.

stack_trace(Flag) -> true

Types:
Flag = all | true | no_tail | false

The interpreter can keep call frames in the stack for future inspections. Typically, it is possible to go up and down in the stack in order to inspect the flow of control when the execution has been stopped - at a break point, when a process has terminated, or in a single step execution.

By default, the whole stack is kept (Flag = all or true). If processes with a very long life time and with a lot of tail recursive calls are interpreted, the no_tail flag should be used. No tail recursive calls are kept in the stack if this flag is used.

The false flag should be used if the interpreter is not to keep call frames.

snapshot() -> [Snap]

Types:
Snap = {Pid, InitialFunc, Status, Info}
Pid = pid()
InitialFunc = atom()
Status = idle | running | waiting | break | exit | no_conn
Info = {} | {Module, Line} | ExitReason
Module = atom()
Line = int()
ExitReason = term()

Returns a list which contains the current status information of all interpreted processes, [{Pid,InitialFunc,Status,Info}, ...] where:

• Pid is the process identity of the interpreted process.
  


• InitialFunc is the name of the first interpreted function.
  


• Status is the current status of the process.
  


• Info is additional information if Status is break (the tuple {Module,Line}) or exit (the exit reason).
  

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

Order Pid to resume the execution.

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

Types:
X = Y = Z = int()

Order the process c:pid(X,Y,Z) to resume the execution.

clear() -> ok

Delete (clear) information for all terminated processes from the interpreter.

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

Types:
Module = atom()
FileName = string()

Returns the name of the corresponding source code file last loaded for Module. Returns the name with the absolute path of the file.

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

Types:
Module = atom()
Line = int()
What = badarg | break_exists

Creates a new break point at Line in Module. The execution of an interpreted process is stopped before the expression at Line in Module is executed.

delete_break(Module,Line) -> ok | {error, What}

Types:
Module = atom()
Line = int()
What = badarg | no_break_exists

Deletes the break point located at Line in Module.

no_break() -> ok

Deletes all existing break points.

no_break(Module) -> ok

Types:
Module = atom()

Deletes all existing break points in Module.

break_in(Module,Function,Arity) -> ok | {error, What}

Types:
Module = atom()
Function = atom()
Arity = int()
What = badarg | function_not_found

Creates break points at the first line in every clause of the Module:Function/Arity function.

del_break_in(Module,Function,Arity) -> ok | {error, What}

Types:
Module = atom()
Function = atom()
Arity = int()
What = badarg | function_not_found

Deletes break points at the first line in every clause of the Module:Function/Arity function.

disable_break(Module,Line) -> ok | {error, What}

Types:
Module = atom()
Line = int()
What = badarg | no_break

Makes the break point at Line in Module inactive. No processes will be stopped at the break point, but the break point still exists.

enable_break(Module,Line) -> ok | {error, What}

Types:
Module = atom()
Line = int()
What = badarg | no_break

Makes the break point at Line in Module active. Processes will again be stopped at the break point.

action_at_break(Module,Line,Action) -> ok | {error, What}

Types:
Module = atom()
Line = int()
Action = enable | disable | delete
What = badarg | no_break

Sets the status of the break point at Line in Module after it is triggered the next time. Action is enable, disable, or delete.

test_at_break(Module,Line,Function) -> ok | {error, What}

Types:
Module = atom()
Line = int()
Function = {M,F}
Mod = atom()
Func = atom()
What = badarg | no_break

Makes the break point at Line in Module conditional. Function is called whenever the break point is reached. Function is a tuple {Mod,Func}. Function must have arity 1 and return either true or false. This way, the break point either triggers, or not. The argument to Function is the current variable bindings of the process at the place of the break point. The bindings can be inspected using int:get_binding/2.

get_binding(Variable,Bs) -> {value, Value} | unbound

Types:
Variable = atom()
Bs = term()
Value = term()

Gets the binding of Variable in the binding structure Bs. Variable must be an atom, for example 'Num'. This function is be used from inside a conditional break point function. Bs is supplied as an argument to the conditional test function above.

all_breaks() -> [{Break, Options}]

Types:
Break = {Module, Line}
Module = atom()
Line = int()
Options = term()

Returns a list of all existing break points.

all_breaks(Module) -> [{Break, Options}]

Types:
Module = atom()
Break = {Module, Line}
Line = int()
Options = term()

Returns a list of all existing break points located in Module.

Usage

Refer to the Debugger User's Guide for information about the graphical interface.

See Also

i(3), c(3), code(3), error_handler(3)

AUTHORS

Magnus Fröberg - support@erlang.ericsson.se