dbx(1) DG/UX 5.4.2 dbx(1)
NAME
dbx - source level debugger
SYNOPSIS
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(s) 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.
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 debugging a
COFF executable whose of debugging information differs in
form 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 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
Licensed material--property of copyright holder(s) 1
dbx(1) DG/UX 5.4.2 dbx(1)
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 a legal C language expression.
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 | pid]
Stop debugging the current program (if any), and begin
debugging the program found in objfile with the given corefile
or pid number. When a pid number is supplied, dbx attaches to
that running process.
Use the debug command to avoid the overhead required to
reinitialize dbx.
kill Stop debugging the current process, kill the process, but
leave dbx ready to debug another.
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.
Licensed material--property of copyright holder(s) 2
dbx(1) DG/UX 5.4.2 dbx(1)
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 and function 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.
status [> filename]
Print out the currently active trace and stop commands.
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 [,command-number...]
Remove the traces or stops corresponding to the given numbers.
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
Licensed material--property of copyright holder(s) 3
dbx(1) DG/UX 5.4.2 dbx(1)
all traces or stops on the line at which execution is stopped.
catch [signal [,signal...]]
ignore [signal [,signal...]]
Start or stop trapping the specified signals before they are
sent to the program; a signal may be identified by its number
or its name. 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.
position source-line-number
position procedure/function[offset]
position @label[offset]
Set the current instruction pointer to the indicated position.
Execution does not resume until directed by the user.
Positioning to a different stack frame may have unpredictable
results.
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.
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
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), c (character), or b (binary). A valid
expression may refer to variables in the current procedure; it
may also invoke any procedure or function in the program.
Licensed material--property of copyright holder(s) 4
dbx(1) DG/UX 5.4.2 dbx(1)
call subroutine [(arg [,arg...])]
Call a FORTRAN 77 subroutine.
whatis name
Print the declaration of the given name. In debugging COFF
executables, 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 and n < 0,
show the bottommost n frames of the stack. If n is specified
and n > 0, show 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 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.
echo string
Print a constant string; C escape sequences must be used to
print newlines and leading or trailing whitespace.
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
Licensed material--property of copyright holder(s) 5
dbx(1) DG/UX 5.4.2 dbx(1)
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.
pwd Print dbx's notion of the working directory.
cd directory
Change dbx's working directory. The change does not take
effect for the program being debugged until the next time it
is started.
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 H. 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
Licensed material--property of copyright holder(s) 6
dbx(1) DG/UX 5.4.2 dbx(1)
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:
$r0 zero
$r1 subroutine return pointer
$r2-$r9 called procedure parameter registers
$r10-$r13 called procedure temporary registers
$r14-$r25 calling procedure reserved registers
$r26-$r29 linker
$r30 frame pointer
$r31 stack pointer
$fp frame pointer (register 30)
$sp stack pointer (register 31)
$fpsr floating-point status register
$fpcr floating-point control register
$psr processor status register
$sxip shadow execute instruction pointer
$snip shadow next instruction pointer
$sfip shadow fetched instruction pointer
$cfa canonical frame address pseudo-register
$pc program counter pseudo-register
Addresses may be expressions made up of other addresses and the
operators +, -, and indirection (unary *).
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 [at] [address] [if condition]
Turn on tracing or set a stop using a machine instruction
address.
position address
Set the current instruction pointer to the specified 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.
Licensed material--property of copyright holder(s) 7
dbx(1) DG/UX 5.4.2 dbx(1)
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 [character-sequence]]
Respond to new-command-name as though it were character-
sequence. Arguments to the alias are permitted, and are
denoted by #1, #2, and so on. Invoked with new-command-name
only, alias prints the character-sequence 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.
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.
When debugging ELF executables, the style command serves no
purpose, and is ignored.
quit Exit from dbx.
FILES
a.out Object file
.dbxinit Initial commands
SEE ALSO
cc(1), gcc(1), ghcc(1), ghf77(1).
NOTES
Non-local goto commands can cause some trace/stops to be missed.
Licensed material--property of copyright holder(s) 8
dbx(1) DG/UX 5.4.2 dbx(1)
When debugging an ELF executable, dbx supports editread functionality
for manipulating previous commands; see editread(5).
Licensed material--property of copyright holder(s) 9