Appendix: Debugger Commands

This appendix describes the general syntax used for all debugger commands as well as the particulars of each command.

Accelerate
Break
Call
CAPture
COnfigfile
Display
DO (or /)
ERror
Examine
Flip
FOnt
Go
Help
HOok
IF
INvoke (or <)
Log (or >)
MOdify
NEW
PAint
Print (or ?)
Quit
RECord
Register
REMark (or *)
Set
SHow
SKip
STackpos intexpr
SYstem (or !)
THread (or ~)
Trace
Undo
View
While
WIndow

Syntax Definitions

A debugger command may contain any of the following syntax elements:

[x] indicates that x is an optional item. It may or may not be included in the command.
[x|y|z] indicates that one of x, y, or z should be included in the command.
[x [x [...]]] indicates that x may be repeated zero or more times in the command.
CApital indicates that ca,cap,capi,... are accepted short forms for the command capital.
(GUI only) indicates that this command is available only in a GUI debugger.
(character-based) indicates that this command is available only in a character-mode debugger.
expr is an expression. These may include such things as variables in the program being debugged, and are evaluated in the current program context. For more information about expressions, see the chapter Expression Handling.
integer is an integer constant
intexpr is an an expression that evaluates to an integral value. For more information about expressions, see the chapter Expression Handling.
command is any debugger command or group of debugger commands.
You can group debugger commands with braces, and separate them with semicolons. The resulting compound command may be considered an atomic command. For example:
```
    {command;command;command}
    
```
address is any expression that evaluates to an address. For more information about expressions, see the chapter Expression Handling.
string is a string of text, optionally enclosed in braces. For example:
```
    this_is_a_string
    {so is this}
    
```
wndname is the name of a window. Valid window names (with acceptable short forms indicated in capitals) are:
- ASsembly
- ALl
- BReak
- Calls
- Watch
- FIle
- FPu
- FUnctions
- FILEScope
- LOCals
- LOG
- MEmory
- MOdules
- Register
- SOurce
- STack
- Thread
- IO
- Globals
- Variable
- BInary
- IMage
- GLobalfunctions
- Accelerators
- TMPFile
- REPlay
- CUrrent
file represents any valid operating system filename. For example:
```
    hello.c
    
```
path represents any valid operating system directory path. For example:
```
    //2/dir1/dir2
    
```

`Accelerate`

The Accelerate command behaves as if a menu item from the main menu were selected:

    Accelerate main menu {menu_string}

The following command behaves as if the named menu item in the floating popup menu for the current window were selected:

    Accelerate {menu_string}

The arguments are as follows:

menu: the string appearing on the main menu bar (File, Run, Break, Code, and so on)
menu_string: enough of the text appearing in a menu item to identify it uniquely.

Examples

behave as if Until return were selected from the Run menu:

    accelerate main run {until return}

behave as if Home were picked from the floating popup menu of the current window:

    accelerate {Home}

`Break`

To print a list of all breakpoints in the log window:

    Break

To set a breakpoint (see the Breakpoints chapter for details about breakpoint operation):

    Break [|/Set|/Byte|/Word|/DWord|/Modify]
      address [ {do_command} [ { condition } [ countdown ]]]

To deactivate a breakpoint:

    Break/Deactivate brkid

To enable a breakpoint:

    Break/Activate brkid

To clear a breakpoint:

    Break/Clear brkid

To toggle a breakpoint through the active/inactive/deleted states:

    Break/Toggle brkid

To turn on the Resume option in the breakpoint:

    Break/Resume brkid

To turn off the Resume option in the breakpoint:

    Break/UnResume brkid

Options

/Set (default)

the breakpoint triggers when address is executed

/Byte

the breakpoint triggers when the byte at address is modified

/Word

the breakpoint triggers when the word at address is modified

/DWord

the breakpoint triggers when the double word at address is modified

/Modify

the breakpoint triggers when integer at address is modified

