7.10.4 Browsing commands

vars

Prints the names of all the known variables in the current environment, together with an ordinal number for each variable.

held_vars

Prints the names of all the held variables.

print [-fpv] name[termpath]

print [-fpv] num[termpath]

Prints the value of the variable in the current environment with the given name, or with the given ordinal number. If the name or number is followed by a term path such as "^2", then only the specified subterm of the given variable is printed. This is a non-interactive version of the ‘browse’ command (see below). Various settings which affect the way that terms are printed out (including e.g. the maximum term depth) can be set using the ‘format_param’ command.

The options ‘-f’ or ‘--flat’, ‘-p’ or ‘--pretty’, and ‘-v’ or ‘--verbose’ specify the format to use for printing.

print [-fpv] *

Prints the values of all the known variables in the current environment.

The options ‘-f’ or ‘--flat’, ‘-p’ or ‘--pretty’, and ‘-v’ or ‘--verbose’ specify the format to use for printing.

print [-fpv]

print [-fpv] goal

Prints the goal of the current call in its present state of instantiation.

The options ‘-f’ or ‘--flat’, ‘-p’ or ‘--pretty’, and ‘-v’ or ‘--verbose’ specify the format to use for printing.

print [-fpv] exception

Prints the value of the exception at an EXCP port. Reports an error if the current event does not refer to such a port.

The options ‘-f’ or ‘--flat’, ‘-p’ or ‘--pretty’, and ‘-v’ or ‘--verbose’ specify the format to use for printing.

print [-fpv] action num

Prints a representation of the num'th I/O action executed by the program.

The options ‘-f’ or ‘--flat’, ‘-p’ or ‘--pretty’, and ‘-v’ or ‘--verbose’ specify the format to use for printing.

browse [-fpvx] name[termpath]

browse [-fpvx] num[termpath]

Invokes an interactive term browser to browse the value of the variable in the current environment with the given ordinal number or with the given name. If the name or number is followed by a term path such as "^2", then only the specified subterm of the given variable is given to the browser.

The interactive term browser allows you to selectively examine particular subterms. The depth and size of printed terms may be controlled. The displayed terms may also be clipped to fit within a single screen.

The options ‘-f’ or ‘--flat’, ‘-p’ or ‘--pretty’, and ‘-v’ or ‘--verbose’ specify the format to use for browsing. The ‘-x’ or ‘--xml’ option tells mdb to dump the value of the variable to an XML file and then invoke an XML browser on the file. The XML filename as well as the command to invoke the XML browser can be set using the ‘set’ command. See the documentation for ‘set’ for more details.

For further documentation on the interactive term browser, invoke the ‘browse’ command from within ‘mdb’ and then type ‘help’ at the ‘browser>’ prompt.

browse [-fpvx]

browse [-fpvx] goal

Invokes the interactive term browser to browse the goal of the current call in its present state of instantiation.

The options ‘-f’ or ‘--flat’, ‘-p’ or ‘--pretty’, and ‘-v’ or ‘--verbose’ specify the format to use for browsing. The ‘-x’ or ‘--xml’ option tells mdb to dump the goal to an XML file and then invoke an XML browser on the file. The XML filename as well as the command to invoke the XML browser can be set using the ‘set’ command. See the documentation for ‘set’ for more details.

browse [-fpvx] exception

Invokes the interactive term browser to browse the value of the exception at an EXCP port. Reports an error if the current event does not refer to such a port.

The options ‘-f’ or ‘--flat’, ‘-p’ or ‘--pretty’, and ‘-v’ or ‘--verbose’ specify the format to use for browsing. The ‘-x’ or ‘--xml’ option tells mdb to dump the exception to an XML file and then invoke an XML browser on the file. The XML filename as well as the command to invoke the XML browser can be set using the ‘set’ command. See the documentation for ‘set’ for more details.

browse [-fpvx] action num

Invokes an interactive term browser to browse a representation of the num'th I/O action executed by the program.

The options ‘-f’ or ‘--flat’, ‘-p’ or ‘--pretty’, and ‘-v’ or ‘--verbose’ specify the format to use for browsing. The ‘-x’ or ‘--xml’ option tells mdb to dump the io action representation to an XML file and then invoke an XML browser on the file. The XML filename as well as the command to invoke the XML browser can be set using the ‘set’ command. See the documentation for ‘set’ for more details.

stack [-a] [-d] [-ccliquelines] [-fnumframes] [numlines]

Prints the names of the ancestors of the call specified by the current event. If two or more consecutive ancestor calls are for the same procedure, the procedure identification will be printed once with the appropriate multiplicity annotation.

The option ‘-d’ or ‘--detailed’ specifies that for each ancestor call, the call's event number, sequence number and depth should also be printed if the call is to a procedure that is being execution traced.

If the ‘-f’ option, if present, specifies that only the topmost numframes stack frames should be printed.

The optional number numlines, if present, specifies that only the topmost numlines lines should be printed. The default value is 100; the special value 0 asks for all the lines to be printed.

By default, this command will look for cliques of mutually recursive ancestors. It will identify them as such in the output, and it will print at most 10 lines from any clique. The ‘-c’ option can be used to specify the maximum number of lines to print for a clique, with the special value 0 asking for all of them to be printed. The option ‘-a’ asks for all lines to be printed without cliques being detected or marked.

This command will report an error if there is no stack trace information available about any ancestor.

up [-d] [num]

Sets the current environment to the stack frame of the num'th level ancestor of the current environment (the immediate caller is the first-level ancestor).

If num is not specified, the default value is one.

This command will report an error if the current environment doesn't have the required number of ancestors, or if there is no execution trace information about the requested ancestor, or if there is no stack trace information about any of the ancestors between the current environment and the requested ancestor.

