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
produced 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
appropriate value.
3. A decimal number immediately followed by `.' is an
absolute quantity with the appropriate value.
4. An octal number immediately followed by r is a
relocatable 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
expression. 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 relocatable.
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
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 interpreted as
numbers, 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
instruction 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
advances 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 requests. 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 ^
requests is by one or two depending on whether the last command
was 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
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 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
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 expression. 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.
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
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. 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 512-byte header containing the system's
per-process data for the dumped process, and also because the
stack is stored contiguously 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
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 512(10) bytes 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;
otherwise ``?''.
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.