DBX(1) SysV DBX(1)
NAME
dbx - debugger
SYNOPSIS
dbx [ -r ] [ -i ] [ -I dir ] [ -no_src ] [ -no_frame ] [ -c file ] [
objfile ]
DESCRIPTION
dbx is a tool for source level debugging and execution of programs under
SysV. The objfile is an object file produced by a compiler with the
appropriate flag (usually -g) specified to produce symbol information in
the object file. The machine level facilities of dbx can be used on any
program.
The object file contains a symbol table that includes the name of the all
the source files translated by the compiler to create it. These files
are available for perusal while using the debugger.
If the file .dbxinit exists in the current directory then the debugger
commands in it are executed. ,B dbx also checks for a .dbxinit in your
home directory if there isn't one in the current directory.
dbx creates a separate transcript pad for debugger interactions unless
the -no_frame option is specified. dbx also creates a window to display
source code unless -no_src is specified.
OPTIONS
-r Executes objfile immediately. If it terminates successfully
dbx exits. Otherwise the reason for termination will be
reported and the user offered the option of entering the
debugger or letting the program fault. dbx reads from /dev/tty
when -r is specified and standard input is not a terminal.
Unless -r is specified, dbx just prompts and waits for a
command.
-i Forces dbx to act as though standard input is a terminal.
-I dir Adds dir to the list of directories that are searched when
looking for a source file. Normally dbx looks for source files
in the current directory and in the directory where objfile is
located. The directory search path can also be set with the
use command.
-c file Executes the dbx commands in the file before reading from
standard input.
-no_src Disables source display.
-no_frame Does not create a separate debugger transcript pad.
Execution and Tracing Commands
run [args] [< filename] [> filename]
rerun [args] [< filename] [> filename]
Start executing objfile, passing args as command line arguments; <
or > can be used to redirect input or output in the usual manner.
When rerun is used without any arguments the previous argument list
is passed to the program; otherwise it is identical to run. If
objfile has been written since the last time the symbolic
information was read in, dbx will read in the new information.
trace [in procedure/function] [if condition]
trace source-line-number [if condition]
trace procedure/function [in procedure/function] [if condition]
trace expression at source-line-number [if condition]
trace variable [in procedure/function] [if condition]
Have tracing information printed when the program is executed. A
number is associated with the command that is used to turn the
tracing off (see the delete command).
The first argument describes what is to be traced. If it is a
source-line-number, then the line is printed immediately prior to
being executed. Source line numbers in a file other than the
current one must be preceded by the name of the file in quotes and a
colon, e.g. "mumble.p":17.
If the argument is a procedure or function name then every time it
is called, information is printed telling what routine called it,
from what source line it was called, and what parameters were passed
to it. In addition, its return is noted, and if it's a function
then the value it is returning is also printed.
If the argument is an expression with an at clause then the value of
the expression is printed whenever the identified source line is
reached.
If the argument is a variable then the name and value of the
variable is printed whenever it changes. Execution is substantially
slower during this form of tracing.
If no argument is specified then all source lines are printed before
they are executed. Execution is substantially slower during this
form of tracing.
The clause "in procedure/function" restricts tracing information to
be printed only while executing inside the given procedure or
function.
Condition is a boolean expression and is evaluated prior to printing
the tracing information; if it is false then the information is not
printed.
stop if condition
stop at source-line-number [if condition]
stop in procedure/function [if condition]
stop variable [if condition]
Stop execution when the given line is reached, procedure or function
called, variable changed, or condition true.
status [> filename]
Print out the currently active trace and stop commands.
delete command-number ...
The traces or stops corresponding to the given numbers are removed.
The numbers associated with traces and stops are printed by the
status command.
catch number
catch signal-name
ignore number
ignore signal-name
Start or stop trapping a signal before it is sent to the program.
This is useful when a program being debugged handles signals such as
interrupts. A signal may be specified by number or by a name (e.g.,
SIGINT). Signal names are case insensitive and the "SIG" prefix is
optional. By default all signals are trapped except SIGCONT,
SIGCHILD, SIGALRM and SIGKILL.
cont integer
cont signal-name
Continue execution from where it stopped. If a signal is specified,
the process continues as though it received the signal. Otherwise,
the process is continued as though it had not been stopped.
Execution cannot be continued if the process has "finished", that
is, called the standard procedure "exit".
step Execute one source line.
next Execute up to the next source line. The difference between this and
step is that if the line contains a call to a procedure or function
the step command will stop at the beginning of that block, while the
next command will not.
return [procedure]
Continue until a return to procedure is executed, or until the
current procedure returns if none is specified.
call procedure(parameters)
Execute the object code associated with the named procedure or
function.
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 static
scope. If static and dynamic searches do not yield a result, an
arbitrary symbol is chosen and the message "[using qualified name]" is
printed. The name resolution procedure may be overridden by qualifying
an identifier with a block name, e.g., "module.variable". For C, source
files are treated as modules named by the file name without ".c".
Expressions are specified with an approximately common subset of C and
Pascal (or equivalently Modula-2) syntax. Indirection can be denoted
using either a prefix "*" or a postfix "^" and array expressions are
subscripted by brackets ("[ ]"). 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 may be
overridden by using "type-name(expression)". When there is no
corresponding named type the special constructs "&type-name" and "$$tag-
name" can be used to represent a pointer to a named type or C structure
tag.
assign variable = expression
Assign the value of the expression to the variable.
dump [procedure] [> filename]
Print the names and values of variables in the given procedure, or
the current one if none is specified. If the procedure given is
".", then the all active variables are dumped.
print expression [, expression ...]
Print out the values of the expressions.
whatis name
Print the declaration of the given name, which may be qualified with
block names as above.
which identifier
Print the full qualification of the given identifer, i.e. the outer
blocks that the identifier is associated with.
up [count]
down [count]
Move the current function, which is used for resolving names, up or
down the stack count levels. The default count is 1.
where
Print out a list of the active procedures and function.
whereis identifier
Print the full qualification of all the symbols whose name matches
the given identifier. The order in which the symbols are printed is
not meaningful.
Accessing Source Files
/regular expression[/]
?regular expression[?]
Search forward or backward in the current source file for the given
pattern.
edit [filename]
edit procedure/function-name
Invoke an editor on filename or the current source file if none is
specified. If a procedure or function name is specified, the editor
is invoked on the file that contains it. Which editor is invoked by
default depends on the installation. The default can be overridden
by setting the environment variable EDITOR to the name of the
desired editor.
file [filename]
Change the current source file name to filename. If none is
specified then the current source file name is printed.
func [procedure/function]
Change the current function. If none is specified then print the
current function. Changing the current function implicitly changes
the current source file to the one that contains the function; it
also changes the current scope used for name resolution.
list [source-line-number [, source-line-number]]
list procedure/function
List the lines in the current source file from the first line number
to the second inclusive. If no lines are specified, the next 10
lines are listed. If the name of a procedure or function is given
lines n-k to n+k are listed where n is the first statement in the
procedure or function and k is small.
use directory-list
Set the list of directories to be searched when looking for source
files. The directory-list is used if the specified file cannot be
found, or if the file is found but the modified time does not match
the time in the object module. If a file is found using directory-
list, or if the file's modified time is different then the source
display banner will display the filename being displayed as well as
the stored filename in parentheses.
Command Aliases and Variables
alias name name
alias name "string"
alias name (parameters) "string"
When commands are processed, dbx first checks to see if the word is
an alias for either a command or a string. If it is an alias, then
dbx treats the input as though the corresponding string (with values
substituted for any parameters) had been entered. For example, to
define an alias "rr" for the command "rerun", one can say
alias rr rerun
To define an alias called "b" that sets a stop at a particular line
one can say
alias b(x) "stop at x"
Subsequently, the command "b(12)" will expand to "stop at 12".
set name [= expression]
The set command defines values for debugger variables. The names of
these variables cannot conflict with names in the program being
debugged, and are expanded to the corresponding expression within
other commands. The following variables have a special meaning:
$hexchars
$hexints
$hexoffsets
$hexstrings
When set, dbx prints out out characters, integers, offsets from
registers, or character pointers respectively 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
parameters. This value is also used when displaying source in the
source window. The current line is positioned so that as much of
the listwindow as possible is visible. Its default value is 10.
$unsafecall
$unsafeassign
When "$unsafecall" is set, strict type checking is turned off for
arguments to subroutine or function calls (e.g. in the call
statement). When "$unsafeassign" is set, strict type checking
between the two sides of an assign statement is turned off. These
variables should be used only with great care, because they severely
limit dbx's usefulness for detecting errors.
unalias name
Remove the alias with the given name.
unset name
Delete the debugger variable associated with name.
Machine Level Commands
tracei [address] [if cond]
tracei [variable] [at address] [if cond]
stopi [if cond]
stop at address [if cond]
Turn on tracing or set a stop using a machine instruction address.
stepi
nexti
Single step as in step or next, but do a single instruction rather
than source line.
address ,address/ [mode]
address / [count] [mode]
Print the contents of memory starting at the first address and
continuing up to the second address or until count items are
printed. If the address is ".", 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:
i print the machine instruction
d print a short word in decimal
D print a long word in decimal
o print a short word in octal
O print a long word in octal
x print a short word in hexadecimal
X print a long word in hexadecimal
b print a byte in octal
c print a byte as a character
s print a string of characters terminated by a null byte
f print a single precision real number
g print a double precision real number
Symbolic addresses are specified by preceding the name with an "&".
Registers are denoted by $D0-$D7, for the data registers, and $A0-$A7,
for the address registers. For convenience, $DB, $SB, $SP, and $PC are
also available. Addresses may be expressions made up of other addresses
and the operators "+", "-", and indirection (unary "*").
Miscellaneous Commands
help Print out a synopsis of dbx commands.
quit Exit dbx.
sh command-line
Pass the command line to the shell for execution. The SHELL
environment variable determines which shell is used.
source filename
Read dbx commands from the given filename.
NOTES
Assignments to structures with bit fields does not work, and assigning
through a pointer variable may cause dbx to have a stack underflow and
abort.
Some problems remain with the support for individual languages. Fortran
problems include: inability to assign to logical, logical*2, complex and
double complex variables; inability to represent parameter constants
which are not type integer or real; peculiar representation for the
values of dummy procedures (the value shown for a dummy procedure is
actually the first few bytes of the procedure text; to find the location
of the procedure, use "&" to take the address of the variable).
FILES
a.out object file
.dbxinit initial commands
SEE ALSO
cc(1)