11/3/71                                                    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.  Typi-

                cally, 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,

                a.out is the default.  If no appropriate name

                list file can be found, db can still be used but

                some of its symbolic facilities become unavail-


                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. An octal number immediately followed by "r"

                      is a relocatable quantity with the appro-

                      priate value.

                   4. The symbol "." indicates the current

                      pointer of db.  The current pointer is set

                      by many db requests.

                   5. Expressions separated by "+" or " " (blank)

                      are expressions with value equal to the sum

                      of the components.  At most one of the com-

                      ponents may be relocatable.

                   6. Expressions separated by "-" form an ex-

                      pression with value equal to the difference

                      to the components.  If the right component

                      is relocatable, the left component must be


                   7. Expressions are evaluated left to right.

                Names for registers are built in:

                   r0 ... r5





                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 in-

                terpreted as octal numbers, machine instructions,

                ASCII characters, and addresses.  For numbers and

                characters, either bytes or words may be exam-

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


                   '  The addressed byte is printed as an ASCII


                   `  The addressed word is multiplied by 2, then

                      printed in octal (used with B programs,

                      whose addresses are word addresses).

                   ?  The addressed word is interpreted as a ma-

                      chine instruction and a symbolic form of

                      the instruction, including symbolic ad-

                      dresses, is printed.  Often, the result

                      will appear exactly as it was written in

                      the source program.

                   &  The addressed word is interpreted as a sym-

                      bolic 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 loca-

                      tion in the mode last specified by one of

                      the above requests.

                   ^  This character decrements "." and prints

                      the resulting location in the mode last se-

                      lected one of the above requests.  It is a

                      converse to <nl>.

                It is illegal for the word-oriented commands to

                have odd addresses.  The incrementing and decre-

                menting of "." done by the <nl> and ^ requests is

                by one or two depending on whether the last com-

                mand was word or byte oriented.

                The address portion of any of the above commands

                may be followed by a comma and then by an expres-

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


                   =  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 ex-

                      pression as a symbolic address.  If the ex-

                      pression is relocatable, that symbol is

                      found whose value is nearest that of the

                      expression, and the symbol is typed, fol-

                      lowed 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 expres-

                      sion.  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 contents of the general regis-

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

                The only way to exit from db is the generate an

                end of file on the typewriter (EOT character).

FILES           --

SEE ALSO        as; core for format of core image.

DIAGNOSTICS     "File not found" if the first argument cannot be

                read; otherwise "?".

BUGS            Really, db should know about relocation bits,

                floating point operations, and PDP11/45 instruc-


OWNER           dmr