File: int.html

package info (click to toggle)
erlang-doc-html 1%3A10.b.1a-1
links: PTS
area: main
in suites: sarge
size: 22,488 kB
ctags: 9,933
sloc: erlang: 505; ansic: 323; perl: 61; sh: 45; makefile: 39
file content (648 lines) | stat: -rw-r--r-- 18,281 bytes
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- This document was generated using DocBuilder 3.3.2 -->
<HTML>
<HEAD>
  <TITLE>int</TITLE>
  <SCRIPT type="text/javascript" src="../../../../doc/erlresolvelinks.js">
</SCRIPT>
  <STYLE TYPE="text/css">
<!--
    .REFBODY     { margin-left: 13mm }
    .REFTYPES    { margin-left: 8mm }
-->
  </STYLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#FF00FF"
      ALINK="#FF0000">
<!-- refpage -->
<CENTER>
<A HREF="http://www.erlang.se">
  <IMG BORDER=0 ALT="[Ericsson AB]" SRC="min_head.gif">
</A>
<H1>int</H1>
</CENTER>

<H3>MODULE</H3>
<DIV CLASS=REFBODY>
int
</DIV>

<H3>MODULE SUMMARY</H3>
<DIV CLASS=REFBODY>
Interpreter Interface.
</DIV>

<H3>DESCRIPTION</H3>
<DIV CLASS=REFBODY>

<P>The Erlang interpreter provides mechanisms for breakpoints and
stepwise execution of code. It is mainly intended to be used by
the <STRONG>Debugger</STRONG>, see Debugger User's Guide and
<CODE>debugger(3)</CODE>.
<P>From the shell, it is possible to:
<P>
<UL>

<LI>
Specify which modules should be interpreted.
</LI>


<LI>
Specify breakpoints.
</LI>


<LI>
Monitor the current status of all processes executing code
        in interpreted modules, also processes at other Erlang nodes.
</LI>


</UL>

<P>By <STRONG>attaching to</STRONG> 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, but not
recommended, to implement your own attached process. See <CODE>int.erl</CODE>
for available functions and <CODE>dbg_ui_trace.erl</CODE> for possible
messages.
</DIV>

<H3>Breakpoints</H3>
<DIV CLASS=REFBODY>

<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,
i.e. a line of code containing an executable expression.
<P>A breakpoint have a status, a trigger action and may have a condition
associated with it. The status is either <STRONG>active</STRONG> or
<STRONG>inactive</STRONG>. An inactive breakpoint is ignored.
When a breakpoint is reached, the trigger action specifies if
the breakpoint should continue to be active (<STRONG>enable</STRONG>), if it
should become inactive (<STRONG>disable</STRONG>), or if it should be
removed (<STRONG>delete</STRONG>). A condition is a tuple <CODE>{Module,Name}</CODE>.
When the breakpoint is reached, <CODE>Module:Name(Bindings)</CODE> is
called. If this evaluates to <CODE>true</CODE>, execution will stop. If
this evaluates to <CODE>false</CODE>, the breakpoint is ignored.
<CODE>Bindings</CODE> contains the current variable bindings, use
<CODE>get_binding</CODE> to retrieve the value for a given variable.
<P>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.
</DIV>

<H3>EXPORTS</H3>

<P><A NAME="i/1"><STRONG><CODE>i(AbsModule) -&#62; {module,Module} | error</CODE></STRONG></A><BR>
<A NAME="ni/1"><STRONG><CODE>ni(AbsModule) -&#62; {module,Module} | error</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>AbsModule = Module | File | [Module | File]</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>File = string()</CODE></STRONG><BR>
<STRONG><CODE>Options = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Interprets the specified module. <CODE>i/1,2</CODE> interprets
         the module only at the current node. <CODE>ni/1,2</CODE> interprets
         the module at all known nodes.
<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
         <CODE>Module.beam</CODE> is searched for in the current path. The source
         code <CODE>Module.erl</CODE> is searched for first in the same directory
         as the object code, then in a <CODE>src</CODE> directory next to it.
<P>If given by its file name, the file name may include a path and
         the <CODE>.erl</CODE> extension may be omitted. The object code
         <CODE>Module.beam</CODE> is searched for first in the same directory as
         the source code, then in an <CODE>ebin</CODE> directory next to it, and
         then in the current path.
