dbx
PURPOSE
Provides a tool to debug and run programs under AIX.
SYNOPSIS
dbx [[-a pid][[-c file -l dir -r]...[ofile[corefile]]]]
DESCRIPTION
The dbx command provides a symbolic debugger to be used
with C, Pascal, and Fortran programs. With it you can
examine object and core files and provide a controlled
environment for running a program. You can set break-
points at selected statements or run the program one line
at a time. You can debug using symbolic variables and
instruct dbx to display them in their correct format.
The ofile is an object (executable) file produced by a
compiler. Use the -g (generate symbol table) flag when
you compile your program to produce the information dbx
needs. If you have not compiled the object file using
the -g flag or if it is not executable (because of com-
piler or loader errors), the symbolic capabilities of dbx
are limited.
When dbx is started, it checks for the file .dbxinit in
the user's current directory. If the file is not found
there, it also checks the user's $HOME directory. If
.dbxinit exists, the subcommands in it are run at the
beginning of the debug session. Use an editor to create
a .dbxinit file.
If the file core exists in the current directory or a
corefile is specified, you can use dbx to examine the
state of the program when it faulted.
When printing variables and expressions, names are
resolved first using the static scope of the current
function, then using the dynamic scope if the name is not
defined in the first scope. If static and dynamic
searches do not yield a result, an arbitrary symbol is
chosen and the system prints the message "[using
module.variable]" where module.variable is the name of an
identifier qualified with a block name. You can override
the name resolution procedure by qualifying an identifier
with a block name. Source files are treated as modules
named by the file name without the language suffix (such
as, the .f suffix on a Fortran program or the .c suffix
on a C Language program).
Expressions are specified with an subset of C and Pascal
(or equivalent Modula-2) syntax. Indirection can be
denoted using either a prefix "*" or a postfix "^" and
array expressions are subscripted by "[ ]" or "( )". The
field reference operator "." can be used with pointers as
well as records, making the C operator "->" unnecessary
(although it is supported).
Types of expressions are checked. The type of an
expression can be overridden by using type-name
(expression). When there is no corresponding named type
the special construct &type-name can be used to represent
a pointer to the named type and the construct $$tag-name
can be used to represent a pointer to enum, struct, or
union tag.
The following operators are valid in expressions:
Algebraic "+, -, *, /" (floating)", div"
(integral)", mod"
Bitwise "-, |, bitand, xor, ~"
Logical "or, and, not"
Comparison "<, >, <=, >=, <> or !=, = or =="
FLAGS
-a pid Attaches the debugger to a process that is
running. The debugger becomes active as soon
as the process wakes up. You must have
authority to end the process in order to
attach.
-c file Runs the dbx commands in the file before
reading from standard input.
-I dir Includes dir in the list of directories that
are searched for source files. The default is
to look for source files in the current direc-
tory and in the directory where the object file
is located. The search path can also be set
with the use subcommand.
-r Runs the object file immediately. If it ends
successfully, exit dbx. Otherwise, enter the
debugger and report the reason for termination.
Note: Unless -r is specified, dbx prompts the user and
waits for a command.
SUBCOMMANDS
Run and Trace Subcommands
call proc (params) Executes the object
code associated with
the named procedure or
function. You can use
print proc (params) to
perform the same func-
tion, but with a
return code of proce-
dure printed.
catch
catch signum
catch signame
ignore
ignore signum
ignore signame Starts or stops trap-
ping a signal before
it is sent to the
program. This subcom-
mand is useful when a
program being debugged
handles signals such
as interrupts. A
signal may be speci-
fied by number or by a
name. Signal names
are case insensitive
and the SIG prefix in
names is optional. By
default all signals
are trapped except
SIGHUP, SIGCLD,
SIGALRM, and SIGKILL.
clear sline Removes all stops at a
given source line.
The sline can be
either an integer or a
file name string fol-
lowed by a ":" and an
integer.
cont
cont signum
cont signame Continues execution
from the current stop-
ping point until the
program finishes or
another break point is
encountered. If a
signal is specified,
the process continues
as though it received
the signal. Other-
wise, the process is
continued as though it
had not been stopped.
delete num ... Removes the traces and
stops corresponding to
the specified numbers.
The numbers associated
by dbx with a trace or
stop can be displayed
with the status sub-
command.
detach
detach signum
detach signame Continues execution
from where it stopped
without debugger
control. If a signal
is specified, the
process continues as
though it received the
signal. Otherwise,
the debugger will
exit, but the debugged
process shall con-
tinue.
multproc [on]
multproc [off] Enables or disables
multi-process debug-
ging. The initial
value is off. To
check the status of
multi-process debug-
ging, issue the
command without param-
eters.
print proc (params) Executes the object
code associated with
the named procedure or
function. You can use
call proc (params) to
perform the same func-
tion, but with a
return code of proce-
dure called.
next Runs the program up to
the next source line.
The difference between
this and the step
subcommand is that if
the line contains a
call to a procedure or
function, step will
stop at the beginning
of that block, while
next will not.
return [proc] Continues until a
return to procedure is
executed, or until the
current procedure
returns if none is
specified.
run [args] [< file] [> file]
[>> file] [2> file] [2>> file]
[>& file] [>>& file]
rerun [args] [< file] [> file]
[>> file] [2> file] [2>> file]
[>& file] [>>& file] Starts running the
object file, passing
args as command line
arguments. "<", ">",
or "2>" redirects
input, output, or
standard error,
respectively. ">>"
appends redirected
output and "2>>"
appends redirected
standard error. ">&"
redirects both output
and standard error to
the same file. ">>&"
appends the redirected
output and standard
error to the same
file. When rerun is
used without any argu-
ments, the previous
argument list is
passed.
status [> file] Prints out the cur-
rently active trace
and stop commands.
step Runs one source line.
stop if cond
stop at sline [if cond]
stop in proc [if cond]
stop var [in proc] [if cond] Stops program when the
condition is true,
when the source line
number is reached,
when the procedure (or
function) is called,
or when the variable
is changed. A condi-
tion can also be spec-
ified for the source
line, procedure, or
variable stops. The
debugger associates
numbers with each stop
subcommand.
Use the status subcom-
mand to display these
numbers. Use the
delete or clear sub-
command to turn stop-
ping off. You may
need to use the quali-
fied name to get the
actual variable stop.
trace
trace in proc [if cond]
trace sline [if cond]
trace proc [in proc] [if cond]
trace expr at sline [if cond]
trace var [in proc] [if cond] Prints the tracing
information for the
specified procedure
(or function), source
line, expression, or
variable when the
program runs. A con-
dition may be speci-
fied. The debugger
associates numbers
with each trace sub-
command. Use the
status subcommand to
display these numbers.
Use the delete subcom-
mand to turn tracing
off.
watch var [in proc] Traces changes to a
variable in a watch
window if invoked
under xdbx. Other-
wise, this is the same
as trace.
Subcommands for Examining Program Data
assign var = expr Assigns the value of the expression
to the variable.
case [default]
case [mixed]
case [lower]
case [upper] Changes the way in which the
debugger interprets symbols. The
default handling of symbols is
based upon the current language.
Symbols are folded to lower case
unless C is the current language.
This command should be used if a
symbol needs to be interpreted in a
way not consistent with the current
language. Entering this command
with no parameters displays the
current case mode.
dump [proc] [> file] Displays or puts in a file the
names and values of variables in
the specified procedure. If the
procedure specified is "."
(period), then all active variables
are dumped. The default is the
current procedure.
print expr [,expr...] Prints out the values of the
expressions.
whatis name Prints the declaration of name
where name is a variable, proce-
dure, or function name that may be
qualified with a block name.
where [> file] Prints out a list of the active
procedures and functions.
whereis identifier Prints the full qualification of
all the symbols whose name matches
the specified identifier. The
order in which the symbols are
printed is not significant.
which identifier Prints the full qualification of
the given identifier (the outer
blocks with which the identifier is
associated).
up [count]
down [count] Moves the current function, which
is used for resolving names, up or
down the stack count levels. The
default is 1.
Subcommands for Accessing Source Files
/regular expression[/] Searches forward in the current
source file for the specified
pattern.
?regular expression[?] Searches backward in the current
source file for the specified
pattern.
edit [file]
edit proc Invokes an editor with file or
the current source file if none
is specified. If a procedure
(or function) proc is specified,
the editor is invoked on the
file that contains it. The
default editor is vi. The
default can be overridden by
resetting the environment vari-
able EDITOR to the name of the
desired editor.
Note: If the procedure has the
same name as any other file in
the same directory, the editor
invokes the other file, not the
file that contains the proce-
dure.
file [file] Changes the current source file
to file, but does not write to
the file. If none is specified,
print the name of the current
source file.
func [proc] Changes the current function to
the specified procedure or func-
tion. If none is specified,
prints the current function.
Changing the current function
implicitly changes the current
source file to the one that con-
tains the function; it also
changes the current scope used
for name resolution.
list proc If the name of a procedure or
function is given, lists lines
f-n to f+m where f is the first
statement in the procedure or
function, n is a small number,
and m is the number of lines
remaining that fit in the
default list window. Use set
$listwindow=value to set or
change the number of lines dis-
played in the list window.
list [sline [, sline]] Lists the source lines in the
current source file from the
first line number to the second
inclusive. If no lines are
specified, lists the next 10
lines or $listwindow lines. An
sline of "$" specifies the
current line of execution.
use dir [dir ...] Sets the list of directories to
be searched when looking for
source files.
Machine Level Subcommands
address,address/[mode][>file]
address/[count][mode][>file] Prints the contents of
memory starting at the
first address and contin-
uing up to the second
address or until count
items are printed. If
the address is "."
(period), the address
following the one printed
most recently is used.
The mode specifies how
memory is to be printed;
if it is omitted, the
previous mode specified
is used. The initial
mode is X. The following
modes are supported:
b Prints a byte in
octal.
c Prints a byte as a
character.
d Prints a short word
in decimal.
D Prints a long word in
decimal.
f Prints a single pre-
cision real number.
g Prints a double pre-
cision real number.
i Prints the machine
instruction.
o Prints a short word
in octal.
O Prints a long word in
octal.
s Prints a string of
characters terminated
by a null byte.
x Prints a short word
in hexadecimal.
X Prints a long word in
hexadecimal.
Symbolic addresses are
specified by preceding
the name with an "&".
Addresses can be
expressions made up of
other addresses and the
operators "+", "-", and
"*" (indirection). Also,
any expression enclosed
in parentheses is inter-
preted as an address.
registers [>file] Displays the values of
all general purpose reg-
isters, system control
registers, floating point
registers, and the
current instruction reg-
ister. General purpose
registers are denoted by
$rn where n is the number
of the register.
Floating point registers
are denoted by $frn.
stepi
nexti Runs a single step as in
step or next, but runs a
single instruction rather
than source line.
tracei [addr][if cond]
stopi [addr][if cond] Traces or sets a stop
when the contents of addr
change.
tracei [var][at addr][if cond]
stopi [var][at addr][if cond] Turns on tracing or sets
a stop at a machine
instruction address.
Subcommand Aliases and Variables
alias Displays aliases for sub-
commands.
alias name name
alias name "string"
alias name (params) "string" When subcommands are
processed, dbx first
checks to see if the word
is an alias for either a
subcommand or a string.
If it is an alias, then
dbx treats the input as
though the corresponding
string (with values sub-
stituted for any parame-
ters) had been entered.
set var [= expr] The set subcommand
defines a value
(expression) for a
debugger variable. The
name of the variable
cannot conflict with
names in the program
being debugged. A vari-
able is expanded to the
corresponding expression
within other commands.
The following variables
have a special meaning:
$frame Setting
this vari-
able to an
address
causes dbx
to use the
stack
frame
pointed to
by this
address
for doing
stack
traces and
accessing
local var-
iables.
This
facility
is of par-
ticular
use for
kernel
debugging.
$hexchars
$hexints
$hexstrings When set,
dbx prints
out char-
acters,
integers,
or char-
acter
pointers
respec-
tively in
hexadecimal.
$listwindow The value
of this
variable
specifies
the number
of lines
to list
around a
function
or when
the list
command is
given
without
any param-
eters.
Its
default
value is
10.
$mapaddrs Setting
(unset-
ting) this
variable
causes dbx
to start
(stop)
mapping
addresses.
As with
$frame,
this is
useful for
kernel
debugging.
$octints When set,
dbx prints
out inte-
gers in
octal.
$unsafeassign When
$unsafeassign
is set,
strict
type
checking
between
the two
sides of
an assign
statement
is turned
off.
These var-
iables
should be
used only
with great
care
because
they
severely
limit the
usefulness
of dbx for
detecting
errors.
$unsafecall When
$unsafecall
is set,
strict
type
checking
is turned
off for
arguments
to subrou-
tine or
function
calls.
unalias name Removes the alias with
the given name.
unset name Deletes the debugger var-
iable associated with
name.
Other Useful Subcommands
help Prints out a synopsis of common dbx com-
mands.
prompt "string" Changes the dbx prompt to be the same as
string.
quit Quits dbx.
screen Opens a virtual terminal for the dbx
command interaction. The user continues
to operate in the window in which the
process originated.
sh command Passes the command line to the shell for
execution. The SHELL environment vari-
able determines which shell is used.
source file Reads dbx commands from the given file.
FILES
a.out Contains object code; object file.
core Contains core dump.
.dbxinit Contains initial commands.
RELATED INFORMATION
The following commands: "cc" and "xdbx."
The a.out and core files in AIX Operating System Tech-
nical Reference.
The topic "Debugging Programs" in AIX Operating System
Programming Tools and Interfaces.