condition

an expression that must be true (non-zero value) before the breakpoint stops program execution

countdown

an integer. The breakpoint won't stop program execution until countdown is decremented to zero.

If you specify both condition and countdown, countdown decrements only when condition evaluates to true.

do_command

a command executed each time the breakpoint stops program execution

brkid

option can be three possible values:

address: Perform the operation on breakpoint with the given address.
*: Perform the operation on all breakpoints.
#integer: Name a breakpoint by its index. This index appears on the title line of the Breakpoint dialog.

Examples

To set a breakpoint at foo the twentieth time that i equals 10. When this occurs do j7 is executed:

    Break /Set foo {do j7} {i10} 20

To clear the breakpoint at foo:

    Break /Clear foo

To activate breakpoint #1:

    Break /Activate #1

To deactivate all breakpoints:

    Break /Deactivate *

`Call`

Use the Call command to call a routine:

    Call [/Far|/Interrupt|/Near]address 
      [([parm[,parm[...]]])] [/|printlist]

This command calls the routine at address, passing the given parameters. The arguments are as follows:

/Far

Use a far call instruction.

/Near

Use a near call instruction.

/Interrupt

Call the routine as if it were an interrupt handler.

parm

[/location] expr, where:

location is [/|regset]

/: means to put the parm on the stack.
/regset: means to put the parm into the named registers.
regset: is a register aggregate.

printlist

See the Print command for details.

Examples

To call the function foo:

    call foo

To call the function bar, passing the parameters 1, 2, and 3:

    call bar( 1,2,3 )

