3/15/72                                                    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, the

                symbol table is obtained from the file being de-

                bugged, or if not there from a.out.  If no appro-

                priate name list file can be found, db can still

                be used but some of its symbolic facilities be-

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



                   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 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 printed in decimal.

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

                   %  Exit.

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

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

                tions 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.  There-

                fore, 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 ap-

                pears 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 ad-

                dressed at apparent locations 160000-160777.

                If one wants to examine a file which has an asso-

                ciated 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 fea-

                ture is used most frequently in examining the

                memory file /dev/mem.

FILES           --

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

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

                read; otherwise "?".

BUGS            The "^" request always decrements "." by 2, even

                in byte mode.

OWNER           dmr