.\".\" Copyright 1987-2000 Sun Microsystems, Inc.
.\" @(#)dbx.1 1.56 00/02/11 SMI;
.TH DBX 1 "11 February 2000" " "
.SH NAME
dbx \- source-level debugging tool
.SH SYNOPSIS
.B dbx
[
.BI \-c "  cmd"
]
[
.B \-C
]
[
.B \-d
]
[
.B \-e
]
[
.B \-F
]
[
.B \-h
]
[
.BI \-I  \|dir
]
[
.B \-k
]
[
.B \-q
]
[
.B \-r
]
[
.B \-R
]
[
.BI \-s " startup"
]
[
.B \-S 
]
[
.B \-V 
]
[
.BI \-w  count 
]
[
.I execfile
[
.I corefile
|
.I process-id
] ]
.SH DESCRIPTION
.IX  dbx  ""  "\fLdbx\fP \(em source debugger"
.IX  "debug tools"  " dbx command"  ""  "\fLdbx\fP\(em source debugger"
.IX  "programming tools" " dbx" "" "\fLdbx\fP \(em source debugger"
.LP
.B dbx
is a utility for source-level debugging and execution of
programs written in C++,  
.SM ANSI
C,
.SM FORTRAN 77,
and Fortran 90.
.LP
.I execfile
is an executable file, produced by
a Sun compiler with the
.B \-g
option which includes debugging symbols in the 
.I execfile
or its associated object files.
This symbol table contains the names of all the source files
used to create the 
.I 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 
.B \-g
option.
.LP
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 
.I execfile.
Distributing the debugging information in the object files allows
.B 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 
.B dbx
knows where to find them.
(See the 
.B pathmap
command.)
If it is not feasible to keep program .o files around,
you can disable Auto-Read by compiling using the
.B \-xs
option, which instructs the compiler to have the linker place all debugging information in the program executable.
.LP
If, when starting
.B dbx
, no
.I execfile
is specified, use the
.B debug
command to specify a program to be debugged.
.LP
If you know a
.I process-id
but not the 
.I execfile,
you can use the
.B \-
(dash) as the 
.I execfile
and enter the
.I process-id
option to attach the process to
.B dbx.
.LP
If a
.I corefile
argument is specified, you can use
.BR dbx
to examine the state of the program when the core file was produced.
.LP
During startup, 
.B dbx
searches for 
.B ./.dbxrc
first (ksh mode).
If 
.B ./.dbxrc
is not found,
.B dbx
prints a warning message and searches for
.B ~/.dbxrc
(dbx mode). 
Then the search order is
.B ./.dbxrc,
then
.B ~/.dbxrc,
then
.B ./.dbxinit,
then
.B ~/.dbxinit. 
.LP
Runtime Checking (RTC) is a fully integrated feature of
.B 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.
.LP
The 
.B \-g
flag provides source line number correlation in the error messages.
RTC can check programs compiled with the optimization
.B \-O
flag. You do not have to recompile, relink, or modify the
makefile to use RTC.
.LP
For proper operation, RTC requires dynamic linking with
.B libc
 and use of the standard
.B libc
functions
.B malloc/free/realloc.
.LP
To use RTC, issue a 
.B check
.I type-of-checking
command within 
.B dbx
before running the program. It is also recommended that you start
.B dbx 
with the
.B -C
option for early loading of the RTC library. Alternatively, RTC can be used in Batch mode. See
.B bcheck (1).
Access checking is supported only on the SPARC hardware architecture.
.SH OPTIONS
.TP 12
.BI \-c " cmd"
Execute
.I cmd
after loading the program and just before prompting for input. For more than one
.I cmd,
use double quotes around the string of commands,
separating them with a semi-colon. If the commands include a $ (dollar sign), the double quotes will not work.
.TP
.B \-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
.B check
command.
.\".TP
.\".B \-C
.\"Force the program to be debugged to load 
.\".I libcollector.so
.\"in order to collect profile data.
.TP
.BI \-d
Delete
.IR startup 
after processing it.
.TP
.BI \-e
Echo input commands.
.TP
.BI \-F
Enable Cfront demangling.
.TP
.B \-h
Print help before prompting for input.
.TP
.BI \-I " dir"
Add
.I dir
to the list of directories to search for a source file.
.B dbx
normally searches the current directory and the directory where
.I execfile
is located. The directory search path can be reset with the
.B pathmap
command.
.TP
.B \-k
Debug a program that sets the keyboard into up-down translation
mode.  Necessary if a program uses up-down decoding.
.TP
.B \-q
Quiet mode, or silence echoing of two loading messages: "Reading symbol table 
for..." and "Attached to ...". 
.TP
.B \-r
Run
.I execfile
immediately. Parameters follow the
.I execfile
name (including redirection). If the program terminates successfully,
.B dbx
exits. Otherwise, if a fault occurs,
.B dbx
reports the reason and waits for a response.
.TP
.BI \-R
Print the
.I README
file.
.TP
.BI \-s "startup"
Read initialization commands from the file
.IR startup 
script instead of from
.BR .dbxrc .
.TP
.BI \-S
Suppress reading of site-specific
.BR .dbxrc .
.TP
.BI \-V
Print the version of
.B dbx
being used.
.TP
.BI \-w
Count - skip the top 
.I N 
frames in the
.B where
command.
.SH USAGE
.LP
The basic commands to know are:
.TP 12
.BI run 
to run the program being debugged
.TP
.BI where 
to obtain a stack trace with line numbers
.TP
.BI print 
to display variables
.TP
.BI stop 
to set breakpoints

.SS "Scope Rules"
.LP
.B 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
.B file
and
.B func
commands. When the current function is changed, the current file
is updated along with it, and vice versa.

.SS Thread Identification
In some commands the use of 
.I id
refers to the thread id (\f3tid\fP) or light weight process id
(\f3lid\fP). These take the form of \f3t@\fP\f2N\fP or \f3l@\fP\f2N\fP.
.SS Handler Identification
Event handlers are identified with an integer number 
.I hid
(see \f3status\fP, \f3delete\fP, \f1and\fP \f3handler\fP 
commands).
.SH COMMANDS 
For a listing of all 
.B dbx
commands, type 
.B help commands
at the
.B dbx
command line.
.SH ENVIRONMENT
.B dbx
checks the environment variable
.SM EDITOR
for the name of the text editor to use with the
.B 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.
.SH FILES
.PD 0
.TP 20
.TP
.B .\|dbxrc
local 
.B dbx
initialization file
.TP
.B ~/.\|dbxrc
your
.B dbx
initialization file
.TP
.B .\|dbxinit
local
.B dbx
alternate initialization file (obsolete) 
.TP
.B ~/.\|dbxinit
your
.B dbx
alternate initialization file (obsolete)
.TP
.B libcollector.so
shared library used with the \f3collector\fP command
.TP
.B libcollector.o
object file used with the 
.B collector
command. Links with the application when using static linking and the 
.B collector
together
.TP
.B librtc.so
shared library used for RTC (\f3check\fP command)
.TP
.B libdbxadb.so
shared library used with the \f3adb\fP command
.TP
.B debugging.so
debugging aid for dbx engineers when tracking dbx problems
.PD
.SH SEE ALSO
.BR bcheck (1),
.BR csh (1),
.BR dbxrc (4),
.BR dbxinit (4),
.BR workshop (1),
.BR kill (1),
.BR ksh (1),
.BR make (1S),
.BR rtc_patch_area (1).