Starting Up the Debugger

This chapter tells you how to start the Watcom Debugger. Topics include:

the syntax and options of the wd command
support files, including configuration files for customizing the Watcom debugger
using a postmortem dump in debugging

Syntax

Use the wd command to start the Watcom debugger. The syntax is as follows:

wd {-options} [:sym_file] [cmd_line]

where cmd_line is one of the following:

[//nid] pid
[//nid] executable {arguments}

The optional nid argument identifies the node you want to run the program on. For more information, see the section ``Using the QNX Network for Remote Debugging'' in the Remote Debugging chapter.

The sym_file argument is optional, and specifies the name of the file, usually with extension sym, in which debugging information for the program is to be found.

The two forms of cmd_line allow you to debug:

a currently executing process by specifying its process ID as the pid argument
an executable file by specifying its name and arguments as executable {arguments}

In both cases you can specify the node the process or executable is found on.

You may encounter problems if the debugger doesn't know where to find the source code associated with your executable. The name of the source file included in the debugging information is the path and the original name from the compiler's command line. If the original filename is no longer valid (for example, if you've moved the source to another directory), you must tell the debugger where to find the source files by choosing Source Path from the File menu. See the ``File menu'' in the Debugger Environment chapter.

Command-line options

You can specify on the command line the options you want to use during your debugging session. Acceptable option short forms are indicated in capital letters; options aren't case-sensitive. For example, the -TRap option may be shortened to -tr.

The following options are available:

-TRap=trap_file[;trap_parm]

specifies an executable helper program that the debugger uses to control the application being debugged, or to communicate across a remote link. It's called a ``trap file'' since the interrupts used for debugging are sometimes called ``traps''. The trap option selects the appropriate trap file to use. This option must be specified when remote debugging over a serial or parallel port.

If you use the ;trap_parm parameter, you'll likely need to put the option in quotes to avoid having the shell interpret the semicolon.

The remote trap files themselves have startup parameters, which are specified following the semicolon. See the Remote Debugging chapter for more information.

Normally you don't have to specify a trap file. If you don't specify the -trap option, the default trap file that supports local or QNX network debugging is loaded.

-LInes=n

controls the number of lines used by a character mode debugger. The number of lines available depends on the operating system and your video card. The values 25, 43 and 50 are often supported.

-COlumns=n

controls the number of columns used by a character-mode debugger. The number of columns available depends on your video card. If your system doesn't support the requested number of columns, this option is ignored.

The -COlumns option is ignored in QNX character-mode.

-Invoke=file

may be used to specify an alternate name for the debugger configuration file to be used at startup time. The default filename is wd.dbg. Debugger configuration files are discussed in ``Support Files'' in this chapter.

-NOInvoke

specifies that the default debugger configuration file isn't to be invoked.

-NOMouse

requests that the debugger ignore any attached mouse. This may be necessary if you're trying to debug mouse events received by your application. This option ensures that the debugger won't interfere with the mouse.

-Dynamic=number

specifies the amount of dynamic storage that the debugger is to set aside for its own use on startup. The default amount that's set aside is 500K bytes. The larger the amount, the less memory is available for the application to be debugged.

You need to use this option only if the debugger runs out of memory or causes your application to run out of memory.

If you're using the remote debugging feature, the debugger uses as much available memory as available.

-REMotefiles

is used in conjunction with the remote debugging capabilities of the debugger. It causes the debugger to look for all source files and debugger files on the remote machine. When -remotefiles is specified, all debugger files (except trap files) and application source files are opened on the task machine rather than the local one (which runs the debugger). The trap file must be located on the same machine as the debugger.

The PATH environment variable on the task machine is always used in locating executable image files. When -remotefiles is specified, the debugger also uses the task machine's PATH environment variable to locate debugger command files. See the chapter Remote Debugging for more information.

-NOFpu

requests that the debugger ignore the presence of a math coprocessor.

-NOSymbols

requests that the debugger omit all debugging information when loading an executable image.

This option is useful if the debugger detects and tries to load debugging information that isn't valid.

-DIP=dipname

used to load a non-default Debug information processor (DIP). This option is generally not needed, since the debugger loads all DIPs that it finds by default. For more information see the section ``Images Window'' in the Navigating Through a Program chapter.

-Console=number

specifies the virtual console number to use for debugger windows. By default, the debugger uses the first unused virtual console.

You can also specify a full device name, such as

    -console=//23/dev/ser1

for wd to use for its input and output. In this case, the debugger doesn't flip between its screen and the application's screen. You can optionally follow the device name with a colon and a terminal type, such as

    -console=/dev/ttyp1:vt240

to let the debugger know what kind of terminal you're using so it can set up the user-interface library appropriately.

If you're in Photon, wd creates a new pterm window and ignores this option.

Environment variables

You can use the WD environment variable to specify default options to be used by the debugger. Once you've defined the environment variable, those options are used each time you start the debugger.

The following example illustrates how to define default options for the debugger:

export "WD=-nofpu -console=3"

In QNX, the names of environment variables must be in uppercase.

Support files

There are several supporting files provided with the Watcom Debugger:

command files (files with the .dbg extension)
trap files (files with the .trp extension)
parser files (files with the .prs extension)
help files (files with the .hlp extension)
symbolic debugging information files (files with the .sym extension).

Search order for support files

The Watcom Debugger searches for support files in this order:

the current directory
the paths listed in the WD_PATH environment variable
the path listed in the HOME environment variable
the /usr/watcom/version/wd directory, and finally
the /usr/watcom/wd directory.

When the REMotefiles option is specified, the debugger attempts to locate the Watcom Debugger's support files (command files, trap files, and so on) on the task machine. See the Remote Debugging chapter.

Customizing the Watcom Debugger

When the debugger starts up, it attempts to open an initialization file that contains your customization commands. The search order for this file as follows:

wd looks for .wdrc in the directories listed above.
If .wdrc isn't found, and you specified the -invoke=filename option, wd looks for filename in the directories listed above, and uses it if it's found.
If the -invoke option isn't specified, wd looks for wd.dbg in the same set of directories. The default version of this file also invokes setup.dbg.

An error message is displayed if no configuration file can be found.

Debugging using the postmortem dump facility

A limited form of debugging of an application that has terminated and produced a postmortem dump can be done under QNX. In order to use this feature, you must start the QNX dumper utility. The syntax is given below; see the QNX Utilities Reference for more information.

dumper [-d path] [-p pid] &

The options are:

-d path: The name of the directory in which postmortem dumps are written. If this isn't specified, the default is your home directory.
-p pid: Save a dump file for this process if it terminates for any reason. Don't save a dump file for any other process.

The ampersand (&) must be specified so that the shell is rejoined.

For example,

dumper &

dumper -d /usr/fred/dump_area &

Whenever a program terminates abnormally, a dump of the current state of the program in memory is written to disk. The dump filename is the same as the program name with a .dmp extension. For example, if the program name is a.out then the dump is written in the /home/userid/a.out.dmp file.

You can use the -d option of the dumper program to force all dumps into a single directory rather than into your home directory.

The -p option lets you monitor a particular process. You can run multiple copies of the dumper program, each monitoring a different process.

Use the Watcom Debugger to examine the contents of the postmortem dump. The interface between wd and the postmortem dump is contained in a special trap file, pmd.trp, which is specified to the debugger using the -trap option.

wd -TRap=pmd[;i] [:sym_file] file_spec

where

-TRap=pmd[;i]

must be specified when debugging an application that has terminated and produced a postmortem dump. The optional ;i is specified when the modification date of the original program file doesn't match the information contained in the dumper file. It indicates that the symbolic debugging information in the program file may be out-of-date. It instructs the Watcom Debugger to ignore the date mismatch.

Depending on the shell that you're using, you may need to place the option specification in quotation marks if you include the optional ;i. For example,

    wd "-trap=pmd;i" myapp

sym_file

is an optional symbolic information file specification. The specification must be preceded by a colon (``:''). When specifying a symbol filename, a path such as //5/etc/ may be included. The default file extension of the symbol file is .sym.

file_spec

is the filename of the dumper file to be loaded into memory. When specifying a filename, a path such as //5/etc/ may be included. If a path is omitted, the debugger attempts to locate the file in the current directory.

Basically, the Watcom Debugger is fully functional when a postmortem dump is examined. However, some operations aren't allowed:

Task execution can't be restarted using Go from the Run menu.
A register can't be modified, except evaluate expressions. Choose Go from the Run menu to restore the register contents to their original postmortem state.
Memory can't be modified.
Memory outside of regions owned by the program can't always be examined.
I/O ports can't be examined.