dbx(1) DG/UX 4.30 dbx(1)
NAME
dbx - debugger
SYNTAX
dbx [-r] [-s style] [-i] [-I dir] [objfile [corefile]]
DESCRIPTION
The dbx utility is a tool for source-level debugging and
execution of programs under the DG/UX system. Objfile is an
executable file--one that has been compiled and linked. The
compiler must use the appropriate flag (usually -g) to
produce symbol information in the object file. The
machine-level facilities of dbx can be used on any program
not linked with the -s option.
If no objfile is specified, dbx looks for a file named a.out
in the current directory.
When a corefile is specified, dbx can be used to examine the
state of the program when it faulted.
If the file .dbxinit exists in the current directory, dbx
executes the debugger commands in it. Dbx also checks for
.dbxinit in the user's home directory if there is not one in
the current directory. Note that the quit command is
ignored if it is found in a .dbxinit file.
Options are:
-r Execute objfile immediately. The object filename
must be supplied. Parameters follow the object
filename. When the program terminates, the reason
for termination is reported and the user can enter
the debugger or let the program fault. Dbx reads
from /dev/tty when -r is specified and standard
input is not a terminal.
-s style Inform dbx of the style of the symbol names in the
executable. By convention, style is the compile
command that produced the executable, e.g. cc,
gcc, ghcc, or ghf77. The -s option is required
only when the form of debugging information
differs from that produced by cc, the default
style.
-i Force dbx to act as though standard input is a
terminal.
-I dir Add dir to the list of directories that dbx
searches when looking for a source file. Normally
dbx looks for source files in the current
directory and in the directory where objfile is
Licensed material--property of copyright holder(s) Page 1
dbx(1) DG/UX 4.30 dbx(1)
located. The directory search path can also be
set with the use command.
Unless -r is specified, dbx just prompts and waits for a
command.
Expressions and Scope
Dbx evaluates an expression according to the scope that is
in effect at the time the expression is evaluated. This
scope determines which variables are accessible. For
example, the command
stop at "foo.c":5 if a == 17
contains the expression "a == 17", which will be evaluated
when line 5 of the file foo.c is reached. At that time, the
variable a must be either a local variable of the current
function or a global variable. The expression "a == 17"
must be legal in the language in which the file foo.c is
written. At present, C, FORTRAN 77, and Pascal are
supported languages.
Execution and Tracing Commands
run [args] [< filename] [> filename]
Execute the objfile specified on the dbx command line
or the one specified with the most recent debug
command. Args are passed as command line arguments.
Input and output can be redirected using the symbols <
and >. Other characters in args are passed through
unchanged. If no arguments are specified, the argument
list from the last run command (if any) is used. If
objfile has been written since the last time the
symbolic information was read in, dbx reads the new
information before beginning execution.
rerun [args] [< filename] [> filename]
Except in the case where no arguments are specified,
rerun is identical to run. When no arguments are
specified, rerun runs the program with no arguments at
all.
debug objfile [corefile]
Stop debugging the current program (if any), and begin
debugging the program found in objfile with the given
corefile. This process avoids the overhead required to
reinitialize dbx.
kill Stop debugging the current process, kill the process,
but leave dbx ready to debug another.
Licensed material--property of copyright holder(s) Page 2
dbx(1) DG/UX 4.30 dbx(1)
trace source-line-number [if condition]
trace @label[offset] [if condition]
trace procedure/function[offset] [if condition]
trace expression at source-line-number [if condition]
trace variable [in procedure/function] [if condition]
Print tracing information when the program is executed.
A number is associated with the trace command, which
may later be used to turn the tracing off (see the
delete and status commands).
The first argument describes what is to be traced. If
it specifies a source statement (by line number, label,
or offset from a procedure or function), the line or
label is printed immediately before being executed. An
offset is + or - some number of lines.
If the argument is a simple procedure or function name,
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.
If the argument is an expression with an at clause, the
value of the expression is printed whenever the
identified source line is reached.
If the argument is a variable, the name and value of
the variable are printed whenever it changes. The
clause in procedure/function restricts tracing
information to be printed only while executing inside
the specified procedure or function.
Source line numbers, labels, and function or variable
names may be qualified by a filename and following
colon, as in "mumble.c":17 (quotes are optional).
Condition is a boolean expression and is evaluated
before printing the tracing information; if it is
false, the information is not printed.
stop [at] source-line-number [if condition]
stop @label[offset] [if condition]
stop [in] procedure/function[offset] [if condition]
stop variable [if condition]
Stop execution when the given line or label is reached,
the procedure or function is called, or the variable is
changed. If the line number specified is out of range
(beyond EOF), the stop will be executed at the last
line of the file.
status [> filename]
Print out the currently active trace and stop commands.
Licensed material--property of copyright holder(s) Page 3
dbx(1) DG/UX 4.30 dbx(1)
commands [command-number]
Attach a series of commands to the specified trace or
stop command (or to the last one that was set) to be
performed whenever the trace or stop is taken. The
commands, which may be any debugger commands including
those that resume or redirect execution, are entered on
successive lines and delimited by the end command on a
separate line. You may use an if/then/else construct
to specify alternate actions based on a conditional
expression.
delete command-number
Remove the trace or stop corresponding to the given
number. The numbers associated with traces and stops
are printed by the status command. Delete all removes
all traces and stops.
clear [source-line-number]
clear @label
clear procedure/function
clear variable
Delete all traces or stops set on the given line-
number, label, function, or variable. Clear without
argument clears all traces or stops on the line at
which execution is stopped.
catch [number]
ignore [number]
Start or stop trapping signal number before it is sent
to the program. This command is useful when a program
being debugged handles signals such as interrupts.
Initially, all signals are trapped except SIGCONT,
SIGCLD, SIGALRM, and SIGKILL. Without arguments, catch
and ignore display a list of signals currently trapped
or ignored.
cont [n]
Continue execution. If n is specified, ignore the
current breakpoint until it has been reached this
number of times. Execution cannot be continued if the
process has called the standard procedure `exit'. Dbx
tries to keep the process from exiting, thereby letting
the user examine the program state.
jump source-line-number
jump procedure/function[offset]
jump @label[offset]
Continue execution from the given source line,
procedure, or label.
finish
Continue execution until the current frame is exited.
Licensed material--property of copyright holder(s) Page 4
dbx(1) DG/UX 4.30 dbx(1)
step [n]
Execute one or more source lines.
next [n]
Execute one or more source lines, but do not follow
procedure or function calls. The difference between
next and step is that if a line contains a call to a
procedure or function, step stops at the beginning of
that block, whereas next continues execution to the
next immediate source line.
Displaying and Naming Data
You must be at a valid breakpoint for these commands to
function properly.
print[/format] expression [, expression ...]
Print out the values of the expressions. The optional
format is one of x (hexadecimal), d (signed decimal), u
(unsigned decimal), o (octal), or c (character). A
valid expression may refer to variables in the current
procedure; it may also invoke any procedure or function
in the program.
call subroutine [(arg [,arg...])]
Call a FORTRAN 77 subroutine.
whatis name
Print the declaration of the given name. Longs are
reported as ints, and tags are reported as typedefs.
assign variable = expression
set variable = expression
Assign the value of the expression to the variable.
where [n]
Display the call/return stack. If n is specified, show
only the topmost n frames of the stack.
up [n]
Move up the call stack n levels in the direction of
main. If n is not specified, the default is 1. This
command allows you to examine the local variables in
functions other than the current one.
down [n]
Move down the call stack n levels towards the current
stopping point. If n is not specified, the default is
1.
describe [procedure/function]
Describe the current or specified procedure or
Licensed material--property of copyright holder(s) Page 5
dbx(1) DG/UX 4.30 dbx(1)
function, including its name, address, and source
coordinates.
describe source-line-number
describe @label
Describe the given source line or label, including the
associated starting address and the name of the program
block.
args Display the arguments to the current procedure or
function.
dump [> filename]
Print the names and values of all local variables.
Accessing Source Files
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. The default editor depends on the
installation. To override the default, set the
environment variable EDITOR to the name of the desired
editor.
file [filename]
Change the current source filename to filename. If you
omit filename, the current source filename is printed.
func [procedure/function]
Change the current function. If no function is
specified, print the name of current function.
Changing the current function implicitly changes the
current source file to the one that contains the
function.
list [[filename:]linespec [, linespec]]
List the lines in the current (or specified) source
file from the first line specified through the second,
or print a window of lines surrounding a single line.
If no lines are specified, list 10 more lines. A
linespec may be a source line number, label, or
function name with optional offset. It may also be a
simple offset (+ or - some number), which specifies an
offset from the last line printed, or from the first of
two linespecs in a list command. $ used as a line
number means the last line in the file.
Licensed material--property of copyright holder(s) Page 6
dbx(1) DG/UX 4.30 dbx(1)
use directory-list
Set the list of directories to be searched when dbx
looks for source files.
Machine-level Commands
address ,address/ [mode]
[address] / [n] [mode]
Print the contents of memory starting at the first
address and continuing up to the second address or
until n items are printed. If no address is specified,
the address following the one printed most recently is
used. Mode specifies how memory is to be printed; if
mode is omitted, the previous mode specified is used.
The initial mode is O. The following modes are
supported:
i a machine instruction
d a short word in decimal
D a long word in decimal
o a short word in octal
O a long word in octal
x a short word in hexadecimal
X a long word in hexadecimal
b two bytes in octal
c two bytes as characters
s a string of characters terminated by a null byte
f a single precision real number
g a double precision real number
Symbolic addresses are specified by preceding the name with
an &. Registers are referred to with the following symbolic
names:
$zero register 0
$rn register n, n = 1-25
$linkern register n, n = 26-29
$fp frame pointer
$sp stack pointer
$srp subroutine return pointer
$psr processor status register
$fpsr floating-point user status register
$fpcr floating-point user control register
$pid processor identification register
$sxip execution instruction pointer
$snip next instruction pointer
$sfip fetch instruction pointer
Addresses may be expressions made up of other addresses and
the operators +, -, and indirection (unary *).
Licensed material--property of copyright holder(s) Page 7
dbx(1) DG/UX 4.30 dbx(1)
stepi [n]
nexti [n]
Single step as in step or next, but do a single instruction
rather than source line.
tracei [address] [if condition]
tracei [variable] [at address] [if condition]
stopi [address] [if condition]
stopi [at] [address] [if condition]
Turn on tracing or set a stop using a machine instruction
address.
Miscellaneous Commands
sh [command-line]
Pass the command line to the shell for execution.
Without argument, sh suspends the debugging session and
enters a shell. The SHELL environment variable
determines which shell is used.
define macro-name
Define a macro with the given name; the body of the
macro is entered on successive lines and delimited by
the end command on a separate line. Arguments to the
macro are denoted by #1, #2, and so on.
alias [new-command-name [old-command-name]]
Respond to new-command-name as though it were old-
command-name. Invoked with new-command-name only,
alias prints the old-command-name associated with new-
command-name. Invoked without arguments, alias prints
a list of currently-defined aliases.
save filename
Save the state of the debugging session in the
specified file (if file exists, it is first deleted).
The state comprises stop and trace commands (with any
associated commands), user-defined macros, and aliases.
restore filename
Restore the debugger state saved in the specified file.
help [command]
Print out a summary of dbx commands, or a synopsis of
the given command.
source filename
Read dbx commands from the given filename. Especially
useful when the filename has been created by
redirecting a status command from an earlier debugging
session.
Licensed material--property of copyright holder(s) Page 8
dbx(1) DG/UX 4.30 dbx(1)
style stylename
Inform dbx of the style of the symbol names in the
executable to be debugged. By convention, stylename is
the compile command originally used to produce the
executable: currently valid stylenames are cc, gcc,
ghcc, and ghf77. The default style is cc.
quit Exit from dbx.
FILES
a.out Object file
.dbxinit Initial commands
SEE ALSO
cc(1), gcc(1), ghcc(1), ghf77(1).
CAVEATS
Non-local goto commands can cause some trace/stops to be
missed.
Licensed material--property of copyright holder(s) Page 9