From 2a43b90eadcbce8763c84d2692e89f5e7a1ec150 Mon Sep 17 00:00:00 2001 From: xsipewe Date: Mon, 14 Dec 2015 10:01:25 +0100 Subject: debugger: Editorial changes in documentation --- lib/debugger/doc/src/int.xml | 334 +++++++++++++++++++++++-------------------- 1 file changed, 176 insertions(+), 158 deletions(-) (limited to 'lib/debugger/doc/src/int.xml') 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 @@
- 19982013 + 19982016 Ericsson AB. All Rights Reserved. @@ -29,16 +29,16 @@
int - Interpreter Interface + Interpreter Interface.

The Erlang interpreter provides mechanisms for breakpoints and - stepwise execution of code. It is mainly intended to be used by - the Debugger, see Debugger User's Guide and - debugger(3).

+ stepwise execution of code. It is primarily intended to be used by + Debugger, see the User's Guide and + debugger(3).

-

From the shell, it is possible to:

- - Specify which modules should be interpreted. +

The following can be done from the shell:

+ + Specify the modules to be interpreted. Specify breakpoints. Monitor the current status of all processes executing code in interpreted modules, also processes at other Erlang nodes. @@ -48,45 +48,48 @@

By attaching to 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 int.erl for available functions and dbg_wx_trace.erl for possible messages.

-

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 +

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.

+ belonging to the Debugger application.
+ Breakpoints

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.

-

A breakpoint have a status, a trigger action and may have a - condition associated with it. The status is either active - or inactive. An inactive breakpoint is ignored. When a - breakpoint is reached, the trigger action specifies if - the breakpoint should continue to be active (enable), if - it should become inactive (disable), or if it should be - removed (delete). A condition is a tuple - {Module,Name}. When the breakpoint is reached, - Module:Name(Bindings) is called. If this evaluates to - true, execution will stop. If this evaluates to - false, the breakpoint is ignored. Bindings contains - the current variable bindings, use get_binding to retrieve - the value for a given variable.

+

A breakpoint has the following:

+ + A status, which is active or inactive. An + inactive breakpoint is ignored. + A trigger action. When a breakpoint is reached, the trigger + action specifies if the breakpoint is to continue as active + (enable), or to become inactive (disable), or + to be removed (delete). + Optionally an associated condition. A condition is a tuple + {Module,Name}. When the breakpoint is reached, + Module:Name(Bindings) is called. If it evaluates to + true, execution stops. If it evaluates to false, + the breakpoint is ignored. Bindings contains the current + variable bindings. To retrieve the value for a specified variable, + use get_binding. +

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.

+ enable, and has no associated condition. For details + about breakpoints, see the User's Guide.

@@ -95,7 +98,7 @@ i(AbsModules) -> ok ni(AbsModule) -> {module,Module} | error ni(AbsModules) -> ok - Interpret a module + Interpret a module. AbsModules = [AbsModule] AbsModule = Module | File | [Module | File] @@ -107,41 +110,43 @@ the module only at the current node. ni/1 interprets the module at all known nodes.

-

A module may be given by its module name (atom) or by its - file name. If given by its module name, the object code +

A module can be specified by its module name (atom) or + filename.

+ +

If specified by its module name, the object code Module.beam is searched for in the current path. The source code Module.erl is searched for first in - the same directory as the object code, then in a src + the same directory as the object code, then in an src directory next to it.

-

If given by its file name, the file name may include a path - and the .erl extension may be omitted. The object code +

If specified by its filename, the filename can include a path + and the .erl extension can be omitted. The object code Module.beam is searched for first in the same directory as the source code, then in an ebin directory next to it, and then in the current path.

-

The interpreter needs both the source code and the object - code, and the object code must include debug - information. That is, only modules compiled with the option +

The interpreter requires both the source code and the object + code. The object code must include debug + information, that is, only modules compiled with option debug_info set can be interpreted.

The functions returns {module,Module} if the module - was interpreted, or error if it was not.

+ was interpreted, otherwise error is returned.

-

The argument may also be a list of modules/file names, in +

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 ok, - but prints some information to stdout if a module could not be - interpreted.

+ specified earlier. The function then always returns ok, + but prints some information to stdout if a module + cannot be interpreted.

n(AbsModule) -> ok nn(AbsModule) -> ok - Stop interpreting a module + Stop interpreting a module. AbsModule = Module | File | [Module | File]  Module = atom() @@ -152,14 +157,14 @@ interpreting the module only at the current node. nn/1 stops interpreting the module at all known nodes.

-

As for i/1 and ni/1, a module may be given by - either its module name or its file name.

+

