dbXtra and dbxtra

Events menu: managing execution time events

The Events menu accesses various commands associated with creating, removing and querying breakpoint and trace events.

Events

[dbxtra command: status]
Displays the currently active events (breakpoints, trace expressions, and so on).

Call

[dbxtra command: call function(arguments)]
Executes the object code associated with a named function, passing arguments to it at the same time. The number and types of arguments must match, except when $unsafecall is set. Execution of the function halts if any breakpoints are encountered, and dbXtra reenters the command level.

When

[dbxtra command: when arguments]
Executes one or more dbXtra commands whenever one of the following events occurs during the execution of the program being debugged:

A particular source line is reached.
A function is called.
A variable is accessed or changed.
Some condition is now true.

The simplest form executes commands depending on some arbitrary condition:

when [inst] condition { command ; [ command ; ... ] }

Before each statement is executed, condition is evaluated and if it is true, the specified command(s) are executed. If the inst keyword is specified, then condition is evaluated before each instruction is executed. If a debug register is available, it monitors the state of the condition.

when at line-number [if condition] { command-list }
when inst at address [if condition] { command-list }

The first form of this command causes the specified command(s) to be executed whenever line-number line is executed. The second form causes the command(s) to be executed whenever the instruction at the specified address is executed.

In both cases, if the optional if clause is specified, the condition is evaluated before the specified line-number or address is executed, and the command(s) are executed only when the condition evaluates to true.

when in routine [if condition] { command ; [ command ; ... ] }

The specified command(s) are executed before the first statement in routine is executed. If the optional if clause is specified, then condition is evaluated and the command(s) are executed only if the condition evaluates to true.

when [inst] change variable [if condition] { command-list }
when [inst] change address [if condition] { command-list }

If the first form is used, the specified commands are executed whenever the contents of the specified variable are modified. If the second form is used, the commands are executed whenever any of the four bytes starting at address are modified.

In either case, if the inst keyword is specified, the commands are executed before the next instruction (as opposed to the next statement) is executed.

If a debug register is available, it monitors changes to the specified variable or address. Otherwise, the contents of variable or address are monitored after each statement (or instruction) is executed.

when [inst] access variable [if condition] { command-list }
when [inst] access address [if condition] { command-list }

If the first form is used, the specified commands are executed whenever the contents of variable are accessed. If the second form is used, the commands are executed whenever any of the four bytes starting at address are accessed.

In either case, if the inst keyword is specified, the commands are executed before the next instruction (as opposed to the next statement) is executed.

NOTE: This format for the when command can only be used if a debug register is available. If no debug registers are available, an error message is reported and the commands do not have any effect.

Stop

[dbxtra command: stop arguments] Sets breakpoints within a program. Submenu provides access to the various modes of the stop commands, which cause program execution to stop depending on whether:

A particular source line is reached.
A function is called.
A variable is accessed or changed.
Some condition is now true.

The syntax for the simplest form is:

stop [inst] if condition

This command stops the execution of the program being debugged before the next statement is executed whenever the Boolean condition specified evaluates to true. If the inst keyword is used, then execution stops before the next machine instruction is executed.

If a 386 debug register is available, it monitors execution. Otherwise, the Boolean condition is evaluated after each statement or instruction has been executed.

The next two forms allow for specific locations where execution is to be stopped:

stop at line-number [if condition]
stop inst at address [if condition]

If the first form is used, then execution of the debugged program stops before the statement on line line-number is executed. If the second form is used, then execution stops before the instruction at the specified address is executed.

If the optional if clause is used, then when execution reaches the specified line or address, the condition specified is evaluated and, if it evaluates to true, execution stops.

stop [inst] in routine [if condition]

Through this variant, the execution of the program being debugged stops before the first statement in the specified routine is executed. If the inst keyword is used, then execution stops before the first instruction in the specified routine is executed.

NOTE: The first instruction is typically in the prologue section of the routine and may not correspond to the first instruction in the program source.

In either case, if the optional if clause is used, then the condition is evaluated before the first instruction or statement is executed, and the execution is stopped only if the condition evaluates to true.

stop [inst] [change] variable [if condition]
stop [inst] [change] address [if condition]

The execution of the program being debugged stops whenever the contents of variable are modified. If address is specified instead of variable, it is interpreted as an address in the data section of the program, in which case execution stops whenever any of the four bytes starting at that address are modified.

If the inst keyword is specified, then execution stops before the next instruction is executed (instead of before the next statement is executed). The change keyword is included for the sake of consistency with the other variants of the stop command, and its inclusion does not alter the behavior described.

In either case, if the optional if clause is used, then the specified condition is evaluated whenever the contents of the variable or memory location are modified, and execution stops only if the condition evaluates to true.

If a 386 debug register is available, it monitors execution. Otherwise, variable or memory locations are tested after each instruction or statement (depending on whether the inst keyword was specified) to determine if execution should be stopped.

stop [inst] access variable [if condition]
stop [inst] access address [if condition]

The execution of the program being debugged stops whenever the contents of variable are accessed.[1] If address is specified instead of variable, it is interpreted as an address in the data section of the program, in which case execution stops whenever any of the four bytes starting at that address are accessed.

If the inst keyword is specified, then execution stops before the next instruction is executed (instead of before the next statement is executed).

