3/15/72 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, the
symbol table is obtained from the file being de-
bugged, or if not there from a.out. If no appro-
priate name list file can be found, db can still
be used but some of its symbolic facilities be-
come unavailable.
For the meaning of the optional third argument,
see the last paragraph below.
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
fr0 ... fr5
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 printed in decimal.
? 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>.
% Exit.
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 fault type and the contents of
the general registers 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.
Db should not be used to examine special files,
for example disks and tapes, since it reads one
byte at a time. Use od(I) instead.
For some purposes, it is important to know how
addresses typed by the user correspond with loca-
tions in the file being debugged. The mapping
algorithm employed by db is non-trivial for two
reasons: First, in an a.out file, there is a
20(8) byte header which will not appear when the
file is loaded into core for execution. There-
fore, apparent location 0 should correspond with
actual file offset 20. Second, some systems
cause a "squashed" core image to be written. In
such a core image, addresses in the stack must be
mapped according to the degree of squashing which
has been employed. Db obeys the following rules:
If exactly one argument is given, and if it ap-
pears to be an a.out file, the 20-byte header is
skipped during addressing, i.e., 20 is added to
all addresses typed. As a consequence, the
header can be examined beginning at location -20.
If exactly one argument is given and if the file
does not appear to be an a.out file, no mapping
is done.
If zero or two arguments are given, the mapping
appropriate to a core image file is employed.
This means that locations above the program break
and below the stack effectively do not exist (and
are not, in fact, recorded in the core file).
Locations above the user's stack pointer are
mapped, in looking at the core file, to the place
where they are really stored. The per-process
data kept by the system, which is stored in the
last 512(10) bytes of the core file, can be ad-
dressed at apparent locations 160000-160777.
If one wants to examine a file which has an asso-
ciated name list, but is not a core image file,
the last argument "-" can be used (actually the
only purpose of the last argument is to make the
number of arguments not equal to two). This fea-
ture is used most frequently in examining the
memory file /dev/mem.
FILES --
SEE ALSO as(I), core(V), a.out(V), od(I)
DIAGNOSTICS "File not found" if the first argument cannot be
read; otherwise "?".
BUGS The "^" request always decrements "." by 2, even
in byte mode.
OWNER dmr