As for i/1 and ni/1, a module can be specified by + its module name or filename.

 interpreted() -> [Module] - Get all interpreted modules + Get all interpreted modules. Module = atom() @@ -170,20 +175,20 @@ file(Module) -> File | {error,not_loaded} - Get the file name for an interpreted module + Get the filename for an interpreted module. Module = atom() File = string() -

Returns the source code file name File for an +

Returns the source code filename File for an interpreted module Module.

 interpretable(AbsModule) -> true | {error,Reason} - Check if a module is possible to interpret + Check if a module can be interpreted. AbsModule = Module | File  Module = atom() @@ -193,45 +198,59 @@  App = atom() -

Checks if a module is possible to interpret. The module can - be given by its module name Module or its source file - name File. If given by a module name, the module is - searched for in the code path.

- -

The function returns true if both source code and - object code for the module is found, the module has been - compiled with the option debug_info set and does not - belong to any of the applications Kernel, STDLIB, GS or - Debugger itself.

- -

The function returns {error,Reason} if the module for - some reason is not possible to interpret.

- -

Reason is no_src if no source code is found or - no_beam if no object code is found. It is assumed that - the source- and object code are located either in the same - directory, or in src and ebin directories next - to each other.

- -

Reason is no_debug_info if the module has not - been compiled with the option debug_info set.

- -

Reason is badarg if AbsModule is not - found. This could be because the specified file does not - exist, or because code:which/1 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.

- -

Reason is {app,App} where App is - kernel, stdlib, gs or debugger if - AbsModule belongs to one of these applications.

- -

Note that the function can return true for a module - which in fact is not interpretable in the case where +

Checks if a module can be interpreted. The module can be + specified by its module name Module or its source + filename File. If specified by a module name, the module + is searched for in the code path.

+ +

The function returns true if all of the following + apply:

+ + Both source code and object code for the module is + found. + The module has been compiled with option debug_info + set. + The module does not belong to any of the applications + Kernel, STDLIB, GS, or Debugger. + + +

The function returns {error,Reason} if the module cannot + be interpreted. Reason can have the following values:

+ + no_src +

No source code is found. + It is assumed that the source code and object code are located + either in the same directory, or in src and ebin + directories next to each other.

 + + no_beam +

No object code is found. + It is assumed that the source code and object code are located + either in the same directory, or in src and ebin + directories next to each other.

 + + no_debug_info +

The module has not been compiled with option + debug_info set.

 + + badarg +

AbsModule is not found. This could be because + the specified file does not exist, or because + code:which/1 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.

 + + {app,App} +

App is kernel, stdlib, gs, + or debugger if AbsModule belongs to one of these + applications.

 + + +

Notice that the function can return true 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.

+ marked as sticky. The reason is that this is not discovered + until the interpreter tries to load the module.

 @@ -239,7 +258,7 @@ auto_attach() -> false | {Flags,Function} auto_attach(false) auto_attach(Flags, Function) - Get/set when and how to attach to a process + Get and set when and how to attach to a process. Flags = [init | break | exit] Function = {Module,Name,Args} @@ -247,24 +266,24 @@  Args = [term()] -

Gets and sets when and how to automatically attach to a +

Gets and sets when and how to attach automatically to a process executing code in interpreted modules. false - 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:

- - init - attach when a process for the very first + a function. The following flags can be specified:

+ + init - Attach when a process for the first time calls an interpreted function. - break - attach whenever a process reaches a + break - Attach whenever a process reaches a breakpoint. - exit - attach when a process terminates. + exit - Attach when a process terminates.

When the specified event occurs, the function Function - will be called as:

+ is called as:

-spawn(Module, Name, [Pid | Args])
-
+spawn(Module, Name, [Pid | Args]) +

Pid is the pid of the process executing interpreted code.

 @@ -273,7 +292,7 @@ spawn(Module, Name, [Pid | Args]) stack_trace() -> Flag stack_trace(Flag) - Get/set if and how to save call frames + Get and set if and how to save call frames. Flag = all | no_tail | false @@ -281,25 +300,30 @@ spawn(Module, Name, [Pid | Args])

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.

- - all - save information about all current calls, - that is, function calls that have not yet returned a value. - - no_tail - save information about current calls, + error (an exception of class error) occurs. The following + flags can be specified:

+ + all +

Save information about all current calls, + that is, function calls that have not yet returned a value.

+ + + no_tail +

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. - false - do not save any information about current - calls. - + tail recursive calls. This is the default.

 + + false +

Save no information about currentcalls.

 + break(Module, Line) -> ok | {error,break_exists} - Create a breakpoint + Create a breakpoint. Module = atom() Line = int() @@ -311,86 +335,80 @@ spawn(Module, Name, [Pid | Args]) delete_break(Module, Line) -> ok - Delete a breakpoint + Delete a breakpoint. Module = atom() Line = int() -

