DB(I) 8/20/73 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. Typically, 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
debugged, or if not there from a.out. If no appropriate
name list file can be found, db can still be used but some
of its symbolic facilities become 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 appro-
priate value.
3. A decimal number immediately followed by `.' is an abso-
lute quantity with the appropriate value.
4. An octal number immediately followed by r is a relocat-
able quantity with the appropriate value.
5. The symbol . indicates the current pointer of db. The
current pointer is set by many db requests.
6. A * before an expression forms an expression whose value
is the number in the word addressed by the first expres-
sion. A * alone is equivalent to `*.'.
7. Expressions separated by + or blank are expressions with
value equal to the sum of the components. At most one
of the components may be relocatable.
8. Expressions separated by - form an expression with value
equal to the difference to the components. If the right
component is relocatable, the left component must be re-
locatable.
- 1 -
DB(I) 8/20/73 DB(I)
9. 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 con-
tents 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 interpreted as num-
bers, machine instructions, ASCII characters, and addresses. For
numbers and characters, either bytes or words may be examined.
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 machine instruc-
tion and a symbolic form of the instruction, including
symbolic addresses, is printed. Often, the result will
appear exactly as it was written in the source program.
& The addressed word is interpreted as a symbolic 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 ad-
vances the current location counter ``.'' and prints the
resulting location in the mode last specified by one of
the above requests.
^ This character decrements ``.'' and prints the resulting
location in the mode last selected one of the above re-
quests. It is a converse to <nl>.
% Exit.
Odd addresses to word-oriented commands are rounded down. The
incrementing and decrementing of ``.'' done by the <nl> and ^ re-
quests is by one or two depending on whether the last command was
- 2 -
DB(I) 8/20/73 DB(I)
word or byte oriented.
The address portion of any of the above commands may be followed
by a comma and then by an expression. 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 expres-
sion is typed in octal. When not preceded by an expres-
sion, the value of ``.'' is indicated. This command
does not change the value of ``.''.
: An attempt is made to print the given expression as a
symbolic address. If the expression is relocatable,
that symbol is found whose value is nearest that of the
expression, and the symbol is typed, followed by a sign
and the appropriate offset. If the value of the expres-
sion 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 de-
bugged.
! This command must be preceded by an expression. The
value of the expression is stored at the location ad-
dressed by the current value of ``.''. The opcodes do
not appear in the symbol table, so the user must assem-
ble them by hand.
The following command is used after a fault has caused a core im-
age 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.
For some purposes, it is important to know how addresses typed by
the user correspond with locations in the file being debugged.
The mapping algorithm employed by db is non-trivial for two rea-
sons: 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.
Therefore, apparent location 0 should correspond with actual file
offset 20. Second, addresses in core images do not correspond
with the addresses used by the program because in a core image
there is a header containing the system's per-process data for
the dumped process, and also because the stack is stored contigu-
ously with the text and data part of the core image rather than
at the highest possible locations. Db obeys the following rules:
If exactly one argument is given, and if it appears to be an
- 3 -
DB(I) 8/20/73 DB(I)
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 first part of the core
file, cannot currently be examined (except by $).
If one wants to examine a file which has an associated 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 feature is used most
frequently in examining the memory file /dev/mem.
SEE ALSO
as(I), core(V), a.out(V), od(I)
DIAGNOSTICS
``File not found'' if the first argument cannot be read; other-
wise ``?''.
BUGS
There should be some way to examine the registers and other per-
process data in a core image; also there should be some way of
specifying double-precision addresses. It does not know yet
about shared text segments.
- 4 -