11/3/71 DB (I)
NAME db -- debug
SYNOPSIS db [ core [ namelist ] ]
DESCRIPTION Unlike many debugging packages (including DEC's
ODT, on which db is loosely based) db is not
loaded as part of the core image which it is used
to examine; instead it examines files. Typi-
cally, the file will be either a core image pro-
duced after a fault or the binary output of the
assembler. Core is the file being debugged; if
omitted "core" is assumed. namelist is a file
containing a symbol table. If it is omitted,
a.out is the default. If no appropriate name
list file can be found, db can still be used but
some of its symbolic facilities become unavail-
able.
The format for most db requests is an address
followed by a one character command.
Addresses are expressions built up as follows:
1. A name has the value assigned to it when
the input file was assembled. It may be
relocatable or not depending on the use of
the name during the assembly.
2. An octal number is an absolute quantity
with the appropriate value.
3. An octal number immediately followed by "r"
is a relocatable quantity with the appro-
priate value.
4. The symbol "." indicates the current
pointer of db. The current pointer is set
by many db requests.
5. Expressions separated by "+" or " " (blank)
are expressions with value equal to the sum
of the components. At most one of the com-
ponents may be relocatable.
6. Expressions separated by "-" form an ex-
pression with value equal to the difference
to the components. If the right component
is relocatable, the left component must be
relocatable.
7. Expressions are evaluated left to right.
Names for registers are built in:
r0 ... r5
sp
pc
ac
mq
These may be examined. Their values are deduced
from the contents of the stack in a core image
file. They are meaningless in a file that is not
a core image.
If no address is given for a command, the current
address (also specified by ".") is assumed. In
general, "." points to the last word or byte
printed by db.
There are db commands for examining locations in-
terpreted as octal numbers, machine instructions,
ASCII characters, and addresses. For numbers and
characters, either bytes or words may be exam-
ined. The following commands are used to examine
the specified file.
/ The addressed word is printed in octal.
\ The addressed byte is printed in octal.
" The addressed word is printed as two ASCII
characters.
' The addressed byte is printed as an ASCII
character.
` The addressed word is multiplied by 2, then
printed in octal (used with B programs,
whose addresses are word addresses).
? The addressed word is interpreted as a ma-
chine instruction and a symbolic form of
the instruction, including symbolic ad-
dresses, is printed. Often, the result
will appear exactly as it was written in
the source program.
& The addressed word is interpreted as a sym-
bolic address and is printed as the name of
the symbol whose value is closest to the
addressed word, possibly followed by a
signed offset.
<nl> (i. e., the character "new line") This
command advances the current location
counter "." and prints the resulting loca-
tion in the mode last specified by one of
the above requests.
^ This character decrements "." and prints
the resulting location in the mode last se-
lected one of the above requests. It is a
converse to <nl>.
It is illegal for the word-oriented commands to
have odd addresses. The incrementing and decre-
menting of "." done by the <nl> and ^ requests is
by one or two depending on whether the last com-
mand was word or byte oriented.
The address portion of any of the above commands
may be followed by a comma and then by an expres-
sion. In this case that number of sequential
words or bytes specified by the expression is
printed. "." is advanced so that it points at
the last thing printed.
There are two commands to interpret the value of
expressions.
= When preceded by an expression, the value
of the expression is typed in octal. When
not preceded by an expression, the value of
"." is indicated. This command does not
change the value of ".".
: An attempt is made to print the given ex-
pression as a symbolic address. If the ex-
pression is relocatable, that symbol is
found whose value is nearest that of the
expression, and the symbol is typed, fol-
lowed by a sign and the appropriate offset.
If the value of the expression is absolute,
a symbol with exactly the indicated value
is sought and printed if found; if no
matching symbol is discovered, the octal
value of the expression is given.
The following command may be used to patch the
file being debugged.
! This command must be preceded by an expres-
sion. The value of the expression is
stored at the location addressed by the
current value of ".". The opcodes do not
appear in the symbol table, so the user
must assemble them by hand.
The following command is used after a fault has
caused a core image file to be produced.
$ causes the contents of the general regis-
ters and several other registers to be
printed both in octal and symbolic format.
The values are as they were at the time of
the fault.
The only way to exit from db is the generate an
end of file on the typewriter (EOT character).
FILES --
SEE ALSO as; core for format of core image.
DIAGNOSTICS "File not found" if the first argument cannot be
read; otherwise "?".
BUGS Really, db should know about relocation bits,
floating point operations, and PDP11/45 instruc-
tions.
OWNER dmr