<P>
<TABLE CELLPADDING=4>
  <TR>
    <TD VALIGN=TOP><IMG ALT="Note!" SRC="note.gif"></TD>
    <TD>

<P>The interpreter needs both the source code and the object code,
         and the object code <STRONG>must</STRONG> include debug information.
         That is, only modules compiled with the option <CODE>debug_info</CODE>
         set can be interpreted.
             </TD>
  </TR>
</TABLE>

</DIV>

<P><A NAME="n/1"><STRONG><CODE>n(AbsModule) -&#62; ok</CODE></STRONG></A><BR>
<A NAME="nn/1"><STRONG><CODE>nn(AbsModule) -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>AbsModule = Module | File | [Module | File]</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>File = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Stops interpreting the specified module. <CODE>n/1</CODE> stops
         interpreting the node only at the current node. <CODE>nn/1</CODE> stops
         interpreting the module at all known nodes.
<P>As for <CODE>i/1</CODE> and <CODE>ni/1</CODE>, a module may be given by
         either its module name or its file name.
</DIV>

<P><A NAME="interpreted/0"><STRONG><CODE>interpreted() -&#62; [Module]</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns a list with all interpreted modules.
</DIV>

<P><A NAME="file/1"><STRONG><CODE>file(Module) -&#62; File | {error,not_loaded}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>File = string()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Returns the source code file name <CODE>File</CODE> for an interpreted
         module <CODE>Module</CODE>.
</DIV>

<P><A NAME="interpretable/1"><STRONG><CODE>interpretable(AbsModule) -&#62; true | {error,Reason}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>AbsModule = Module | File</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>File = string()</CODE></STRONG><BR>
<STRONG><CODE>Reason = no_src | no_beam | no_debug_info | badarg</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Checks if a module is possible to interpret. The module can be
         given by its module name <CODE>Module</CODE> or its file name
         <CODE>File</CODE>.
<P>The function returns <CODE>true</CODE> if both source code and object
         code for the module is found, and the module has been compiled
         with the option <CODE>debug_info</CODE> set.
<P>The function returns <CODE>{error,Reason}</CODE> where <CODE>Reason</CODE> is
         <CODE>no_src</CODE> if no source code is found, <CODE>no_beam</CODE> if no
         object code is found, <CODE>no_debug_info</CODE> if the module has not
         been compiled with the option <CODE>debug_info</CODE> set, or
         <CODE>badarg</CODE> if <CODE>AbsModule</CODE> does not exist.
</DIV>

<P><A NAME="auto_attach/0"><STRONG><CODE>auto_attach() -&#62; false | {Flags,Function}</CODE></STRONG></A><BR>
<A NAME="auto_attach/1"><STRONG><CODE>auto_attach(false)</CODE></STRONG></A><BR>
<A NAME="auto_attach/2"><STRONG><CODE>auto_attach(Flags, Function)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Flags = [init | break | exit]</CODE></STRONG><BR>
<STRONG><CODE>Function = {Module,Name,Args}</CODE></STRONG><BR>
<STRONG><CODE>Module = Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>Args = [term()]</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Get and set when and how to automatically attach to a process
         executing code in interpreted modules. <CODE>false</CODE> means never
         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>
<UL>

<LI>
<CODE>init</CODE> - attach when a process for the very first time
         calls an interpreted function.
</LI>


<LI>
<CODE>break</CODE> - attach whenever a process reaches a
         breakpoint.
</LI>


<LI>
<CODE>exit</CODE> - attach when a process terminates.
</LI>


</UL>

<P>When the specified event occurs, the function <CODE>Function</CODE>
         will be called as:
<PRE>
spawn(Module, Name, [Pid | Args])
        
</PRE>

<P>The resulting process can attach to, i.e. send commands to and
         receive messages from, the interpreted process, see above.
</DIV>

<P><A NAME="stack_trace/0"><STRONG><CODE>stack_trace() -&#62; Flag</CODE></STRONG></A><BR>
<A NAME="stack_trace/1"><STRONG><CODE>stack_trace(Flag)</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Flag = all | no_tail | false</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Get and set how to save call frames in the stack. This makes it
         possible to inspect the call chain of a process.