Deletes the breakpoint located at Line in - Module.

+

Deletes the breakpoint at Line in Module.

 break_in(Module, Name, Arity) -> ok | {error,function_not_found} - Create breakpoints in the specified function + Create breakpoints in the specified function. Module = Name = atom() Arity = int()

Creates a breakpoint at the first line of every clause of - the Module:Name/Arity function.

+ function Module:Name/Arity.

 del_break_in(Module, Name, Arity) -> ok | {error,function_not_found} - Delete breakpoints from the specified function - + Delete breakpoints from the specified function. Module = Name = atom() Arity = int()

Deletes the breakpoints at the first line of every clause of - the Module:Name/Arity function. -

+ function Module:Name/Arity.

 no_break() -> ok no_break(Module) -> ok - Delete all breakpoints + Delete all breakpoints. -

Deletes all breakpoints, or all breakpoints in Module. -

+

Deletes all breakpoints, or all breakpoints in Module.

 disable_break(Module, Line) -> ok - Make a breakpoint inactive + Make a breakpoint inactive. Module = atom() Line = int() -

Makes the breakpoint at Line in Module - inactive.

+

Makes the breakpoint at Line in Module inactive.

 enable_break(Module, Line) -> ok - Make a breakpoint active + Make a breakpoint active. Module = atom() Line = int() -

Makes the breakpoint at Line in Module active. -

+

Makes the breakpoint at Line in Module active.

 action_at_break(Module, Line, Action) -> ok - Set the trigger action of a breakpoint + Set the trigger action of a breakpoint. Module = atom() Line = int() @@ -404,7 +422,7 @@ spawn(Module, Name, [Pid | Args]) test_at_break(Module, Line, Function) -> ok - Set the conditional test of a breakpoint + Set the conditional test of a breakpoint. Module = atom() Line = int() @@ -414,14 +432,14 @@ spawn(Module, Name, [Pid | Args])

Sets the conditional test of the breakpoint at Line in Module to Function. The function must - fulfill the requirements specified in the section - Breakpoints above.

+ fulfill the requirements specified in section + Breakpoints.

 get_binding(Var, Bindings) -> {value,Value} | unbound - Retrieve a variable binding + Retrieve a variable binding. Var = atom() Bindings = term() @@ -437,7 +455,7 @@ spawn(Module, Name, [Pid | Args]) all_breaks() -> [Break] all_breaks(Module) -> [Break] - Get all breakpoints + Get all breakpoints. Break = {Point,Options}  Point = {Module,Line} @@ -451,15 +469,14 @@ spawn(Module, Name, [Pid | Args])     Name = atom() -

Gets all breakpoints, or all breakpoints in Module. -

+

Gets all breakpoints, or all breakpoints in Module.

 snapshot() -> [Snapshot] Get information about all processes executing interpreted - code + code. Snapshot = {Pid, Function, Status, Info}  Pid = pid() @@ -475,26 +492,27 @@ spawn(Module, Name, [Pid | Args])

Gets information about all processes executing interpreted code.

- - Pid - process identifier. - Function - first interpreted function called by + + Pid - Process identifier. + Function - First interpreted function called by the process. - Status - current status of the process. - Info - additional information. + Status - Current status of the process. + Info - More information. -

Status is one of:

- - idle - the process is no longer executing + +

Status is one of the following:

+ + idle - The process is no longer executing interpreted code. Info={}. - running - the process is running. Info={}. + running - The process is running. Info={}. - waiting - the process is waiting at a + waiting - The process is waiting at a receive. Info={}. - break - process execution has been stopped, + break - Process execution is stopped, normally at a breakpoint. Info={Module,Line}. - exit - the process has terminated. + exit - The process is terminated. Info=ExitReason. - no_conn - the connection is down to the node + no_conn - The connection is down to the node where the process is running. Info={}. @@ -503,7 +521,7 @@ spawn(Module, Name, [Pid | Args]) clear() -> ok Clear information about processes executing interpreted - code + code.

Clears information about processes executing interpreted code by removing all information about terminated processes.

@@ -513,13 +531,13 @@ spawn(Module, Name, [Pid | Args]) continue(Pid) -> ok | {error,not_interpreted} continue(X,Y,Z) -> ok | {error,not_interpreted} - Resume process execution + Resume process execution. Pid = pid() X = Y = Z = int() -

Resume process execution for Pid, or for +

Resumes process execution for Pid or c:pid(X,Y,Z).

 -- cgit v1.2.3