    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 -