From 84adefa331c4159d432d22840663c38f155cd4c1 Mon Sep 17 00:00:00 2001 From: Erlang/OTP Date: Fri, 20 Nov 2009 14:54:40 +0000 Subject: The R13B03 release. --- lib/debugger/doc/src/int.xml | 528 +++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 528 insertions(+) create mode 100644 lib/debugger/doc/src/int.xml (limited to 'lib/debugger/doc/src/int.xml') diff --git a/lib/debugger/doc/src/int.xml b/lib/debugger/doc/src/int.xml new file mode 100644 index 0000000000..8b55461a44 --- /dev/null +++ b/lib/debugger/doc/src/int.xml @@ -0,0 +1,528 @@ + + + + +
+ + 19982009 + Ericsson AB. All Rights Reserved. + + + The contents of this file are subject to the Erlang Public License, + Version 1.1, (the "License"); you may not use this file except in + compliance with the License. You should have received a copy of the + Erlang Public License along with this software. If not, it can be + retrieved online at http://www.erlang.org/. + + Software distributed under the License is distributed on an "AS IS" + basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See + the License for the specific language governing rights and limitations + under the License. + + + + int + + + + +
+ int + Interpreter Interface + +

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 interpreted 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_ui_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 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.

+ + +
+ 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 inactive breakpoint is ignored. When a + breakpoint is reached, the trigger action specifies if + the breakpoint should continue to be active (enable), if + it should become inactive (disable), or if it should be + removed (delete). A condition is a tuple + {Module,Name}. When the breakpoint 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.

+
+ + + + i(AbsModule) -> {module,Module} | error + i(AbsModules) -> ok + ni(AbsModule) -> {module,Module} | error + ni(AbsModules) -> ok + Interpret a module + + 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.

+ + +

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 interpreted.

+ + +

The functions returns {module,Module} if the module + was interpreted, 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 information to stdout if a module could not be + interpreted.

+ + + + + n(AbsModule) -> ok + nn(AbsModule) -> ok + Stop interpreting a module + + 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] + Get all interpreted modules + + Module = atom() + + +

Returns a list with all interpreted modules.

+ + + + + file(Module) -> File | {error,not_loaded} + Get the file name for an interpreted module + + Module = atom() + File = string() + + +

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

+ + + + + interpretable(AbsModule) -> true | {error,Reason} + Check if a module is possible to interpret + + 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 applications Kernel, STDLIB, GS or + Debugger itself.

+ +

The function returns {error,Reason} if the module for + some reason is not possible to interpret.

+ +

Reason is no_src if no source code is found or + no_beam if no object 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 because 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) + Get/set when and how to attach to a process + + 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 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:

+ + 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) + Get/set if and how to save call frames + + 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 exception of class error) occurs.

+ + all - save information about all current calls, + that is, function calls that have not yet returned a value. + This is the default. + 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. + false - do not save any information about current + calls. + + + + + + break(Module, Line) -> ok | {error,break_exists} + Create a breakpoint + + Module = atom() + Line = int() + + +

Creates a breakpoint at Line in Module.

+ + + + + delete_break(Module, Line) -> ok + Delete a breakpoint + + Module = atom() + Line = int() + + +

Deletes the breakpoint located at Line in + Module.

+ + + + + break_in(Module, Name, Arity) -> ok + | {error,function_not_found} + Create breakpoints in the specified function + + 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} + Delete breakpoints from the specified function + + + 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 + Delete all breakpoints + +

Deletes all breakpoints, or all breakpoints in Module. +

+ + + + + disable_break(Module, Line) -> ok + Make a breakpoint inactive + + Module = atom() + Line = int() + + +

Makes the breakpoint at Line in Module + inactive.

+ + + + + enable_break(Module, Line) -> ok + Make a breakpoint active + + Module = atom() + Line = int() + + +

Makes the breakpoint at Line in Module active. +

+ + + + + action_at_break(Module, Line, Action) -> ok + Set the trigger action of a breakpoint + + 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 + Set the conditional test of a breakpoint + + 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 + Retrieve a variable binding + + 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] + Get all breakpoints + + 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] + Get information about all processes executing interpreted + code + + 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 + Clear information about processes executing interpreted + code + +

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} + Resume process execution + + Pid = pid() + X = Y = Z = int() + + +

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

+ + + + + + -- cgit v1.2.3