diff options
Diffstat (limited to 'lib/debugger/doc/src/int.xml')
| -rw-r--r-- | lib/debugger/doc/src/int.xml | 334 |
1 files changed, 176 insertions, 158 deletions
diff --git a/lib/debugger/doc/src/int.xml b/lib/debugger/doc/src/int.xml index ea21d04a07..31e9dfe923 100644 --- a/lib/debugger/doc/src/int.xml +++ b/lib/debugger/doc/src/int.xml @@ -4,7 +4,7 @@ <erlref> <header> <copyright> - <year>1998</year><year>2013</year> + <year>1998</year><year>2016</year> <holder>Ericsson AB. All Rights Reserved.</holder> </copyright> <legalnotice> @@ -29,16 +29,16 @@ <rev></rev> </header> <module>int</module> - <modulesummary>Interpreter Interface</modulesummary> + <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> + stepwise execution of code. It is primarily intended to be used by + Debugger, see the User's Guide and + <seealso marker="debugger"><c>debugger(3)</c></seealso>.</p> - <p>From the shell, it is possible to:</p> - <list> - <item>Specify which modules should be interpreted.</item> + <p>The following can be done from the shell:</p> + <list type="bulleted"> + <item>Specify the modules to 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. @@ -48,45 +48,48 @@ <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 + to/from the process through a third process, called the meta + process. You can implement your own attached process. See <c>int.erl</c> for available functions and <c>dbg_wx_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 + <p>The interpreter depends on the Kernel, STDLIB, and + GS applications. This means that 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> + belonging to the Debugger application.</p> </description> <section> + <marker id="int_breakpoints"/> <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 + stops. This means that a breakpoint must be set at an + executable line, that is, a code line 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>A breakpoint has the following:</p> + <list type="bulleted"> + <item>A status, which is <em>active</em> or <em>inactive</em>. An + inactive breakpoint is ignored.</item> + <item>A trigger action. When a breakpoint is reached, the trigger + action specifies if the breakpoint is to continue as active + (<em>enable</em>), or to become inactive (<em>disable</em>), or + to be removed (<em>delete</em>).</item> + <item>Optionally an associated condition. A condition is a tuple + <c>{Module,Name}</c>. When the breakpoint is reached, + <c>Module:Name(Bindings)</c> is called. If it evaluates to + <c>true</c>, execution stops. If it evaluates to <c>false</c>, + the breakpoint is ignored. <c>Bindings</c> contains the current + variable bindings. To retrieve the value for a specified variable, + use <c>get_binding</c>.</item> + </list> <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> + <c>enable</c>, and has no associated condition. For details + about breakpoints, see the User's Guide.</p> </section> <funcs> @@ -95,7 +98,7 @@ <name>i(AbsModules) -> ok</name> <name>ni(AbsModule) -> {module,Module} | error</name> <name>ni(AbsModules) -> ok</name> - <fsummary>Interpret a module</fsummary> + <fsummary>Interpret a module.</fsummary> <type> <v>AbsModules = [AbsModule]</v> <v>AbsModule = Module | File | [Module | File]</v> @@ -107,41 +110,43 @@ 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 + <p>A module can be specified by its module name (atom) or + filename.</p> + + <p>If specified 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> + the same directory as the object code, then in an <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 + <p>If specified by its filename, the filename can include a path + and the <c>.erl</c> extension can 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 + <p>The interpreter requires both the source code and the object + code. The object code <em>must</em> include debug + information, that is, only modules compiled with 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> + was interpreted, otherwise <c>error</c> is returned.</p> - <p>The argument may also be a list of modules/file names, in + <p>The argument can also be a list of modules or filenames, 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> + specified earlier. The function then always returns <c>ok</c>, + but prints some information to <c>stdout</c> if a module + cannot be interpreted.</p> </desc> </func> <func> <name>n(AbsModule) -> ok</name> <name>nn(AbsModule) -> ok</name> - <fsummary>Stop interpreting a module</fsummary> + <fsummary>Stop interpreting a module.</fsummary> <type> <v>AbsModule = Module | File | [Module | File]</v> <v> Module = atom()</v> @@ -152,14 +157,14 @@ 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> + <p>As for <c>i/1</c> and <c>ni/1</c>, a module can be specified by + its module name or filename.</p> </desc> </func> <func> <name>interpreted() -> [Module]</name> - <fsummary>Get all interpreted modules</fsummary> + <fsummary>Get all interpreted modules.</fsummary> <type> <v>Module = atom()</v> </type> @@ -170,20 +175,20 @@ <func> <name>file(Module) -> File | {error,not_loaded}</name> - <fsummary>Get the file name for an interpreted module</fsummary> + <fsummary>Get the filename 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 + <p>Returns the source code filename <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> + <fsummary>Check if a module can be interpreted.</fsummary> <type> <v>AbsModule = Module | File</v> <v> Module = atom()</v> @@ -193,45 +198,59 @@ <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 + <p>Checks if a module can be interpreted. The module can be + specified by its module name <c>Module</c> or its source + filename <c>File</c>. If specified by a module name, the module + is searched for in the code path.</p> + + <p>The function returns <c>true</c> if all of the following + apply:</p> + <list type="bulleted"> + <item>Both source code and object code for the module is + found.</item> + <item>The module has been compiled with option <c>debug_info</c> + set.</item> + <item>The module does not belong to any of the applications + Kernel, STDLIB, GS, or Debugger.</item> + </list> + + <p>The function returns <c>{error,Reason}</c> if the module cannot + be interpreted. <c>Reason</c> can have the following values:</p> + <taglist> + <tag><c>no_src</c></tag> + <item><p>No source code is found. + It is assumed that the source code 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></item> + + <tag><c>no_beam</c></tag> + <item><p>No object code is found. + It is assumed that the source code 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></item> + + <tag><c>no_debug_info</c></tag> + <item><p>The module has not been compiled with option + <c>debug_info</c> set.</p></item> + + <tag><c>badarg</c></tag> + <item><p><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 filename, + which is the case not only for non-existing modules but also + for modules that are preloaded or cover-compiled.</p></item> + + <tag><c>{app,App}</c></tag> + <item><p><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></item> + </taglist> + + <p>Notice that the function can return <c>true</c> for a module + that 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> + marked as sticky. The reason is that this is not discovered + until the interpreter tries to load the module.</p> </desc> </func> @@ -239,7 +258,7 @@ <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> + <fsummary>Get and set when and how to attach to a process.</fsummary> <type> <v>Flags = [init | break | exit]</v> <v>Function = {Module,Name,Args}</v> @@ -247,24 +266,24 @@ <v> Args = [term()]</v> </type> <desc> - <p>Gets and sets when and how to automatically attach to a + <p>Gets and sets when and how to attach automatically to a process executing code in interpreted modules. <c>false</c> - means never automatically attach, this is the default. + means never attach automatically, 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 + a function. The following flags can be specified:</p> + <list type="bulleted"> + <item><c>init</c> - Attach when a process for the first time calls an interpreted function.</item> - <item><c>break</c> - attach whenever a process reaches a + <item><c>break</c> - Attach whenever a process reaches a breakpoint.</item> - <item><c>exit</c> - attach when a process terminates.</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> + is called as:</p> <pre> -spawn(Module, Name, [Pid | Args]) - </pre> +spawn(Module, Name, [Pid | Args])</pre> + <p><c>Pid</c> is the pid of the process executing interpreted code.</p> </desc> @@ -273,7 +292,7 @@ spawn(Module, Name, [Pid | Args]) <func> <name>stack_trace() -> Flag</name> <name>stack_trace(Flag)</name> - <fsummary>Get/set if and how to save call frames</fsummary> + <fsummary>Get and set if and how to save call frames.</fsummary> <type> <v>Flag = all | no_tail | false</v> </type> @@ -281,25 +300,30 @@ spawn(Module, Name, [Pid | Args]) <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. - </item> - <item><c>no_tail</c> - save information about current calls, + error (an exception of class error) occurs. The following + flags can be specified:</p> + <taglist> + <tag><c>all</c></tag> + <item><p>Save information about all current calls, + that is, function calls that have not yet returned a value.</p> + </item> + + <tag><c>no_tail</c></tag> + <item><p>Save information about current calls, but discard previous information when a tail recursive call - is made. This option consumes less memory and may be + is made. This option consumes less memory and can be necessary to use for processes with long lifetimes and many - tail recursive calls. This is the default.</item> - <item><c>false</c> - do not save any information about current - calls.</item> - </list> + tail recursive calls. This is the default.</p></item> + + <tag><c>false</c></tag> + <item><p>Save no information about currentcalls.</p></item> + </taglist> </desc> </func> <func> <name>break(Module, Line) -> ok | {error,break_exists}</name> - <fsummary>Create a breakpoint</fsummary> + <fsummary>Create a breakpoint.</fsummary> <type> <v>Module = atom()</v> <v>Line = int()</v> @@ -311,86 +335,80 @@ spawn(Module, Name, [Pid | Args]) <func> <name>delete_break(Module, Line) -> ok</name> - <fsummary>Delete a breakpoint</fsummary> + <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> + <p>Deletes the breakpoint 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> + <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> + function <c>Module:Name/Arity</c>.</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> + <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> + function <c>Module:Name/Arity</c>.</p> </desc> </func> <func> <name>no_break() -> ok</name> <name>no_break(Module) -> ok</name> - <fsummary>Delete all breakpoints</fsummary> + <fsummary>Delete all breakpoints.</fsummary> <desc> - <p>Deletes all breakpoints, or all breakpoints in <c>Module</c>. - </p> + <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> + <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> + <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> + <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> + <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> + <fsummary>Set the trigger action of a breakpoint.</fsummary> <type> <v>Module = atom()</v> <v>Line = int()</v> @@ -404,7 +422,7 @@ spawn(Module, Name, [Pid | Args]) <func> <name>test_at_break(Module, Line, Function) -> ok</name> - <fsummary>Set the conditional test of a breakpoint</fsummary> + <fsummary>Set the conditional test of a breakpoint.</fsummary> <type> <v>Module = atom()</v> <v>Line = int()</v> @@ -414,14 +432,14 @@ spawn(Module, Name, [Pid | Args]) <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> + fulfill the requirements specified in section + <seealso marker="#int_breakpoints">Breakpoints</seealso>.</p> </desc> </func> <func> <name>get_binding(Var, Bindings) -> {value,Value} | unbound</name> - <fsummary>Retrieve a variable binding</fsummary> + <fsummary>Retrieve a variable binding.</fsummary> <type> <v>Var = atom()</v> <v>Bindings = term()</v> @@ -437,7 +455,7 @@ spawn(Module, Name, [Pid | Args]) <func> <name>all_breaks() -> [Break]</name> <name>all_breaks(Module) -> [Break]</name> - <fsummary>Get all breakpoints</fsummary> + <fsummary>Get all breakpoints.</fsummary> <type> <v>Break = {Point,Options}</v> <v> Point = {Module,Line}</v> @@ -451,15 +469,14 @@ spawn(Module, Name, [Pid | Args]) <v> Name = atom()</v> </type> <desc> - <p>Gets all breakpoints, or all breakpoints in <c>Module</c>. - </p> + <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> + code.</fsummary> <type> <v>Snapshot = {Pid, Function, Status, Info}</v> <v> Pid = pid()</v> @@ -475,26 +492,27 @@ spawn(Module, Name, [Pid | Args]) <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 + <list type="bulleted"> + <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> + <item><c>Status</c> - Current status of the process.</item> + <item><c>Info</c> - More information.</item> </list> - <p><c>Status</c> is one of:</p> - <list> - <item><c>idle</c> - the process is no longer executing + + <p><c>Status</c> is one of the following:</p> + <list type="bulleted"> + <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><c>running</c> - The process is running. <c>Info={}</c>. </item> - <item><c>waiting</c> - the process is waiting at a + <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, + <item><c>break</c> - Process execution is stopped, normally at a breakpoint. <c>Info={Module,Line}</c>.</item> - <item><c>exit</c> - the process has terminated. + <item><c>exit</c> - The process is terminated. <c>Info=ExitReason</c>.</item> - <item><c>no_conn</c> - the connection is down to the node + <item><c>no_conn</c> - The connection is down to the node where the process is running. <c>Info={}</c>.</item> </list> </desc> @@ -503,7 +521,7 @@ spawn(Module, Name, [Pid | Args]) <func> <name>clear() -> ok</name> <fsummary>Clear information about processes executing interpreted - code</fsummary> + code.</fsummary> <desc> <p>Clears information about processes executing interpreted code by removing all information about terminated processes.</p> @@ -513,13 +531,13 @@ spawn(Module, Name, [Pid | Args]) <func> <name>continue(Pid) -> ok | {error,not_interpreted}</name> <name>continue(X,Y,Z) -> ok | {error,not_interpreted}</name> - <fsummary>Resume process execution</fsummary> + <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 + <p>Resumes process execution for <c>Pid</c> or <c>c:pid(X,Y,Z)</c>.</p> </desc> </func> |