DB(I)                        8/20/73                        DB(I)

     db - debug

     db [ core [ namelist ] ] [ - ]

     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-

                              - 1 -

DB(I)                        8/20/73                        DB(I)

      9. Expressions are evaluated left to right.

Names for registers are built in:

   r0 ... r5
   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

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-

      !  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.

as(I), core(V), a.out(V), od(I)

``File not found'' if the first argument cannot be  read;  other-
wise ``?''.

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 -