diff options
Diffstat (limited to 'lib/debugger/doc/src/int.xml')
| -rw-r--r-- | lib/debugger/doc/src/int.xml | 528 |
1 files changed, 528 insertions, 0 deletions
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 @@ +<?xml version="1.0" encoding="latin1" ?> +<!DOCTYPE erlref SYSTEM "erlref.dtd"> + +<erlref> + <header> + <copyright> + <year>1998</year><year>2009</year> + <holder>Ericsson AB. All Rights Reserved.</holder> + </copyright> + <legalnotice> + 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. + + </legalnotice> + + <title>int</title> + <prepared></prepared> + <docno></docno> + <date></date> + <rev></rev> + </header> + <module>int</module> + <modulesummary>Interpreter Interface</modulesummary> + <description> + <p>The Erlang interpreter provides mechanisms for breakpoints and + stepwise execution of code. It is mainly intended to be used by + the <em>Debugger</em>, see Debugger User's Guide and + <c>debugger(3)</c>.</p> + + <p>From the shell, it is possible to:</p> + <list> + <item>Specify which modules should be interpreted.</item> + <item>Specify breakpoints.</item> + <item>Monitor the current status of all processes executing code + in interpreted modules, also processes at other Erlang nodes. + </item> + </list> + + <p>By <em>attaching to</em> 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 + <c>int.erl</c> for available functions and <c>dbg_ui_trace.erl</c> + for possible messages.</p> + + <p>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.</p> + </description> + + <section> + <title>Breakpoints</title> + + <p>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.</p> + + <p>A breakpoint have a status, a trigger action and may have a + condition associated with it. The status is either <em>active</em> + or <em>inactive</em>. An inactive breakpoint is ignored. When a + breakpoint is reached, the trigger action specifies if + the breakpoint should continue to be active (<em>enable</em>), if + it should become inactive (<em>disable</em>), or if it should be + removed (<em>delete</em>). A condition is a tuple + <c>{Module,Name}</c>. When the breakpoint is reached, + <c>Module:Name(Bindings)</c> is called. If this evaluates to + <c>true</c>, execution will stop. If this evaluates to + <c>false</c>, the breakpoint is ignored. <c>Bindings</c> contains + the current variable bindings, use <c>get_binding</c> to retrieve + the value for a given variable.</p> + + <p>By default, a breakpoint is active, has trigger action + <c>enable</c> and has no condition associated with it. For more + detailed information about breakpoints, refer to Debugger User's + Guide.</p> + </section> + + <funcs> + <func> + <name>i(AbsModule) -> {module,Module} | error</name> + <name>i(AbsModules) -> ok</name> + <name>ni(AbsModule) -> {module,Module} | error</name> + <name>ni(AbsModules) -> ok</name> + <fsummary>Interpret a module</fsummary> + <type> + <v>AbsModules = [AbsModule]</v> + <v>AbsModule = Module | File | [Module | File]</v> + <v> Module = atom()</v> + <v> File = string()</v> + </type> + <desc> + <p>Interprets the specified module(s). <c>i/1</c> interprets + the module only at the current node. <c>ni/1</c> interprets + the module at all known nodes.</p> + + <p>A module may be given by its module name (atom) or by its + file name. If given by its module name, the object code + <c>Module.beam</c> is searched for in the current path. + The source code <c>Module.erl</c> is searched for first in + the same directory as the object code, then in a <c>src</c> + directory next to it.</p> + + <p>If given by its file name, the file name may include a path + and the <c>.erl</c> extension may be omitted. The object code + <c>Module.beam</c> is searched for first in the same directory + as the source code, then in an <c>ebin</c> directory next to + it, and then in the current path.</p> + + <note> + <p>The interpreter needs both the source code and the object + code, and the object code <em>must</em> include debug + information. That is, only modules compiled with the option + <c>debug_info</c> set can be interpreted.</p> + </note> + + <p>The functions returns <c>{module,Module}</c> if the module + was interpreted, or <c>error</c> if it was not.</p> + + <p>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 <c>ok</c>, + but prints some information to stdout if a module could not be + interpreted.</p> + </desc> + </func> + + <func> + <name>n(AbsModule) -> ok</name> + <name>nn(AbsModule) -> ok</name> + <fsummary>Stop interpreting a module</fsummary> + <type> + <v>AbsModule = Module | File | [Module | File]</v> + <v> Module = atom()</v> + <v> File = string()</v> + </type> + <desc> + <p>Stops interpreting the specified module. <c>n/1</c> stops + interpreting the module only at the current node. <c>nn/1</c> + stops interpreting the module at all known nodes.</p> + + <p>As for <c>i/1</c> and <c>ni/1</c>, a module may be given by + either its module name or its file name.</p> + </desc> + </func> + + <func> + <name>interpreted() -> [Module]</name> + <fsummary>Get all interpreted modules</fsummary> + <type> + <v>Module = atom()</v> + </type> + <desc> + <p>Returns a list with all interpreted modules.</p> + </desc> + </func> + + <func> + <name>file(Module) -> File | {error,not_loaded}</name> + <fsummary>Get the file name for an interpreted module</fsummary> + <type> + <v>Module = atom()</v> + <v>File = string()</v> + </type> + <desc> + <p>Returns the source code file name <c>File</c> for an + interpreted module <c>Module</c>.</p> + </desc> + </func> + + <func> + <name>interpretable(AbsModule) -> true | {error,Reason}</name> + <fsummary>Check if a module is possible to interpret</fsummary> + <type> + <v>AbsModule = Module | File</v> + <v> Module = atom()</v> + <v> File = string()</v> + <v>Reason = no_src | no_beam | no_debug_info | badarg + | {app,App}</v> + <v> App = atom()</v> + </type> + <desc> + <p>Checks if a module is possible to interpret. The module can + be given by its module name <c>Module</c> or its source file + name <c>File</c>. If given by a module name, the module is + searched for in the code path.</p> + + <p>The function returns <c>true</c> if both source code and + object code for the module is found, the module has been + compiled with the option <c>debug_info</c> set and does not + belong to any of the applications Kernel, STDLIB, GS or + Debugger itself.</p> + + <p>The function returns <c>{error,Reason}</c> if the module for + some reason is not possible to interpret.</p> + + <p><c>Reason</c> is <c>no_src</c> if no source code is found or + <c>no_beam</c> if no object code is found. It is assumed that + the source- and object code are located either in the same + directory, or in <c>src</c> and <c>ebin</c> directories next + to each other.</p> + + <p><c>Reason</c> is <c>no_debug_info</c> if the module has not + been compiled with the option <c>debug_info</c> set.</p> + + <p><c>Reason</c> is <c>badarg</c> if <c>AbsModule</c> is not + found. This could be because the specified file does not + exist, or because <c>code:which/1</c> 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.</p> + + <p><c>Reason</c> is <c>{app,App}</c> where <c>App</c> is + <c>kernel</c>, <c>stdlib</c>, <c>gs</c> or <c>debugger</c> if + <c>AbsModule</c> belongs to one of these applications.</p> + + <p>Note that the function can return <c>true</c> 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.</p> + </desc> + </func> + + <func> + <name>auto_attach() -> false | {Flags,Function}</name> + <name>auto_attach(false)</name> + <name>auto_attach(Flags, Function)</name> + <fsummary>Get/set when and how to attach to a process</fsummary> + <type> + <v>Flags = [init | break | exit]</v> + <v>Function = {Module,Name,Args}</v> + <v> Module = Name = atom()</v> + <v> Args = [term()]</v> + </type> + <desc> + <p>Gets and sets when and how to automatically attach to a + process executing code in interpreted modules. <c>false</c> + 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:</p> + <list> + <item><c>init</c> - attach when a process for the very first + time calls an interpreted function.</item> + <item><c>break</c> - attach whenever a process reaches a + breakpoint.</item> + <item><c>exit</c> - attach when a process terminates.</item> + </list> + + <p>When the specified event occurs, the function <c>Function</c> + will be called as:</p> + <pre> +spawn(Module, Name, [Pid | Args]) + </pre> + <p><c>Pid</c> is the pid of the process executing interpreted + code.</p> + </desc> + </func> + + <func> + <name>stack_trace() -> Flag</name> + <name>stack_trace(Flag)</name> + <fsummary>Get/set if and how to save call frames</fsummary> + <type> + <v>Flag = all | no_tail | false</v> + </type> + <desc> + <p>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.</p> + <list> + <item><c>all</c> - save information about all current calls, + that is, function calls that have not yet returned a value. + This is the default.</item> + <item><c>no_tail</c> - 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.</item> + <item><c>false</c> - do not save any information about current + calls.</item> + </list> + </desc> + </func> + + <func> + <name>break(Module, Line) -> ok | {error,break_exists}</name> + <fsummary>Create a breakpoint</fsummary> + <type> + <v>Module = atom()</v> + <v>Line = int()</v> + </type> + <desc> + <p>Creates a breakpoint at <c>Line</c> in <c>Module</c>.</p> + </desc> + </func> + + <func> + <name>delete_break(Module, Line) -> ok</name> + <fsummary>Delete a breakpoint</fsummary> + <type> + <v>Module = atom()</v> + <v>Line = int()</v> + </type> + <desc> + <p>Deletes the breakpoint located at <c>Line</c> in + <c>Module</c>.</p> + </desc> + </func> + + <func> + <name>break_in(Module, Name, Arity) -> ok + | {error,function_not_found}</name> + <fsummary>Create breakpoints in the specified function</fsummary> + <type> + <v>Module = Name = atom()</v> + <v>Arity = int()</v> + </type> + <desc> + <p>Creates a breakpoint at the first line of every clause of + the <c>Module:Name/Arity</c> function.</p> + </desc> + </func> + + <func> + <name>del_break_in(Module, Name, Arity) -> ok + | {error,function_not_found}</name> + <fsummary>Delete breakpoints from the specified function + </fsummary> + <type> + <v>Module = Name = atom()</v> + <v>Arity = int()</v> + </type> + <desc> + <p>Deletes the breakpoints at the first line of every clause of + the <c>Module:Name/Arity</c> function. + </p> + </desc> + </func> + + <func> + <name>no_break() -> ok</name> + <name>no_break(Module) -> ok</name> + <fsummary>Delete all breakpoints</fsummary> + <desc> + <p>Deletes all breakpoints, or all breakpoints in <c>Module</c>. + </p> + </desc> + </func> + + <func> + <name>disable_break(Module, Line) -> ok</name> + <fsummary>Make a breakpoint inactive</fsummary> + <type> + <v>Module = atom()</v> + <v>Line = int()</v> + </type> + <desc> + <p>Makes the breakpoint at <c>Line</c> in <c>Module</c> + inactive.</p> + </desc> + </func> + + <func> + <name>enable_break(Module, Line) -> ok</name> + <fsummary>Make a breakpoint active</fsummary> + <type> + <v>Module = atom()</v> + <v>Line = int()</v> + </type> + <desc> + <p>Makes the breakpoint at <c>Line</c> in <c>Module</c> active. + </p> + </desc> + </func> + + <func> + <name>action_at_break(Module, Line, Action) -> ok</name> + <fsummary>Set the trigger action of a breakpoint</fsummary> + <type> + <v>Module = atom()</v> + <v>Line = int()</v> + <v>Action = enable | disable | delete</v> + </type> + <desc> + <p>Sets the trigger action of the breakpoint at <c>Line</c> in + <c>Module</c> to <c>Action</c>.</p> + </desc> + </func> + + <func> + <name>test_at_break(Module, Line, Function) -> ok</name> + <fsummary>Set the conditional test of a breakpoint</fsummary> + <type> + <v>Module = atom()</v> + <v>Line = int()</v> + <v>Function = {Module,Name}</v> + <v> Name = atom()</v> + </type> + <desc> + <p>Sets the conditional test of the breakpoint at <c>Line</c> in + <c>Module</c> to <c>Function</c>. The function must + fulfill the requirements specified in the section + <em>Breakpoints</em> above.</p> + </desc> + </func> + + <func> + <name>get_binding(Var, Bindings) -> {value,Value} | unbound</name> + <fsummary>Retrieve a variable binding</fsummary> + <type> + <v>Var = atom()</v> + <v>Bindings = term()</v> + <v>Value = term()</v> + </type> + <desc> + <p>Retrieves the binding of <c>Var</c>. This function is + intended to be used by the conditional function of a + breakpoint.</p> + </desc> + </func> + + <func> + <name>all_breaks() -> [Break]</name> + <name>all_breaks(Module) -> [Break]</name> + <fsummary>Get all breakpoints</fsummary> + <type> + <v>Break = {Point,Options}</v> + <v> Point = {Module,Line}</v> + <v> Module = atom()</v> + <v> Line = int()</v> + <v> Options = [Status,Trigger,null,Cond|]</v> + <v> Status = active | inactive</v> + <v> Trigger = enable | disable | delete</v> + <v> Cond = null | Function</v> + <v> Function = {Module,Name}</v> + <v> Name = atom()</v> + </type> + <desc> + <p>Gets all breakpoints, or all breakpoints in <c>Module</c>. + </p> + </desc> + </func> + + <func> + <name>snapshot() -> [Snapshot]</name> + <fsummary>Get information about all processes executing interpreted + code</fsummary> + <type> + <v>Snapshot = {Pid, Function, Status, Info}</v> + <v> Pid = pid()</v> + <v> Function = {Module,Name,Args}</v> + <v> Module = Name = atom()</v> + <v> Args = [term()]</v> + <v> Status = idle | running | waiting | break | exit + | no_conn</v> + <v> Info = {} | {Module,Line} | ExitReason</v> + <v> Line = int()</v> + <v> ExitReason = term()</v> + </type> + <desc> + <p>Gets information about all processes executing interpreted code. + </p> + <list> + <item><c>Pid</c> - process identifier.</item> + <item><c>Function</c> - first interpreted function called by + the process.</item> + <item><c>Status</c> - current status of the process.</item> + <item><c>Info</c> - additional information.</item> + </list> + <p><c>Status</c> is one of:</p> + <list> + <item><c>idle</c> - the process is no longer executing + interpreted code. <c>Info={}</c>.</item> + <item><c>running</c> - the process is running. <c>Info={}</c>. + </item> + <item><c>waiting</c> - the process is waiting at a + <c>receive</c>. <c>Info={}</c>.</item> + <item><c>break</c> - process execution has been stopped, + normally at a breakpoint. <c>Info={Module,Line}</c>.</item> + <item><c>exit</c> - the process has terminated. + <c>Info=ExitReason</c>.</item> + <item><c>no_conn</c> - the connection is down to the node + where the process is running. <c>Info={}</c>.</item> + </list> + </desc> + </func> + + <func> + <name>clear() -> ok</name> + <fsummary>Clear information about processes executing interpreted + code</fsummary> + <desc> + <p>Clears information about processes executing interpreted code + by removing all information about terminated processes.</p> + </desc> + </func> + + <func> + <name>continue(Pid) -> ok | {error,not_interpreted}</name> + <name>continue(X,Y,Z) -> ok | {error,not_interpreted}</name> + <fsummary>Resume process execution</fsummary> + <type> + <v>Pid = pid()</v> + <v>X = Y = Z = int()</v> + </type> + <desc> + <p>Resume process execution for <c>Pid</c>, or for + <c>c:pid(X,Y,Z)</c>.</p> + </desc> + </func> + </funcs> +</erlref> + + |