aboutsummaryrefslogtreecommitdiffstats
path: root/lib/debugger/doc/src/int.xml
diff options
context:
space:
mode:
Diffstat (limited to 'lib/debugger/doc/src/int.xml')
-rw-r--r--lib/debugger/doc/src/int.xml528
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>&nbsp;Module = atom()</v>
+ <v>&nbsp;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>&nbsp;Module = atom()</v>
+ <v>&nbsp;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>&nbsp;Module = atom()</v>
+ <v>&nbsp;File = string()</v>
+ <v>Reason = no_src | no_beam | no_debug_info | badarg
+ | {app,App}</v>
+ <v>&nbsp;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>&nbsp;Module = Name = atom()</v>
+ <v>&nbsp;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>&nbsp;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>&nbsp;Point = {Module,Line}</v>
+ <v>&nbsp;&nbsp;Module = atom()</v>
+ <v>&nbsp;&nbsp;Line = int()</v>
+ <v>&nbsp;Options = [Status,Trigger,null,Cond|]</v>
+ <v>&nbsp;&nbsp;Status = active | inactive</v>
+ <v>&nbsp;&nbsp;Trigger = enable | disable | delete</v>
+ <v>&nbsp;&nbsp;Cond = null | Function</v>
+ <v>&nbsp;&nbsp;&nbsp;Function = {Module,Name}</v>
+ <v>&nbsp;&nbsp;&nbsp;&nbsp;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>&nbsp;Pid = pid()</v>
+ <v>&nbsp;Function = {Module,Name,Args}</v>
+ <v>&nbsp;&nbsp;Module = Name = atom()</v>
+ <v>&nbsp;&nbsp;Args = [term()]</v>
+ <v>&nbsp;Status = idle | running | waiting | break | exit
+ | no_conn</v>
+ <v>&nbsp;Info = {} | {Module,Line} | ExitReason</v>
+ <v>&nbsp;&nbsp;Line = int()</v>
+ <v>&nbsp;&nbsp;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>
+
+