<P>
<UL>

<LI>
<CODE>all</CODE> - save all call frames. This is the default.
         
</LI>


<LI>
<CODE>no_tail</CODE> - save all call frames, except for tail
         recursive calls. This option consumes less memory and may be
         necessary to use for processes with long lifetimes and many
         tail recursive calls.
</LI>


<LI>
<CODE>false</CODE> - do not save call frames.
</LI>


</UL>

</DIV>

<P><A NAME="break/2"><STRONG><CODE>break(Module, Line) -&#62; ok | {error,break_exists}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Line = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Creates a breakpoint at <CODE>Line</CODE> in <CODE>Module</CODE>.
</DIV>

<P><A NAME="delete_break/2"><STRONG><CODE>delete_break(Module, Line) -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Line = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Deletes the breakpoint located at <CODE>Line</CODE> in <CODE>Module</CODE>.
        
</DIV>

<P><A NAME="break_in/3"><STRONG><CODE>break_in(Module, Name, Arity) -&#62; ok
        | {error,function_not_found}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Module = Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>Function = atom()</CODE></STRONG><BR>
<STRONG><CODE>Arity = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Create a breakpoint at the first line of every clause of 
         the <CODE>Module:Function/Arity</CODE> function.

</DIV>

<P><A NAME="del_break_in/3"><STRONG><CODE>del_break_in(Module, Name, Arity) -&#62; ok
        | {error,function_not_found}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Module = Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>Arity = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Delete the breakpoints at the first line of every clause of 
         the <CODE>Module:Function/Arity</CODE> function.
        
</DIV>

<P><A NAME="no_break/0"><STRONG><CODE>no_break() -&#62; ok</CODE></STRONG></A><BR>
<A NAME="no_break/1"><STRONG><CODE>no_break(Module) -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Deletes all breakpoints, or all breakpoints in <CODE>Module</CODE>.
</DIV>

<P><A NAME="disable_break/2"><STRONG><CODE>disable_break(Module, Line) -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Line = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Makes the breakpoint at <CODE>Line</CODE> in <CODE>Module</CODE> inactive.
        
</DIV>

<P><A NAME="enable_break/2"><STRONG><CODE>enable_break(Module, Line) -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Line = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Makes the breakpoint at <CODE>Line</CODE> in <CODE>Module</CODE> active.
</DIV>

<P><A NAME="action_at_break/3"><STRONG><CODE>action_at_break(Module, Line, Action) -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Line = integer()</CODE></STRONG><BR>
<STRONG><CODE>Action = enable | disable | delete</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Set the trigger action of the breakpoint at <CODE>Line</CODE> in
         <CODE>Module</CODE> to <CODE>Action</CODE>.
</DIV>

<P><A NAME="test_at_break/3"><STRONG><CODE>test_at_break(Module, Line, Function) -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Line = integer()</CODE></STRONG><BR>
<STRONG><CODE>Function = {Module,Name}</CODE></STRONG><BR>
<STRONG><CODE>Module = Name = atom()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Set the condition of the breakpoint at <CODE>Line</CODE> in
         <CODE>Module</CODE> to <CODE>Function</CODE>.
        
</DIV>

<P><A NAME="get_binding/2"><STRONG><CODE>get_binding(Var, Bindings) -&#62; {value,Value} | unbound</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Var = atom()</CODE></STRONG><BR>
<STRONG><CODE>Bindings = term()</CODE></STRONG><BR>
<STRONG><CODE>Value = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Retrieve the binding of <CODE>Variable</CODE>. This function is
         intended to be used by a breakpoint condition function.
</DIV>

<P><A NAME="all_breaks/0"><STRONG><CODE>all_breaks() -&#62; [Break]</CODE></STRONG></A><BR>
<A NAME="all_breaks/1"><STRONG><CODE>all_breaks(Module) -&#62; [Break]</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Break = {Point,Options}</CODE></STRONG><BR>
<STRONG><CODE>Point = {Module,Line}</CODE></STRONG><BR>
<STRONG><CODE>Module = atom()</CODE></STRONG><BR>
<STRONG><CODE>Line = int()</CODE></STRONG><BR>
<STRONG><CODE>Options = [Status,Trigger,null,Cond|]</CODE></STRONG><BR>
<STRONG><CODE>Status = active | inactive</CODE></STRONG><BR>
<STRONG><CODE>Trigger = enable | disable | delete</CODE></STRONG><BR>
<STRONG><CODE>Cond = null | Function</CODE></STRONG><BR>
<STRONG><CODE>Function = {Module,Name}</CODE></STRONG><BR>
<STRONG><CODE>Name = atom()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Gets all breakpoints, or all breakpoints in <CODE>Module</CODE>.
</DIV>

