This chapter tells you how to start the Watcom Debugger. Topics include:
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.
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.
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.
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).
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.
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.
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 &
or
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.