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

     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.



     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.  A decimal number immediately  followed  by  `.'  is  an

         absolute quantity with the appropriate value.



      4.  An  octal  number  immediately  followed  by  r  is   a

         relocatable 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

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



      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

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  interpreted  as

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.



      /   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

         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.



      &   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

         advances  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 requests.  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 ^

requests is by one or two depending on whether the  last  command

was 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

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



The following command  may  be  used  to  patch  the  file  being

debugged.



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



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.



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, addresses in core images  do  not

correspond  with  the  addresses used by the program because in a

core image there is a 512-byte  header  containing  the  system's

per-process  data  for  the  dumped process, and also because the

stack is stored contiguously 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

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 512(10) bytes 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;

otherwise ``?''.



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.