NAME

dbx − source-level debugging tool

SYNOPSIS

dbx [ −c  cmd ] [ −C ] [ −d ] [ −e ] [ −F ] [ −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, Pascal, Fortran 90, and ObjectiveC.  For an overview of dbx features see the manual, Command-Line Utilities. 

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 compilation does not create an object file, all debugging information is stored in the execfile 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 use 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 produced. 

During startup, dbx searches for .dbxrc first (ksh mode).  If .dbxrc is not found, dbx prints a warning message and searches for .dbxinit (dbx mode).  The search order is: ./.dbxrc, then ~/.dbxinit. 

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 during the development phase. Additionally, you can monitor memory usage. 

−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 commands, separating them with a semi-colon. If the commands include a $ (dollar sign), the double quites 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 Remove startup after processing it. 

−h Print help. 

−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 use command. 

−k Debug a program that sets the keyboard into up-down translation mode.  Necessary if a program uses up-down decoding. 

−q Silence echoing of two loading messages: "Reading symbol table for..." and "Attached to ...". 

−r Execute execfile immediately. Parameters follow the execfile name (including redirection). If the program terminates successfully, dbx exits. Otherwise, dbx reports the reason for termination and waits for a response.  dbx switches to stdin only after an abend. 

−R Print the README file. 

−sstartup Read initialization commands from the file startup instead of from .dbxrc. 

−S Suppress reading of site-specific .dbxrc. 

−V Print the version of dbx being used. 

−w Count - skip N frames. 

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; and stop- to set breakpoints. 

Expressions

dbx expressions are combinations of variables, constants, procedure calls, and operators. Variables are either variables in the program being debugged or special dbx variables whose names begin with $.  Hexadecimal constants must be preceded by ‘0x’ and octal constants by ‘0’. Character constants must be enclosed in single quotes. In general, the expression rules followed are those of the current language. 

Operators

+   −   ∗   /   % Add, subtract, multiply, divide, and remainder. 

<<    >>     &   |   ~ Left-shift, right-shift, bitwise AND, bitwise OR, and bitwise complement. 

&   ∗ Address of operator and contents of operator. 

<   >    <=    >=   ==   !=   !
Less than, greater than, less than or equal to, greater than or equal to, equal, not equal, and negation.

&&   || Logical AND and logical OR . 

sizeof  (cast) Size of variable or type cast. 

.   −> Field reference and pointer field reference. 

:: C++ scope resolution operator. 

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 commands. When the current function is changed, the current file is updated along with it, and vice versa. 

C++ Symbolic Names

CC mangles the original source names of locals, member functions, functions, and more.  dbx demangles all mangled names into C++ symbolic format in dbx output. 

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 environment variable TMPDIR (if set) is used to replace /tmp as the location for temporary files needed by dbx.  The numerous ksh environment variables are also used. 

FILES

core default core file

.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 command. Links with the application when using static linking and the collector together

librtc.so shared library used for RTC (check command)

adb.so shared library used with the adb command

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(1), rtc_patch_area(1), and the Command-Line Utilities manual. 
 

SunOS 3.0.1  —  Last change: 16 Aug 1996