To call foo, putting 1 on the stack, 2 in ax, and 3 in cx:bx; printing the value of ax and dx in decimal and hexadecimal, respectively, on return:

    call /near foo( // 1, /ax 2, /[cx bx] 3 ) {%d %x} ax,dx

For another way to call C or C++ functions, see ``Primary Expression Operators for the C Grammar'' in the Expression Handling chapter.

`CAPture`

Use the Capture command to execute a command and put the resulting program output into a window:

    CAPture command

For example, the following command calls a routine foo and puts its output into a debugger window:

    capture call foo

`COnfigfile`

The syntax of this command is as follows:

    COnfigfile

This command is used by the debugger to save and restore configuration. The debugger overwrites the file containing configfile when it saves configuration information.

`Display`

The Display command allows you to open any window:

    Display wndname 
      [/Open|/Close|/New|/MInimize|/MAximize|/Restore] 
      [ord,ord,ord,ord]

To refresh the debugger screen:

    Display

To open the status line:

    Display Status [/Open]

To close the status line:

    Display Status /Close

To bring a window to the front:

    Display wndname

Options

ord,ord,ord,ord: These are the x and y coordinates of the top left corner, and the width and the height of the window, respectively. 0,0,10000,10000 is a window covering the entire screen.
/Open: Open a new window or resize an existing one.
/New: Open a new window regardless of an existing one.
/Close: Close the window.
/MInimize: Iconify the window.
/MAximize: Make the window the size of the screen.
/REstore: Restore a window from a minimize or maximize.

Examples

To open a register window in the top left quarter of the screen:

    display register /open 0,0,5000,5000

To minimize the source window if it's open:

    display source /minimize

`DO` (or `/`)

Use the DO command to evaluate an arbitrary C/C++ or FORTRAN expression:

    DO expr

For example:

    DO i = 10

`ERror`

Use the Error command to display a string as an error message:

    ERror string

For example:

    error {An error has been detected}

`Examine`

Use the Examine command to examine memory at a specific address:

    Examine [/Byte|/Word|/Dword|/Pointer] 
      [address] [,follow [,len]]

To show an assembly window at a specific address:

    Examine /Assembly [address]

To show a source window at a specific address:

    Examine /Source [address]

To add an address to the I/O window as a byte, word, or dword:

    Examine [/IOByte|/IOWord|/IODword] [address]

Options

/Byte /Word /DWord /Pointer: Set the initial display type of the memory window.
/IOByte /IOWord /IODword: Set the initial display type of the line in the I/O window.
address: the address to examine.
follow: an expression used if the memory window's Repeat function is chosen.
len: an integer expression indicating the length of memory to examine.

For example, The following command opens a memory window positioned at the address of foo. The window initially displays 2-byte words. If the Repeat menu item is used, it follows a near pointer 4 bytes past the beginning of the window *(.+$). The window displays 16 bytes of data at a time:

    examine /word foo,*(.+4),16

`Flip`

Use the Flip command to configure screen flipping. See the section ``Options Dialog'' in the Debugger Environment chapter for details.

    Flip ON
    Flip OFf

`FOnt`

Use the Font command to set the font for the specified window:

FOnt wndname fontinfo

where

wndname: the name of the affected window
fontinfo: operating-system-specific font data.

`Go`

Use the Go command to start or continue program execution. Execution then resumes at the specified address or at the location defined by the current contents of the instruction pointer (the CS:IP or CS:EIP register pair). The format of the Go command is:

    Go [/Until] [/Keep] [/Noflip] [[start,]stop]

Options

/Until: skips breakpoints until the specified stop address is reached.
/Keep: allows you to keep a previous temporary breakpoint. If you keep the previous breakpoint you can't create a new one.
/Noflip: keeps the debugger from flipping to the application's screen.
start: the address at which to start execution (optional).
stop: the address at which to stop execution.

Examples

To resume execution until function foo is executed, without flipping to the application screen:

    go /noflip foo

The following command starts execution at foo, and runs until bar is executed.

    go foo,bar

`Help`

Bring up the help screen:

    Help

The help information provides information on using the debugger on a variety of operating systems; this manual concentrates on QNX alone.

The Photon Helpviewer contains the entire set of Watcom manuals for QNX.

`HOok`

Use the Hook command to execute a command when a defined event occurs:

    HOok event command

event can be any of the following:

PROGStart: a program is loaded
PROGEnd: a program terminates
DLLStart: a DLL is loaded
DLLEnd: a DLL is unloaded
EXECStart: program execution is beginning
EXECEnd: program execution is stopped
Sourceinfo: the current location being examined has debugging information
Assemblyinfo: the current location being examined has no debugging information
Modulechange: the current location being examined has changed modules

This example causes the Locals and Source windows to come to the front whenever a region with symbolic debugging information is entered:

    hook sourceinfo {display locals; display source}

`IF`

Use the If command to evaluate an expression, and then (depending on the results) execute a list of commands:

    IF expr { command }
    [ ELSEIF expr { command } 
    [ ELSEIF expr { command } [...]]]
    [ELSE { command }]

If the expression results in a non-zero value, the debugger commands contained after the IF expression are executed. Otherwise, the commands that appear after the ELSEIF expression are executed.

`INvoke` (or `<`)

Use the Invoke command to invoke a file containing a number of debugger commands:

    INvoke file [string [string [...]]]
    <      file [string [string [...]]]

file: the name of the command file to invoke.
string: passed as a parameter. These parameters may be referenced in the command file as <1>, <2>, and so on.

`Log` (or `>`)

Use the Log command to send the Dialog window output to a specified file. To start logging to a file:

    Log        file
    Log /Start file
    >          file

To start appending log information to a file:

    Log >       file
    >>           file
    Log /Append file

To stop logging:

    Log
    >

`MOdify`

Use the Modify command to change memory at an address to the values specified by the list of expressions:

    MOdify 
      [/Byte|/Pointer|/Word|/Dword|/IOByte|/IOWord|/IODword]
      address[,expr[...]]

Options

/Byte /Pointer /Word /Dword: Control the size of memory to be modified.
/IOByte /IOWord /IODword: Control the size of the I/O port to be modified.
address: The address to modify.
expr: The values to be placed in memory.

The following command changes the 3 bytes at location foo to the values 1, 2, and 3:

    modify /byte foo 1,2,3

The following command changes the 4 bytes at location foo to the value 12345678 hex:

    modify /dword foo 0x12345678

`NEW`

Use the New command to initialize various items:

    NEW [args]
    NEW /Program [[:symfile] progfile [args]]
    NEW /Restart [args]
    NEW /STDIn file
    NEW /STDOut file
    NEW /SYmbol file [seg [,seg [...]]

symfile: a file containing the symbolic information.
progfile: the executable file.
args: the arguments to be passed to the program.
/Program: Start the specified program.
/Restart: Reload the current application and place it into an initial state so that you may begin execution again. The application may have already partially or completely executed.
/STDIn: associate the standard input file handle with a particular file or device.
/STDOut: associate the standard output file handle with a particular file or device.
/Symbol: load additional symbolic debugging information, and specify the mapping between the linker addresses and the actual execution addresses.

`PAint`

Use the Paint command to define window or dialog colors. For window colors, use the following command:

    PAint [Status|wndname] wndattr color ON color

For dialog colors, use the following command:

    PAint DIalog dlgattr color ON color

Options

wndattr

allows you to define the window attributes. You can choose from the following items:

MEnu Plain: menu text (character-based)
MEnu STandout: menu accelerator key (character-based)
MEnu Disabled: grayed menu item (character-based)
MEnu Disabled Active: grayed menu item under the cursor (character-based)
MEnu Active: menu item under the cursor (character-based)
MEnu Active STandout: menu accelerator key under the cursor (character-based)
MEnu Frame: frame of the menu (character-based)
TItle Disabled: a non-active window's title
Frame Active: the frame of the active window (character-based)
Frame Disabled: the frame an inactive window (character-based)
ICon: an icon
Plain: normal text within a window
Active: window text under the cursor
SElected: window text being selected
STandout: window text the debugger wishes to highlight
Active STandout: window text the debugger wishes to highlight under the cursor
BUtton: the gadgets on the left side of a window (character-based)

dlgattr

allows you to define the dialog attributes. The possible options are:

Plain: normal text
Frame: the dialog frame
SHadow: the shadow of a button
BUtton Plain: normal button text
BUtton STandout: button accelerator key character
BUtton Active: a button that has focus
BUtton Active STandout: button accelerator key character of a button with focus

color

choose from the following colors:

BLAck
BLUe
GREEn
Cyan
Red
MAgenta
BROwn
White
GREY (or GRAy)
BRIght BLUe
BRIght GREEn
BRIght Cyan
BRIght Red
BRIght MAgenta
Yellow
BRIght BROwn
BRIght White

You can't use BRIght White as the background color.

Examples

To paint plain text black on white in all windows:

    paint all plain black on white

To make the highlighted text for buttons in all dialogs appear as bright green on a yellow background:

    paint dialog button standout bright green on yellow

For more examples of this command, see a configuration file such as setup.dbg.

`Print` (or `?`)

Use the Print command to:

prompt for an expression and then print it to the log window.
examine the values of variables and expressions.

The form of the Print command is:

    Print [/Window|/Program] [printlist]

/Window: open up a watch window containing the listed expressions.
/Program: print the results to the application's screen.
printlist: [format] [expr [,expr [...]]]
format: is a printf-like format string. It consists of plain text intermixed with control sequences, which are replaced with values from the expression list. The following table lists the control sequences and the format used for the corresponding argument:

Sequence:	Format:
`%i`	signed decimal integer value
`%d`	signed decimal integer value
`%u`	unsigned decimal integer value
`%x`	unsigned hexadecimal integer value. Letter digits are printed in lower case (`a-f`).
`%X`	unsigned hexadecimal integer value. Letter digits are printed in upper case (`A-F`).
`%o`	unsigned octal integer value
`%p`	pointer (segment:offset) value in hexadecimal notation.
`%c`	single character value.
`%s`	C/C++ string value. The argument must point to a string of characters terminated by a byte whose value is zero.
`%%`	To print out a percentage symbol, the % must be doubled up (that is, %%).
`%f`	floating-point representation. If the floating-point value has a very large or small magnitude, you should use one of `g`, `G`, `e` or `E` formatting.
`%g`	floating-point representation. Numbers of very large or small magnitude are printed out in scientific ``E'' notation (for example, 1.54352e+16). The exponent letter is printed in lower case.
`%G`	floating-point representation Numbers of very large or small magnitude are printed out in scientific ``E'' notation (for example, 1.54352E+16). The exponent letter is printed in upper case.
`%e`	scientific ``E'' notation (for example, 1.23456e+02). The exponent letter is printed in lower case.
`%E`	scientific ``E'' notation (for example, 1.23456E+02). The exponent letter is printed in upper case.
`%r`	current default numeric radix.
`%a`	symbol reference (symbol_name+offset) when possible; otherwise it's printed out as a pointer (segment:offset) value in hexadecimal notation.
`%l`	line number reference (module_name@line_number+offset) when possible; otherwise it is printed out as a pointer (segment:offset) value in hexadecimal notation.

Examples

To print the value of i:

? i

To print decimal=100 hex=0x64:

    print {decimal=%d hex=%x} 100,100

`Quit`

Use the Quit command to leave the debugger.

`RECord`

Use the Record command to add a command to the Replay window. This command is for internal use only. The format of the command is:

    REcordexpr command

`Register`

The format of the Register command is:

    Register intexpr

If intexpr is negative, this is equivalent to using the menu item Undo/Undo -intexpr times. If intexpr is positive, this is equivalent to using the menu item Undo/Redo intexpr times.

`REMark` (or `*`)

Use the Remark command to enter lines of comments:

    REMark string

`Set`

The Set command is used internally by the debugger to save and restore the configuration:

Set AUtosave [ON|OFf]
Set ASsembly [Lower|Upper] [Outside|Inside] [Source|NOSource] 
    [Hexadecimal|Decimal]
Set Variable [Entire|Partial] [CODe|NOCODe] [INherit|NOINherit] 
    [COMpiler|NOCOMpiler] [PRIvate|NOPRIvate] 
    [PROtected|NOPROTected] [Members|NOMembers]
Set FUnctions [Typed|All]
Set GLobals [Typed|All]
Set REGister [Hexadecimal|Decimal] [Extended|Normal]
Set Fpu [Hexadecimal|Decimal]
Set Bell [ON|OFf]
Set Call [/Far|/Interrupt|/Near] [ ( [location [,location [...]]] ) ]
Set Dclick expr
Set Implicit [ON|OFf]
Set INput wndname
Set Radix expr
Set RECursion [ON|OFf]
Set SEarch [CASEIgnore|CASEREspect] [Rx|NORx] string
Set SOurce [/Add] [path [path] [...]]]
Set SYmbol [/Add|/Ignore|/Respect] [lookspec [lookspec [...]]]
Set Tab intexpr
Set Level [Assembly|Mixed|Source]
Set LAnguage [CPP|C|FORTRAN]
Set SUpportroutine string
Set MAcro wndname key command

Options

location: see the Call command.
lookspec: [/Ignore|/Respect] string

`SHow`

The Show commands are used internally by the debugger to save and restore its configuration. The syntax is:

SHow Paint
SHow Display
SHow Font
SHow Set
SHow Set AUtosave
SHow Set ASsembly
SHow Set Variable
SHow Set FUnctions
SHow Set GLobals
SHow Set REGister
SHow Set Fpu
SHow Set Bell
SHow Set Call
SHow Set Dclick
SHow Set Implicit
SHow Set INput
SHow Set Radix
SHow Set RECursion
SHow Set SEarch
SHow Set SOurce
SHow Set SYmbol
SHow Set Tab
SHow Set Level
SHow Set LAnguage
SHow Set MAcro
SHow Set SUpportroutine
SHow Flip
SHow Hook

`SKip`

Use the Skip command to set the instruction pointer (CS:EIP) to a specific address:

    SKip address

`STackpos` intexpr

The Stackpos command is the same as using Undo/Unwind. The intexpr allows you to define the number of times to undo or unwind.

`SYstem` (or `!`)

Use the System command to spawn an operating system shell to execute a given string. The format of the system command is:

    SYstem [/Remote|/Local] string

/Remote: the shell is started on the program side of a remote debug link.
/Local: the shell is started on the debugger side of a remote debug link.

`THread` (or `~`)

Use the Thread command to manipulate the threads of execution of a multi-threaded application under OS/2 or NetWare 386:

THread [/Show|/Freeze|/Thaw|/Change] [threadid]

/Show: display the status of the current thread.
/Freeze: freeze a thread and make it unrunnable.
/Thaw: make a frozen thread runnable.
/Change: select a specific thread.
threadid: the identification number of the thread.

`Trace`

Use the Trace command to step through the execution of your program:

    Trace [/Assembly|/Mixed|/Source] [/Into|/Next|/Over]

/Assembly: trace through your assembly code one instruction at a time.
/Mixed: trace execution of the application one source statement at a time, or one instruction at a time when no source text is available.
/Source: trace execution of the application one source statement at a time.
/Into: continue execution to the next statement or assembly instruction. If the current statement or instruction invokes a routine, then the next statement or instruction is the first one called in the routine.
/Next: continue execution to the next statement or assembly instruction that immediately follows the current statement or instruction in memory. If the current statement or instruction is one that branches, be sure that the execution path eventually executes the statement or instruction that follows. If the program doesn't execute this point, the program may execute to completion.
/Over: continue execution to the next statement or assembly instruction. If the current statement or instruction invokes a routine, then the next statement or instruction is the one that follows the invocation of the routine.

`Undo`

The format of the Undo command is:

    Undo intexpr

If intexpr is positive, this is equivalent to using the menu item Undo/Undo intexpr times. If intexpr is negative, this is equivalent to using the menu item Undo/Redo -intexpr times.

`View`

Use the View command to show a file in a window:

    View [/Binary] [file|module]

/Binary: show the file contents in binary.
file: the file to be shown.
module: the module to be shown. The default is the current module.

`While`

Use the While command to permit the execution of a list of commands while the specified expression is true:

    While expr { command }

`WIndow`

The WIndow command operates on the current window and is useful when defining accelerators that perform window operations.

WIndow CLose: close the window
WIndow CURSORStart: move the cursor to start of line
WIndow CURSOREnd: move the cursor to end of line
WIndow CURSORDown: move the cursor down one line
WIndow CURSORLeft: move the cursor left
WIndow CURSORRight: move the cursor right
WIndow CURSORUp: move up one line
WIndow Dump: dump the window to a file
WIndow Log: dump the window to a log window
WIndow FINDNext: find the next occurrence of the current search string
WIndow FINDPrev: find the previous occurrence of the current search string
WIndow Next: make another window the current window
WIndow PAGEDown: move the window down one page
WIndow PAGEUp: move the window up one page
WIndow POpup: show the window's floating popup menu
WIndow SEarch: search for a given string
WIndow SCROLLDown: scroll the window down one line
WIndow SCROLLUp: scroll the window up one line
WIndow SCROLLTop: scroll the window to the very top
WIndow SCROLLBottom: scroll the window to the very bottom
WIndow TABLeft: move to the previous tabstop
WIndow TABRight: move to the next tabstop
WIndow MAXimize: maximize the window
WIndow MINimize: minimize the window
WIndow REStore: restore the window
WIndow TIle: tile all windows
WIndow CAscade: cascade all windows
WIndow PRevious: move to the previous window