The R13B03 release.OTP_R13B03

1 files changed, 407 insertions, 0 deletions

diff --git a/lib/debugger/doc/src/i.xml b/lib/debugger/doc/src/i.xml
new file mode 100644
index 0000000000..9560b43665
--- /dev/null
+++ b/lib/debugger/doc/src/i.xml
@@ -0,0 +1,407 @@
+<?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>i</title>
+    <prepared></prepared>
+    <docno></docno>
+    <date></date>
+    <rev></rev>
+  </header>
+  <module>i</module>
+  <modulesummary>Debugger/Interpreter Interface</modulesummary>
+  <description>
+    <p>The module <c>i</c> provides short forms for some of
+      the functions used by the graphical Debugger and some of
+      the functions in the <c>int</c> module, the Erlang interpreter.
+    </p>
+
+    <p>This module also provides facilities for displaying status
+      information about interpreted processes and break points.</p>
+
+    <p>It is possible to attach to interpreted processes by giving
+      the corresponding process identity only. By default, an attachment
+      window pops up. Processes at other Erlang nodes can be
+      attached manually or automatically.</p>
+
+    <p>By preference, these functions can be included in the module
+      <c>shell_default</c>. By default, they are.</p>
+  </description>
+
+  <funcs>
+    <func>
+      <name>im() -> pid()</name>
+      <fsummary>Start a graphical monitor</fsummary>
+      <desc>
+	<p>Starts a new graphical monitor. This is the Monitor window,
+	  the main window of the Debugger. All of the Debugger and
+	  interpreter functionality is accessed from the Monitor window.
+	  The Monitor window displays the status of all processes that 
+	  have been/are executing interpreted modules.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>ii(AbsModules) -> ok</name>
+      <name>ii(AbsModule) -> {module, Module} | error</name>
+      <name>ini(AbsModules) -> ok</name>
+      <name>ini(AbsModule) -> {module, Module} | error</name>
+      <fsummary>Interpret a module</fsummary>
+      <type>
+	<v>AbsModules = [AbsModule]</v>
+	<v>AbsModule = Module | File</v>
+	<v>&nbsp;Module = atom()</v>
+	<v>&nbsp;File = string()</v>
+      </type>
+      <desc>
+	<p>Interprets the specified module(s). <c>ii/1</c> interprets
+	  the module(s) only at the current node, see
+	  <seealso marker="int#i/1">int:i/1</seealso>. <c>ini/1</c>
+	  interprets the module(s) at all known nodes, see
+	  <seealso marker="int#ni/1">int:ni/1</seealso>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>iq(AbsModule) -> ok</name>
+      <name>inq(AbsModule) -> ok</name>
+      <fsummary>Stop interpreting a module</fsummary>
+      <type>
+	<v>AbsModule = Module | File</v>
+	<v>&nbsp;Module = atom()</v>
+	<v>&nbsp;File = string()</v>
+      </type>
+      <desc>
+	<p>Stops interpreting the specified module. <c>iq/1</c> stops
+	  interpreting the module only at the current node. <c>inq/1</c>
+	  stops interpreting the module at all known nodes.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>il() -> ok</name>
+      <fsummary>Make a printout of all interpreted modules</fsummary>
+      <desc>
+	<p>Makes a printout of all interpreted modules.
+	  Modules are printed together with the full path name of the 
+	  corresponding source code file.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>ip() -> ok</name>
+      <fsummary>Make a printout of the current status of all interpreted
+	processes</fsummary>
+      <desc>
+	<p>Makes a printout of the current status of all interpreted 
+	  processes.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>ic() -> ok</name>
+      <fsummary>Clear information about processes executing interpreted
+	code</fsummary>
+      <desc>
+	<p>Clears information about processes executing interpreted code
+	  byt removing all information about terminated processes.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>iaa(Flags) -> true</name>
+      <name>iaa(Flags, Function) -> true</name>
+      <fsummary>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>Sets when and how to automatically attach to a debugged
+	  process, see
+	  <seealso marker="int#auto_attach/0">int:auto_attach/2</seealso>.
+	  <c>Function</c> defaults to the standard function used by
+	  the Debugger.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>ist(Flag) -> true</name>
+      <fsummary>Set how to save call frames</fsummary>
+      <type>
+	<v>Flag = all | no_tail | false</v>
+      </type>
+      <desc>
+	<p>Sets how to save call frames in the stack, see
+	  <seealso marker="int#stack_trace/0">int:stack_trace/1</seealso>.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>ia(Pid) -> ok | no_proc</name>
+      <fsummary>Attach to a process</fsummary>
+      <type>
+	<v>Pid = pid()</v>
+      </type>
+      <desc>
+	<p>Attaches to the debugged process <c>Pid</c>. A Debugger
+	  Attach Process window is opened for the process.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>ia(X,Y,Z) -> ok | no_proc</name>
+      <fsummary>Attach to a process</fsummary>
+      <type>
+	<v>X = Y = Z = int()</v>
+      </type>
+      <desc>
+	<p>Same as <c>ia(Pid)</c>, where <c>Pid</c> is the result of
+	  calling the shell function <c>pid(X,Y,Z)</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>ia(Pid, Function) -> ok | no_proc</name>
+      <fsummary>Attach to a process</fsummary>
+      <type>
+	<v>Pid = pid()</v>
+	<v>Function = {Module,Name}</v>
+	<v>&nbsp;Module = Name = atom()</v>
+      </type>
+      <desc>
+	<p>Attaches to the debugged process <c>Pid</c>. The interpreter
+	  will call <c>spawn(Module, Name, [Pid])</c> (and ignore
+	  the result).</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>ia(X,Y,Z, Function) -> ok | no_proc</name>
+      <fsummary>Attach to a process</fsummary>
+      <type>
+	<v>X = Y = Z = int()</v>
+	<v>Function = {Module,Name}</v>
+	<v>&nbsp;Module = Name = atom()</v>
+      </type>
+      <desc>
+	<p>Same as <c>ia(Pid, Function)</c>, where <c>Pid</c> is
+	  the result of calling the shell function <c>pid(X,Y,Z)</c>.
+	  An attached process is expected to call the unofficial
+	  <c>int:attached(Pid)</c> function and to be able to handle
+	  messages from the interpreter, see <c>dbg_ui_trace.erl</c> for
+	  an example.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>ib(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>ib(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 breakpoints at the first line of every clause of 
+	  the <c>Module:Name/Arity</c> function.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>ir() -> ok</name>
+      <fsummary>Delete all breakpoints</fsummary>
+      <desc>
+	<p>Deletes all breakpoints.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>ir(Module) -> ok</name>
+      <fsummary>Delete all breakpoints in a module</fsummary>
+      <type>
+	<v>Module = atom()</v>
+      </type>
+      <desc>
+	<p>Deletes all breakpoints in <c>Module</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>ir(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>ir(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>ibd(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>ibe(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>iba(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>ibc(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>.</p>
+
+	<p>The conditional test is performed by calling
+	  <c>Module:Name(Bindings)</c>, where <c>Bindings</c> is
+	  the current variable bindings. The function must return
+	  <c>true</c> (break) or <c>false</c> (do not break). Use
+	  <c>int:get_binding(Var, Bindings)</c> to retrieve the value
+	  of a variable <c>Var</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>ipb() -> ok</name>
+      <fsummary>Make a printout of all existing breakpoints</fsummary>
+      <desc>
+	<p>Makes a printout of all existing breakpoints.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>ipb(Module) -> ok</name>
+      <fsummary>Make a printout of all breakpoints in a module
+      </fsummary>
+      <type>
+	<v>Module = atom()</v>
+      </type>
+      <desc>
+	<p>Makes a printout of all existing breakpoints in
+	  <c>Module</c>.</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>iv() -> atom()</name>
+      <fsummary>Current version number of the interpreter</fsummary>
+      <desc>
+	<p>Returns the current version number of the interpreter.
+	  The same as the version number of the Debugger application.
+	</p>
+      </desc>
+    </func>
+
+    <func>
+      <name>help() -> ok</name>
+      <fsummary>Print help text</fsummary>
+      <desc>
+	<p>Prints help text.</p>
+      </desc>
+    </func>
+  </funcs>
+
+  <section>
+    <title>Usage</title>
+
+    <p>Refer to the Debugger User's Guide for information about
+      the Debugger.</p>
+  </section>
+
+  <section>
+  <title>See Also</title>
+    <p><c>int(3)</c></p>
+  </section>
+</erlref>
+
+