dbx(1)
_________________________________________________________________
dbx Command
debugger in DG/UX
_________________________________________________________________
SYNTAX
dbx [ -r ] [ -i ] [ -I dir ] [ objfile [ coredump|PID ]]
DESCRIPTION
Dbx is a tool for source-level debugging and execution of
programs under DG/UX. 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. Currently, cc(1), f77(1) and pc(1) produce the
appropriate source information. 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.
If a file named core exists in the current directory or a
coredump file is specified, dbx can be used to examine the state
of the program when it faulted. If - is specified for coredump,
then no core file is used, even if a file named core exists in
the current directory.
If a numeric PID is specified, then dbx attempts to find a
process with that process ID, attaches to it, and stops it. The
process can then be debugged as if it had been run from dbx.
If the file .dbxinit exists in the current directory, then the
debugger commands in it are executed. Dbx also checks for
.dbxinit in the user's home directory if there isn't 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.
-i Force dbx to act as though standard input is a terminal.
DG/UX 4.00 Page 1
Licensed material--property of copyright holder(s)
dbx(1)
-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 and what language the
expression must be written in. 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 and
FORTRAN 77 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 | process-id]
Stop debugging the current program (if any), and begin
debugging the program found in objfile with the given
corefile or live process. This process avoids the overhead
required to reinitialize dbx.
DG/UX 4.00 Page 2
Licensed material--property of copyright holder(s)
dbx(1)
kill Stop debugging the current process, kill the process, but
leave dbx ready to debug another.
trace source-line-number [if condition]
trace procedure/function [if condition]
trace expression at source-line-number [if condition]
trace variable [if condition]
Print tracing information when the program is executed. A
number is associated with the command that turns 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
before 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.c":17.
If the argument is a 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, then 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.
Condition is a boolean expression and is evaluated before
printing the tracing information; if it is false then the
information is not printed.
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, 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.
delete command-number
The trace or stop corresponding to the given number is
removed. The numbers associated with traces and stops are
printed by the status command.
catch number
ignore number
DG/UX 4.00 Page 3
Licensed material--property of copyright holder(s)
dbx(1)
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.
cont Continue execution from where it stopped. 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.
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, step stops at the beginning of that
block, whereas next does not.
Displaying and Naming Data
You must be at a valid break point for these commands to function
properly.
print expression [, expression ...]
Print out the values of the expressions.
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
Print out a list of the active procedures and function.
up [ n]
Move up the call stack n levels in the direction of main.
If is not specified, the default is one. 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 one.
dump [> filename]
Print the names and values of all local variables.
DG/UX 4.00 Page 4
Licensed material--property of copyright holder(s)
dbx(1)
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,
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 through the second. 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. $ used as a line number means the last line in the
file.
use directory-list
Set the list of directories to be searched when dbx looks
for source files.
Machine-level Commands
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 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:
DG/UX 4.00 Page 5
Licensed material--property of copyright holder(s)
dbx(1)
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 two bytes in octal
c Print two bytes as characters
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 referred to with the following symbolic
names:
$ac0 - accumulator 0
$ac1 - accumulator 1
$ac2 - accumulator 2
$ac3 - accumulator 3
$pc - program counter
$wfp - wide frame pointer
$wsb - wide stack base
$wsl - wide stack limit
$wsp - wide stack pointer
Addresses may be expressions made up of other addresses and
the operators +, -, and indirection (unary *).
stepi
nexti Single step as in step or next, but do a single
instruction rather than source line.
tracei [address] [if cond]
tracei [variable] [at address] [if cond]
stopi [address] [if cond]
stopi [at] [address] [if cond]
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. The SHELL
environment variable determines which shell is used.
alias new-command-name old-command-name
Respond to new-command-name as though it were old-command-
name.
DG/UX 4.00 Page 6
Licensed material--property of copyright holder(s)
dbx(1)
help Print out a synopsis of dbx commands.
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), f77(1), pc(1).
CAVEATS
Non-local goto commands can cause some trace/stops to be missed.
DG/UX 4.00 Page 7
Licensed material--property of copyright holder(s)