path: root/static/v10/man1/db.1

.pa 1
.he 'DB (I)'3/15/72'DB (I)'
.ti 0
NAME		db -- debug
.sp
.ti 0
SYNOPSIS	db__ [ core [ namelist ] ] [ -_ ]
.sp
.ti 0
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.
.sp
The format for most db__ requests is an address followed
by a one character command.
.sp
Addresses are expressions built up as follows:
.sp
.in +6
.un 3
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.
.br
.un 3
.sp
2. An octal number is an absolute quantity with the appropriate
value.
.br
.un 3
.sp
3. A decimal number immediately followed by "." is
an absolute quantity with the appropriate value.
.br
.un 3
.sp
4. An octal number immediately followed by "r" is a relocatable
quantity with the appropriate value.
.br
.un 3
.sp
5. The symbol "." indicates the current pointer
of db__.  The current pointer is set by many db__ requests.

.ti -3
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 "*.".

.ti -3
6. 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.
.br
.un 3
.sp
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.
.br
.un 3
.sp
9. Expressions are evaluated left to right.
.sp 1
.in -6
Names for registers are
built in:
.sp
   r0 ... r5
   sp
   pc
   fr0 ... fr5
.sp
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.
.sp
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__.
.sp
There are db__ commands for examining locations
interpreted as octal 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.
.sp
.in +6
.un 3
/  The addressed word is printed in octal.

.un 3
\\  The addressed byte is printed in octal.

.un 3
"  The addressed word is printed as two ASCII characters.

.un 3
'  The addressed byte is printed as an ASCII character.
.ti -3

`  The addressed word is printed in decimal.

.un 3
?  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.
.br
.un 3

&  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.
.br
.un 3

<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.
.br
.un 3

^  This character decrements "." and prints the
resulting location in the mode last selected
one of the above requests.  It is a converse to <nl>.

.un 3
%  Exit.
.sp
.in -6
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.
.sp
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.
.sp
There are two commands to interpret the value
of expressions.
.sp
.in +6
.un 3
=  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 ".".
.br
.un 3

:  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.
.sp
.in -6
The following command may be used to patch the file being debugged.
.sp
.in +6
.un 3
!  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.

.sp
.in -6
The following command is used after a fault has caused
a core image file to be produced.
.sp
.in +6
.un 3
$  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.
.sp
.in -6
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
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, 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 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 last 512(10) bytes
of the core file,
can be addressed at apparent locations 160000-160777.

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.

.ti 0
FILES		--
.sp
.ti 0
SEE ALSO	as(I), core(V), a.out(V), od(I)
.sp
.ti 0
DIAGNOSTICS	"File not found" if the first argument
cannot be read; otherwise "?".
.sp
.ti 0
BUGS		--