DBX(1) DOMAIN/IX SYS5 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 DOMAIN/IX. 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. Dbx also checks
for a ".dbxinit" in the user's home directory if there isn't
one in the current directory.
Dbx will create a separate transcript pad for debugger
interactions unless the -no_frame option is specified. Dbx
will also create a window to display source code unless the
-no_src is specified.
OPTIONS
The command line options and their meanings are:
-r Execute 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 will read from "/dev/tty" when
-r is specified and standard input is not a termi-
nal.
-i Force dbx to act as though standard input is a
terminal.
-I dir Add dir to the list of directories that are
searched when looking for a source file. Normally
dbx looks for source files in the current direc-
tory and in the directory where objfile is
located. The directory search path can also be
set with the use command.
Printed 12/4/86 DBX-1
DBX(1) DOMAIN/IX SYS5 DBX(1)
-c file Execute the dbx commands in the file before read-
ing from standard input.
-no_src Disable source display.
-no_frame Do not create a separate debugger transcript pad.
Unless -r is specified, dbx just prompts and waits for a
command.
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 out-
put 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 sym-
bolic 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 com-
mand).
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
DBX-2 Printed 12/4/86
DBX(1) DOMAIN/IX SYS5 DBX(1)
identified source line is reached.
If the argument is a variable then the name and value
of the variable is printed whenever it changes. Execu-
tion is substantially slower during this form of trac-
ing.
If no argument is specified then all source lines are
printed before they are executed. Execution is sub-
stantially 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, pro-
cedure or function called, variable changed, or condi-
tion 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
Printed 12/4/86 DBX-3
DBX(1) DOMAIN/IX SYS5 DBX(1)
is specified, the process continues as though it
received the signal. Otherwise, the process is contin-
ued as though it had not been stopped. Execution can-
not 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 speci-
fied.
call procedure(parameters)
Execute the object code associated with the named pro-
cedure 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 qualify-
ing an identifier with a block name, e.g.,
"module.variable". For C, source files are treated as
modules named by the file name in uppercase with the string
"_c" substituted for ".c", eg., "x.c" => "X_C".
Expressions are specified with an approximately common sub-
set 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 brack-
ets ("[ ]"). 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
DBX-4 Printed 12/4/86
DBX(1) DOMAIN/IX SYS5 DBX(1)
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 vari-
ables 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 associ-
ated 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
Printed 12/4/86 DBX-5
DBX(1) DOMAIN/IX SYS5 DBX(1)
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 over-
ridden 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 func-
tion 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
DBX-6 Printed 12/4/86
DBX(1) DOMAIN/IX SYS5 DBX(1)
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 respec-
tively in hexadecimal.
$listwindow
The value of this variable specifies the number of
lines to list around a function or when the list com-
mand 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 "$unsafeas-
sign" 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
Printed 12/4/86 DBX-7
DBX(1) DOMAIN/IX SYS5 DBX(1)
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 instruc-
tion 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 sup-
ported:
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
DBX-8 Printed 12/4/86
DBX(1) DOMAIN/IX SYS5 DBX(1)
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 con-
venience, $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.
FILES
a.out object file
.dbxinit initial commands
RELATED INFORMATION
cc(1)
COMMENTS
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).
Printed 12/4/86 DBX-9