Man Page dbx.1
NAME
dbx - source-level debugging tool
SYNOPSIS
dbx [ -c cmd ] [ -C ] [ -d ] [ -e ] [ -h ] [ -Idir ] [ -k ]
[ -q ] [ -r ] [ -R ] [ -s startup ] [ -S ] [ -V ] [ -wcount
] [ execfile [ corefile | process-id ] ]
DESCRIPTION
dbx is a utility for source-level debugging and execution of
programs written in C++, ANSI C, FORTRAN 77, and Fortran 90.
execfile is an executable file, produced by a Sun compiler
with the -g option which includes debugging symbols in the
execfile or its associated object files. This symbol table
contains the names of all the source files used to create
the execfile (all of which may be browsed), as well as a
wide range of debugging information. Debugging support is
limited for parts of a program not compiled with the -g
option.
Initially, symbol table information is stored piecemeal in
each of the object files the compiler creates. If compila-
tion does not create an object file, all debugging informa-
tion is stored in the execfile. Distributing the debugging
information in the object files allows dbx to read and load
debugging information as needed, a feature known as Auto-
Read. If you need to move object files from their original
location, make sure that dbx knows where to find them. (See
the pathmap command.) If it is not feasible to keep program
.o files around, you can disable Auto-Read by compiling
using the -xs option, which instructs the compiler to have
the linker place all debugging information in the program
executable.
If, when starting dbx , no execfile is specified, use the
debug command to specify a program to be debugged.
If you know a process-id but not the execfile, you can use
the - (dash) as the execfile and enter the process-id option
to attach the process to dbx.
If a corefile argument is specified, you can use dbx to
examine the state of the program when the core file was pro-
duced.
During startup, dbx searches for ./.dbxrc first (ksh mode).
If ./.dbxrc is not found, dbx prints a warning message and
searches for ~/.dbxrc (dbx mode). Then the search order is
./.dbxrc, then ~/.dbxrc, then ./.dbxinit, then ~/.dbxinit.
Runtime Checking (RTC) is a fully integrated feature of dbx
using its full capabilities for setting breakpoints and exa-
mining variables. With RTC, you can detect runtime errors in
an application at any stage. Additionally, you can monitor
memory usage.
The -g flag provides source line number correlation in the
error messages. RTC can check programs compiled with the
optimization -O flag. You do not have to recompile, relink,
or modify the makefile to use RTC.
For proper operation, RTC requires dynamic linking with libc
and use of the standard libc functions malloc/free/realloc.
To use RTC, issue a check type-of-checking command within
dbx before running the program. It is also recommended that
you start dbx with the -C option for early loading of the
RTC library. Alternatively, RTC can be used in Batch mode.
See bcheck (1). Access checking is supported only on the
SPARC hardware architecture.
OPTIONS
-c cmd Execute cmd after loading the program and just
before prompting for input. For more than one
cmd, use double quotes around the string of com-
mands, separating them with a semi-colon. If the
commands include a $ (dollar sign), the double
quotes will not work.
-C Causes early loading of the RTC library. (This
does not turn on checking) If not used on
startup, then the RTC library is loaded on the
next run, after a check command.
-d Delete startup after processing it.
-e Echo input commands.
-h Print help before prompting for input.
-I dir Add dir to the list of directories to search for
a source file. dbx normally searches the
current directory and the directory where
execfile is located. The directory search path
can be reset with the pathmap command.
-k Debug a program that sets the keyboard into up-
down translation mode. Necessary if a program
uses up-down decoding.
-q Quiet mode, or silence echoing of two loading
messages: "Reading symbol table for..." and
"Attached to ...".
-r Run execfile immediately. Parameters follow the
execfile name (including redirection). If the
program terminates successfully, dbx exits. Oth-
erwise, if a fault occurs, dbx reports the rea-
son and waits for a response.
-R Print the README file.
-sstartup Read initialization commands from the file
startup script instead of from .dbxrc.
-S Suppress reading of site-specific .dbxrc.
-V Print the version of dbx being used.
-w Count - skip the top N frames in the where com-
mand.
USAGE
The basic commands to know are:
run to run the program being debugged
where to obtain a stack trace with line numbers
print to display variables
stop to set breakpoints
Scope Rules
dbx resolves scope conflicts based on the values of the
current file and function. These values are updated as files
and functions are entered and exited during execution. You
can also change them explicitly using the file and func com-
mands. When the current function is changed, the current
file is updated along with it, and vice versa.
Thread Identification
In some commands the use of id refers to the thread id (tid)
or light weight process id (lid). These take the form of t@N
or l@N.
Handler Identification
Event handlers are identified with an integer number hid
(see status, delete, and handler commands).
COMMANDS
For a listing of all dbx commands, type help commands at the
dbx command line.
ENVIRONMENT
dbx checks the environment variable EDITOR for the name of
the text editor to use with the edit command. The environ-
ment variable TMPDIR (if set) is used to replace /tmp as the
location for temporary files needed by dbx. Several ksh
environment variables are also used.
FILES
.dbxrc local dbx initialization file
~/.dbxrc your dbx initialization file
.dbxinit local dbx alternate initialization file
(obsolete)
~/.dbxinit your dbx alternate initialization file
(obsolete)
libcollector.so shared library used with the collector
command
libcollector.o object file used with the collector com-
mand. Links with the application when
using static linking and the collector
together
librtc.so shared library used for RTC (check com-
mand)
libdbxadb.so shared library used with the adb command
libdbxFintr.so shared library used for Fortran intrin-
sic function calls
debugging.so debugging aid for dbx engineers when
tracking dbx problems
SEE ALSO
bcheck(1), csh(1), dbxrc(4), dbxinit(4), workshop(1),
kill(1), ksh(1), make(1S), rtc_patch_area(1).