DBX(1)DBX(1)NAMEdbx - source-level debugging tool
SYNOPSISdbx [ -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 compilation does not create an
object file, all debugging information is stored in the execfile. Dis‐
tributing 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 com‐
mand.) 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 produced.
You can specify arguments to be passed to the program only if you spec‐
ify 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] soft‐
ware.
During startup, dbx searches for .dbxrc first in the installation
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 examining 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 mes‐
sages. 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
0.ft R 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 commands 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 trans‐
lation 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. Otherwise, if a fault occurs, dbx
reports the reason 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 command.
-xexec32 Run the 32-bit dbx binary instead of the 64-bit dbx binary
that runs by default on systems running 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 explic‐
itly using the file and func commands. 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 com‐
mand 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..
ENVIRONMENTdbx checks the environment variable EDITOR for the name of the text
editor to use with the edit command. The environment 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 com‐
mand
libdbx_agent.so shared library used for Java debugging
librtc.so shared library used for RTC (check command)
libdbxadb.so shared library used with the adb command
libdbxFintr.so shared library used for Fortran intrinsic
function calls
debugging.so debugging aid for dbx engineers when track‐
ing dbx problems
SEE ALSObcheck(1), csh(1), dbxrc(4), kill(1), ksh(1), make(1S),
rtc_patch_area(1).
May 2010 DBX(1)