<P><A NAME="snapshot/0"><STRONG><CODE>snapshot() -&#62; [Snapshot]</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Snapshot = {Pid, Function, Status, Info}</CODE></STRONG><BR>
<STRONG><CODE>Pid = pid()</CODE></STRONG><BR>
<STRONG><CODE>Function = {Module,Name,Args}</CODE></STRONG><BR>
<STRONG><CODE>Module = Name = atom()</CODE></STRONG><BR>
<STRONG><CODE>Args = [term()]</CODE></STRONG><BR>
<STRONG><CODE>Status = idle | running | waiting | break | exit
         | no_conn</CODE></STRONG><BR>
<STRONG><CODE>Info = {} | {Module,Line} | ExitReason</CODE></STRONG><BR>
<STRONG><CODE>Line = integer()</CODE></STRONG><BR>
<STRONG><CODE>ExitReason = term()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Gets information about all processes executing interpreted code.
        
<P>
<UL>

<LI>
<CODE>Pid</CODE> - process identifier.
</LI>


<LI>
<CODE>Function</CODE> - first interpreted function called by
         the process.
</LI>


<LI>
<CODE>Status</CODE> - current status of the process.
</LI>


<LI>
<CODE>Info</CODE> - additional information.
</LI>


</UL>

<P><CODE>Status</CODE> is one of:
<P>
<UL>

<LI>
<CODE>idle</CODE> - the process is no longer executing interpreted
         code. <CODE>Info={}</CODE>.
</LI>


<LI>
<CODE>running</CODE> - the process is running. <CODE>Info={}</CODE>.
         
</LI>


<LI>
<CODE>waiting</CODE> - the process is waiting at a <CODE>receive</CODE>.
         <CODE>Info={}</CODE>.
</LI>


<LI>
<CODE>break</CODE> - process execution has been stopped, normally
         at a breakpoint. <CODE>Info={Module,Line}</CODE>.
</LI>


<LI>
<CODE>exit</CODE> - the process has terminated.
         <CODE>Info=ExitReason</CODE>.
</LI>


<LI>
<CODE>no_conn</CODE> - the connection is down to the node where
         the process is running. <CODE>Info={}</CODE>.
</LI>


</UL>

</DIV>

<P><A NAME="clear/0"><STRONG><CODE>clear() -&#62; ok</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY>

<P>Clears information about processes executing interpreted code
         by removing all information about terminated processes.
</DIV>

<P><A NAME="continue/1"><STRONG><CODE>continue(Pid) -&#62; ok | {error,not_interpreted}</CODE></STRONG></A><BR>
<A NAME="continue/3"><STRONG><CODE>continue(X,Y,Z) -&#62; ok | {error,not_interpreted}</CODE></STRONG></A><BR>

<DIV CLASS=REFBODY><P>Types:
  <DIV CLASS=REFTYPES>
<P>
<STRONG><CODE>Pid = pid()</CODE></STRONG><BR>
<STRONG><CODE>X = Y = Z = integer()</CODE></STRONG><BR>

  </DIV>
</DIV>

<DIV CLASS=REFBODY>

<P>Resume process execution for <CODE>Pid</CODE>, or for
         <CODE>c:pid(X,Y,Z)</CODE>.
</DIV>

<H3>AUTHORS</H3>
<DIV CLASS=REFBODY>
Gunilla Arendt - support@erlang.ericsson.se<BR>

</DIV>
<CENTER>
<HR>
<SMALL>debugger 2.3<BR>
Copyright &copy; 1991-2004
<A HREF="http://www.erlang.se">Ericsson AB</A><BR>
</SMALL>
</CENTER>
</BODY>
</HTML>