dbx(1) DG/UX R4.11MU05 dbx(1)
NAME
dbx - source level debugger
SYNOPSIS
dbx [-r] [-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.
-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
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. Execution
continues until an event such as a breakpoint, watchpoint or
signal occurs. 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.
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
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.
Threads-related Commands
Note: These commands are supported only when debugging ELF
executables.
conditions address [, address ...]
Print information about the condition variables at the
specified addresses.
focus [thread-id]
If a thread-id is specified, set the focus to the related
thread. Otherwise print the status of the thread.
mutexes address [, address ...]
Print information about the mutexes at the specified
addresses.
threads [thread-id [, thread-id ...]]
If one or more thread-ids is specified, print the status of
the related threads. Otherwise print the status of all
threads.
tspecific number thread-id [, thread-id ...]
Make the specified stop or trace sensitive only to the
specified threads.
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.
call subroutine [(arg [,arg...])]
Call a 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
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
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
On the Intel platform:
$eax return value
$edx scratch register (dividend: divide operations)
$ecx scratch register (count: shift and string operations)
$ebx local register variable
$ebp stack frame pointer
$esi local register variable
$edi local register variable
$esp stack pointer
$efl flags register
$eip instruction pointer
$pc program counter pseudo-register ($eip alias)
$ds..$gs various segment registers
$fpcw floating-point control word
$fpsw floating-point status word
$fptw floating-point tag word
$st0-$st7 floating-point stack registers
$st alias for $st0
On the 88K platform:
$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
The MC-88110 adds the following integer pseudo-register:
$swsr floating-point status register
The MC-88110 also contains 32 extended registers, each of which
contains 80 bits. They are referred to with the following symbol
names:
$x0 zero
$x1-$x21 called procedure temporary registers
$x22-$x29 calling procedure reserved registers
$x30-$x31 reserved registers
Each extended register is viewed as a union with single-, double- and
extended-precision floating-point fields. The MC-88110 registers are
only available when debugging an ELF object.
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.
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.
quit Exit from dbx.
FILES
a.out Object file
.dbxinit Initial commands
SEE ALSO
cc(1), gcc(1) legend(5).
NOTES
Non-local goto commands can cause some trace/stops to be missed.
dbx supports editread functionality for manipulating previous
commands; see editread(5).
Licensed material--property of copyright holder(s)