The option ‘-d’ or ‘--detailed’ specifies that for each ancestor call, the call's event number, sequence number and depth should also be printed if the call is to a procedure that is being execution traced.

down [-d] [num]

Sets the current environment to the stack frame of the num'th level descendant of the current environment (the procedure called by the current environment is the first-level descendant).

If num is not specified, the default value is one.

This command will report an error if there is no execution trace information about the requested descendant.

The option ‘-d’ or ‘--detailed’ specifies that for each ancestor call, the call's event number, sequence number and depth should also be printed if the call is to a procedure that is being execution traced.

level [-d]

level [-d] num

level [-d] (‘clentry’|‘clique’)

level [-d] ‘clparent’

If the command is given no arguments, it sets the current environment to the stack frame that belongs to the current event. If invoked with the number num as argument, it sets the current environment to the stack frame of the num'th level ancestor of the call to which the current event belongs. If invoked with the argument ‘clentry’ or ‘clique’, it sets the current environment to the stack frame of the call that first entered into the clique of recursive calls of which the current call is a part. (If the current call is not (mutually) recursive with any other currently active call, it sets the current environment to the stack frame of the current event.) If the command is given the argument ‘clparent’, it sets the current environment to the stack frame of the first call outside the current call's clique. This will be the parent of the stack frame that ‘level clentry’ would set the current environment to.

This command will report an error if the current environment doesn't have the required number of ancestors, or if there is no execution trace information about the requested ancestor, or if there is no stack trace information about any of the ancestors between the current environment and the requested ancestor.

The option ‘-d’ or ‘--detailed’ specifies that for each ancestor call, the call's event number, sequence number and depth should also be printed if the call is to a procedure that is being execution traced.

current

Prints the current event. This is useful if the details of the event, which were printed when control arrived at the event, have since scrolled off the screen.

view [-vf2] [-w window-cmd] [-s server-cmd] [-n server-name] [-t timeout]

view -c [-v] [-s server-cmd] [-n server-name]

Opens a new window displaying the source code, at the location of the current event. As mdb stops at new events, the window is updated to track through the source code. This requires X11 and a version of ‘vim’ compiled with the client/server option enabled.

The debugger only updates one window at a time. If you try to open a new source window when there is already one open, this command aborts with an error message.

The variant with ‘-c’ (or ‘--close’) does not open a new window but instead attempts to close a currently open source window. The attempt may fail if, for example, the user has modified the source file without saving.

The option ‘-v’ (or ‘--verbose’) prints the underlying system calls before running them, and prints any output the calls produced. This is useful to find out what is wrong if the server does not start.

The option ‘-f’ (or ‘--force’) stops the command from aborting if there is already a window open. Instead it attempts to close that window first.

The option ‘-2’ (or ‘--split-screen’) starts the vim server with two windows, which allows both the callee as well as the caller to be displayed at interface events. The lower window shows what would normally be seen if the split-screen option was not used, which at interface events is the caller. At these events, the upper window shows the callee definition. At internal events, the lower window shows the associated source, and the view in the upper window (which is not interesting at these events) remains unchanged.

The option ‘-w’ (or ‘--window-command’) specifies the command to open a new window. The default is ‘xterm -e’.

The option ‘-s’ (or ‘--server-command’) specifies the command to start the server. The default is ‘vim’.

The option ‘-n’ (or ‘--server-name’) specifies the name of an existing server. Instead of starting up a new server, mdb will attempt to connect to the existing one.

The option ‘-t’ (or ‘--timeout’) specifies the maximum number of seconds to wait for the server to start.

hold name[termpath] [heldname]

Holds on to the variable name of the current event, or the part of the specified by termpath, even after execution leaves the current event. The held value will stay accessible via the name $heldname. If heldname is not specified, it defaults to name. There must not already be a held variable named heldname.

diff [-s start] [-m max] name1[termpath1] name2[termpath2]

Prints a list of some of the term paths at which the (specified parts of) the specified terms differ. Normally this command prints the term paths of the first 20 differences.

The option ‘-s’ (or ‘--start’), if present, specifies how many of the initial differences to skip.

The option ‘-m’ (or ‘--max’), if present, specifies how many differences to print.

dump [-qx] goal filename

Writes the goal of the current call in its present state of instantiation to the specified file, and outputs a message announcing this fact unless the option ‘-q’ (or ‘--quiet’) was given. The option ‘-x’ (or ‘--xml’) causes the output to be in XML.

dump [-qx] exception filename

Writes the value of the exception at an EXCP port to the specified file, and outputs a message announcing this fact unless the option ‘-q’ (or ‘--quiet’) was given. Reports an error if the current event does not refer to such a port. The option ‘-x’ (or ‘--xml’) causes the output to be in XML.

dump [-qx] name filename

dump [-qx] num filename

Writes the value of the variable in the current environment with the given ordinal number or with the given name to the specified file, and outputs a message announcing this fact unless the option ‘-q’ (or ‘--quiet’) was given. The option ‘-x’ (or ‘--xml’) causes the output to be in XML.

open term

Save term to a temporary file and open the file in an editor. The environment variable EDITOR is consulted to determine what editor to use. If this environment variable is not set then ‘vi’ is used. term may be any term that can be saved to a file with the ‘save_to_file’ command.

grep pattern term

Saves the given term to a temporary file and invokes grep on the file using pattern. term may be any term that can be saved to a file with the ‘save_to_file’ command. The unix `grep' command must be available from the shell for this command to work.

list [num]

Lists the source code text for the current environment, including num preceding and following lines. If num is not provided then the default of two is used.