NAME
dbx - source-level debugging tool
SYNOPSIS
dbx [ -B ] [ -c cmd ] [ -C ] [ -d ] [ -e ] [ -f ] [ -h ] [
-Idir ] [ -k ] [ -q ] [ -r ] [ -R ] [ -s startup ] [ -S ] [
-V ] [ -wcount ] [ -x exec32 ] [ execfile [ .class | .jar ]
[ corefile | process-id ] ] [ arguments ]
DESCRIPTION
Oracle Solaris Studio dbx is a utility for source-level
debugging and execution of programs written in C++, ANSI C,
Fortran 77, Fortran 95, and Java programming languages.
execfile is an executable file, produced by a Solaris Studio
compiler with the -g option which includes debugging symbols
in the execfile or its associated object files. For Java
code, it can be a .class or .jar file. The 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.
You can specify arguments to be passed to the program only
if you specify the -r option. For a Java program, specify
only arguments to be passed to the program, not arguments to
be passed to the JVM[tm] software.
During startup, dbx searches for .dbxrc first in the instal-
lation directory. If .dbxrc is not found, dbx then searches
for ./.dbxrc (ksh mode). If ./.dbxrc is not found, dbx
prints a warning message and searches for ~/.dbxrc (dbx
mode).
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.
AVAILABILITY
Solaris Studio dbx is available on the following platforms:
o Solaris[tm] Operating System, version 9 and version 10
1/06
o Linux operating system:
SuSE Linux Enterprise Server 9 with Service Pack 3
RedHat Enterprise Linux 4
OPTIONS
B Suppress all messages; return with exit code of
program being debugged.
-c cmd Execute cmd after loading the program and just
before prompting for input. For more than one
cmd, use quotes around the string of commands,
separating them with a semi-colon. If the com-
mands include a $ (dollar sign), the 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.
-f Force loading of core file, even if it does not
match.
-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.
-xexec32 Run the 32-bit dbx binary instead of the 64-bit
dbx binary that runs by default on systems run-
ning a 64-bit OS.
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.
LIMITATIONS
The following features of dbx are not available on Linux
platforms:
o Fix and continue
o Java debugging
o Core file debugging
Memory access checking is not available on Linux platforms
or on the Solaris OS x86 Platform Edition..
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. For information on
setting dbx environment variables, type "help dbxenv" on the
dbx command line.
FILES
.dbxrc local dbx initialization file
~/.dbxrc your dbx initialization file
libcollector.so shared library used with the collector
command
libdbx_agent.so shared library used for Java debugging
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), kill(1), ksh(1), make(1S),
rtc_patch_area(1).