NOTE: This command is only accepted if a 386 hardware debug register is available. If no such registers are available, an error message is displayed. To free up a debug register, you have to cancel a command that has been allocated a debug register. The status command can list all the commands that are active.

Footnotes

[1]: This command is also triggered when variables are modified since variables have to be accessed to be modified.

Trace

[dbxtra command: trace arguments]
Submenu provides access to the various modes of the trace commands, which can have dbXtra display diagnostic messages whenever one of the following events occurs during the execution of the program being debugged:

A particular source line is reached.
A function is called.
A variable is accessed or changed.
Some condition is now true.

As these commands continuously update the source window and/or display messages, it is useful to specify a time interval between updates or displays. This is achieved through the use of the $sleep dbXtra variable, which is described in ``Info menu: debugging registers, memory locations, and expressions''. The commands affected by the $sleep variable are marked with a ``+'' symbol.

Each variant of trace has a trace region associated with it, which is the set of program statements or instructions executed while the specified events are monitored. By default, the trace region consists of all the statements (and instructions) in the program being debugged. A trace is triggered whenever a specified event occurs during the execution of the statements (or instructions) in the trace region.

This syntax for the simplest form of this command is:

trace [inst] [if condition] +

This command causes the source window to be updated so that the source line pointer is placed at the line containing the next statement to be executed. If inst is specified, then each instruction is disassembled and displayed in the interaction window before it is executed.

If the optional if clause is specified, then condition is evaluated after each statement (or instruction) in the trace region is executed, and tracing information displayed only when condition evaluates to true. The trace region for this command is the whole program.

trace line-number [if condition]
trace inst address [if condition]

The first form of this command causes a message to be displayed whenever line-number is executed. This line must be from the file displayed in the source window. The second form causes a message to be displayed whenever the instruction at address is executed.

In both cases, if the optional if clause is specified, the condition is evaluated before the specified line-number or address is executed, and if it evaluates to true, the trace message is displayed.

trace [inst] in routine [if condition] +

This command is only slightly different from the first trace variant described above -- it limits the trace region to the statements that are executed while the specified routine is active.

trace routine [in routine2] [if condition]

A message is displayed every time the specified routine is called, and also every time the routine returns. If the optional in clause is used, then the trace region is limited to those statements executed while routine2 is active.

If the optional if clause is specified, then the condition is evaluated whenever the trace is triggered, and trace information is displayed only if the condition evaluates to true.

trace [inst] [change] variable [in routine] [if condition]
trace [inst] change address [in routine] [if condition]

If the first form is used, a message is displayed whenever the contents of variable are modified. If the second form is used, then the message is displayed whenever any of the four bytes starting at the specified address are modified.

In either case, if the inst keyword is specified, the message is displayed before the next instruction (as opposed to the next statement) is executed. Please note that in the first form of the command, the change keyword is optional and is included for consistency with the other variants of the trace command; its inclusion does not alter the behavior described.

If the ``in routine'' clause is specified, the trace region is limited to the statements (instructions) executed while the specified routine is active. If the optional if clause is specified, then whenever the trace is triggered, the specified condition is evaluated, and the message is displayed only if the condition evaluates to true.

If a debug register is available, it monitors changes to the specified variable or address. Otherwise, the code in the trace region is single stepped, and the contents of variable or address are monitored after each statement (or instruction) is executed.

trace [inst] access variable [in routine] [if condition]
trace [inst] access address [in routine] [if condition]

If the first form is used, a message is displayed whenever the contents of variable are accessed. If the second form is used,the message is displayed whenever any of the four bytes starting at the specified address are accessed.

In either case, if the inst keyword is specified, the message is displayed before the next instruction (as opposed to the next statement) is executed.

If the in clause is specified, the trace region is limited to the statements (instructions) executed while the specified routine is active. If the optional if clause is specified, then whenever the trace is triggered, the specified condition is evaluated, and the message is displayed only if the condition evaluates to true.

NOTE: This command is only accepted if a 386 hardware debug register is available. If no such registers are available, an error message is displayed. To free up a debug register, you have to cancel a command that has been allocated a debug register. The Events menu button can list all the commands that are active.

Interrupt

Stops the execution of the program; the source window is updated to display the current execution point.

Catch

[dbxtra command: catch [signal-name | number]]
Catches signals destined for your program; upon receipt of one of these signals, stops your program. You may elect to send the signal to the program through the Continue menu button. The catch command is useful when a program being debugged does not handle signals such as interrupts. A signal can be specified by a number or by a name. Signal names are case insensitive and the SIG prefix is optional. By default, all signals are caught except SIGCONT, SIGCHILD, SIGALRM, and SIGKILL. For more information on signals, see signal(S).

Ignore

[dbxtra command: ignore [signal-name | number]]
Deletes a signal from the list of signals intercepted by the debugger. The ignore command specifies that the debugger send the specified signals on to the program being debugged. This command is useful when a program being debugged handles signals such as interrupts. A signal can be specified by a number or by a name. Signal names are case insensitive and the SIG prefix is optional. By default, all signals are caught except SIGCONT, SIGCHILD, SIGALRM, and SIGKILL.

Dbxtra

Allows you to enter complex commands for direct execution by dbx. The output from the debugger is displayed in a separate, read-only window that can be removed when no longer required.