Program Database Toolkit (PDT)

**********************************************************************

Program Database (PDB) Format

    Items                    ID      attribute
			   prefix     prefix
    HEADER
    FILES                    so          s
    ROUTINES	             ro          r
    TYPES (non-classes)      ty          y
    CLASSES                  cl          c
    TEMPLATES                te          t
    MACROS                   ma          m
    NAMESPACES               na          n

Prototype format for each item:
* Each line is of the form:  attribute value value...
* Attributes and values are separated by exactly one space (" ")
* Item description blocks are terminated by an empty line
* Values which are references to other items are done using IDs
* Values are never enclosed in ""
* Attributes with boolean value are only listed if true (value == T)
  i.e. absence means false
* String "[...]" after attribute means "0 or more" instances of this
  attribute line possible

**********************************************************************

HEADER Item

<PDB 1.0>

**********************************************************************

SOURCE FILE Item

so#[fileID]	<filename (absolute path)>
sinc [...]	<included fileID>		     # IDs of included files

**********************************************************************

ROUTINE Item

ro#[routineID]  <name of routine>
rloc		<fileID> <line> <column>	     # location
[
rclass		<classID>			     # parent class
racs		<pub|prot|priv>			     # access
  OR
rnspace		<namespaceID>			     # parent namespace
]
rsig		<typeID>                             # signature
rlink		<no|internal|C++|C>		     # linkage
rstore		<ext|stat|auto|NA|asm>		     # storage class
rstatic		<boolean>			     # is static function?
rkind		<ctor|dtor|conv|op>		     # special kind
rvirt		<no|virt|pure>                       # virtuality
rcrvo		<boolean>                            # is covariant return
						     # virtual override?
rinline		<boolean>			     # is inline?
rcgen		<boolean>                            # is compiler generated?
rexpl		<boolean>                            # is explicit ctor?
rtempl		<templateID or boolean>              # ID if template instance;
						     # boolean if specialized
rspecl		<boolean>                            # is specialized?
rcall [...]	<routineID> <no|virt> <fileID> <line> <column>
						     # callees
rpos		<start of return type> <last token before "{"> <"{"> <"}">

**********************************************************************

CLASS Item

cl#[classID] 	<name of class>
cloc		<fileID> <line> <column>	     # location
[
cclass		<classID>			     # parent class
cacs		<pub|prot|priv>			     # access
  OR
cnspace		<namespaceID>			     # parent namespace
]
ckind		<class|struct|union>		     # kind
ctempl		<templateID or boolean>              # ID if template instance;
						     # boolean if specialized
cspecl		<boolean>                            # is specialized?
cbase [...]	<virt|no> <NA|pub|prot|priv> <direct base classID> <fileID> <line> <column>
						     # direct base classes
cfrclass [...]  <classID> <fileID> <line> <column>   # friend classes
cfrfunc [...]	<routineID> <fileID> <line> <column> # friend functions
cfunc [...]	<member routineID> <fileID> <line> <column>
						     # member functions
cmem [...]	<name of non-function member>	     # other members
  cmloc		<fileID> <line> <column>	     # location    
  cmacs		<pub|prot|priv>			     # access
  cmkind	<type|statvar|var>		     # kind:  type or class,
						     # static or non-static
						     # variable
  cmtype	<typeID or classID>		     # type of member
  [
  if (cmkind == statvar):
  cmtempl	<templateID or boolean>		     # ID if template static
						     # data member;
						     # boolean if specialized
  cmspecl	<boolean>			     # is specialized?
  cmconst	<boolean>			     # was initializer
						     # specified at its
						     # declaration within the
						     # class definition?

  if (cmkind == var):
  cmisbit	<boolean>                            # is bit field?
  cmmut		<boolean>			     # is mutable?
  ]
cpos		<class token> <last token before "{"> <"{"> <"};">

**********************************************************************

TYPE Item

ty#[typeID]	<name of type>
yloc		<fileID> <line> <column>	     # location
[
yclass		<classID>			     # parent class
yacs		<pub|prot|priv>			     # access
  OR
ynspace		<namespaceID>			     # parent namespace
]
ykind		<err|void|int|float|ptr|ref|func     # kind
		|array|tref|ptrmem|tparam|NA
		|enum|wchar|bool>

[
if (ykind == int|enum|wchar|bool):
yikind		<char|schar|uchar|short|ushort	     # integer kind
		|int|uint|long|ulong
		|longlong|ulonglong>
ysigned		<boolean>			     # is explicitly signed?

if (ykind == enum):
yenum [...]	<name1> <value1>                     # name-value pairs

if (ykind == float):
yfkind		<float|dbl|longdbl>		     # float kind

if (ykind == ptr):
yptr		<typeID or classID>		     # type pointed to

if (ykind == ref):
yref		<typeID or classID>		     # type referred to

if (ykind == func):
yrett		<typeID or classID>                  # return type
yargt [...]	<typeID or classID> <boolean>	     # argument type;
						     # has default argument?
yellip          <boolean>			     # has ellipsis?
yqual		<const>				     # qualifier
yexcep [...]	<classID>			     # absence of attribute
						     # indicates any exception
						     # may be thrown; NULL
						     # indicates no exceptions
						     # will be thrown

if (ykind == array):
yelem		<typeID or classID>		     # type of array element
ynelem		<number of elements>		     # -1: variable length array;
						     # 0: [] incomplete-type case;
						     # else number of elements

if (ykind == tref):
ytref		<typeID or classID>		     # typedef type
yqual		<const|volatile|restrict>*	     # qualifiers

if (ykind == ptrmem):
ympclass  	<classID>			     # type of class to which
						     # member pointed to belongs
ymptype		<typeID or classID>		     # type of member pointed to
]

**********************************************************************

TEMPLATE Item

te#[templateID] <name of template>
tloc		<fileID> <line> <column>	     # location
[
tclass          <classID>			     # parent class
tacs            <pub|prot|priv>			     # access
  OR
tnspace		<namespaceID>			     # parent namespace
]
tkind		<none|class|func|memfunc	     # kind
		|statmem|memclass>
ttext		<string giving text of template>     # text of template
tpos		<template token> <">"> <start of template> <"}">

**********************************************************************

NAMESPACE Item

na#[namespaceID]	<name of namespace>
nloc		<fileID> <line> <column>	     # location
nnspace		<parent namespaceID>		     # parent namespace
nmem [...]	<typeID>|<routineID>|<classID>	     # IDs of members
		|<templateID>|<namespaceID>
nalias		<alias name>			     # alias of namespace
npos		<namespace token> <last token before "{"> <"{"> <"}">

**********************************************************************

MACRO Item

ma#[macroID] 	<name of macro>
mloc		<fileID> <line> <column>	     # location
mkind		<def|undef>			     # kind
mtext		<string giving text of macro>	     # text of macro

**********************************************************************

NOTES AND CAVEATS:

To eliminate unneeded entities, add the EDG option "--remove_unneeded_entities"
to the command line for cxxparse. 

ROUTINE rpos, CLASS cpos, TEMPLATE tpos, NAMESPACE npos:
* Positions have form <fileID> <line> <column>
* Position 1 corresponds to the first 3 values, position 2 to the
  next 3 values, etc.
* Location of the header is given by the first 2 positions, location
  of the body by the last 2 positions.
* A value of "NULL 0 0" indicates an unknown position.
* Tab characters are counted as a single column.

ROUTINE rcall:
* The values for rcall will be NULL 0 0, if the routine calling (e.g. some
  constructors) or being called (e.g. implicit conversions) is compiler
  generated.
* Some positions are not ideal (but the best that can be done):
  ctor/dtor calls associated with "new"/"delete", 
  dtor calls within dtors for derived classes,
  new/ctor calls associated with return statements,
  positions associated with macros.
* Destructor calls are often reported with the corresponding constructor
  calls; this is for exception handling.

ROUTINE rpos:
* For unused member functions of instantiated template classes, the
  header positions are known, but not the body positions.
* For unused constructors of instantiated template classes, position 2
  will not reflect the constructor initializers.
* For functions that are specializations of function templates, the header
  positions are not given in the IL.
* If "throw( ... )" is the last element in the header, position 2 will be
  the location of the 'w':  the IL does not give locations for the
  parentheses or the types listed within the parentheses.
* EDG has bug relating to constructor initializations that can cause
  the rpos positions to be incorrect.  Notified EDG 2/5/99; told them
  it wasn't critical.
* EDG (2.38 manual, but evidently also 2.39):
  "Putting a try/catch around the initializers and body of a constructor
  is not implemented."
  This refers to the following (from Stroustrup):
    function-definition:
      ...
      decl-specifier-seq(opt) declarator function-try-block
    function-try-block:
      try ctor-initializer(opt) function-body handler-seq

CLASS cpos:
* If position 2 is null, then the class is a typedef having the form:
    typedef struct { . . . };
* Position 3 cannot be determined for non-template classes and speciali-
  zations; it is not given in the IL.
* In cases where positions 3 and 4 are null -- i.e. the class corresponds
  to a template declaration rather than a definition -- position 2 will not
  reflect base classes, if there are any.  This is the best that
  can be done given the structure of the IL.

TEMPLATE tpos:
* Position 2 is unknown in IL.

NAMESPACE npos:
* The positions for a namespace pertain to the first encountered segment
  of a namespace.
* Position 1 is unknown in IL.
* Position 2 is known in IL only for named namespaces.
* Position 3 is known in IL only for unnamed namespaces.
* Position 4 is unknown in IL for namespace aliases.

IL Analyzer (bin/taucpdisp):
* See rpos above for EDG bug.
* Enums are reported in hex format; configuration should be changed.
  Note: from Changes 2.40 9/22/98
  Enum types larger than "int":
  In C++ (except in Microsoft mode) enum types are now permitted to be
  stored as integer types larger than "int".  The type selected is the
  smallest integer type greater than int that is large enough to contain
  the largest of the enumeration constants.
  (This has not been incorporated as of 6/18/99.)
* Cannot distinguish among multiple templates defined at the same location,
  as can happen when templates are defined within templates
  (see find_template_in_node_list()). (1/25/99)
* Need parameter names for templates (1st priority) and functions (2nd priority;
  see scope entry in memory region for function).
  (5/10/99)
* Add exits from routines (for profiling purposes for C and Fortran). (5/10/99)
* Lines which end with a location triple (file,line,col) have an extra
  unnecessary blank at the end of the line. (7/19/99)
* For memfunc, statmem, memclass templates, need pointer to the parent template
  class.  Add "ttempl <templateID>"?  (10/26/99)
* Routine calls using pointers to functions are not currently reported.
  The function signature can be determined without difficulty; what else can
  be determined is not known at this time.  See emails on "C++ function calls"
  from Kathie and Bernd, and ptrToFunc.c example. (1/20/00)
 
DUCTAPE application bin/pdbmerge:
* Namespace definitions spread over several files are not merged correctly.

DUCTAPE application bin/pdbtree:
* Class hierarchy is a DAG, not a tree, and therefore display is bad.

Possible enhancements:
* Last comment block before routines, classes, templates, ...
* Full symbol information
  * type
  * location where defined
  * locations where used
* Template instantiations?
* Pragmas?

**********************************************************************

CHANGE LOG:

************************************

Change date: July  3, 1998, klindlan

************************************

Change date: July  7, 1998, klindlan

ROUTINE:
rlink (deleted), rrett (deleted), rargt (deleted), roride (deleted
since not needed), rexpl, rcgen, exception specification (deleted)

CLASS:
cmem cfmut, cfrclass,cfrfunc

TYPE:
ykind == func: yrett (added), yargt (added), yellip (added),
ylink (added, attributes modified due to nature of code changes),
exception specification (added)
ykind == ptrmem: ytype -> ymptype

OTHER:
Deleted spaces after IDs.

************************************

Change date: July 13, 1998, klindlan

ROUTINE:
rlink (added)
rstore (deleted values reg, tdef)

CLASS:
cbase (implemented <virt|no> <pub|prot|priv|NA>, added cbloc to spec)

TYPE:
ykind (added values enum, wchar, bool)
ykind == int|enum|wchar|bool: ywchar (deleted), ybool (deleted)
ykind == func: ylink (deleted), yqual (added)

NAMESPACE:
Implemented except for attribute npos 
Caveat: templates are not listed due to edg bug

************************************

Change date: July 17, 1998, klindlan

HEADER:
Added.

CLASS:
cbase (fixed problem with <pub|prot|priv>).
Under cmem:
  cfloc -> cmloc, cfacs -> cmacs, cftype -> cmtype, cfisbut -> cmisbit, cfmut -> cmmut.
  cmkind (added, implemented), cmstore(added, implemented), cmtempl(added, implemented),
  cmspecl (added, implemented), cmconst(added, implemented).
  Note 3 types of non-function members.
  
TYPE:
ykind == enum: yenum (implemented), yaftype (deleted -- not intended for C++)
ykind == func: yexcep (added, implemented)
ykind == array: ynelem (implemented)
ykind == ptrmem: ympclass (changed name, implemented)

OTHER:
Modified names of types so that class name prefix is not printed.
Deleted NA from all instances of <pub|prot|priv|NA>.
v
************************************

Change date: July 21, 1998, klindlan

CLASS:
cmem cmkind: statvbl -> statvar, vbl -> var.
cmem cmkind == statvar: cmstore (eliminated).

OTHER:
class name prefix is restored everywhere.
template part of class names is restored.

************************************

Change date: July 23, 1998, klindlan

ROUTINE:
rtempl (converted attribute from boolean to <templateID or boolean>)

CLASS:
ctempl (converted attribute from boolean to <templateID or boolean>)
cmem (cmkind == statvar):
  cmstore (deleted)
  cmtempl (converted attribute from boolean to <templateID or boolean>)

TEMPLATE:
This section is now printed immediately following the SOURCE section, since
the list of templates must be constructed.

************************************

Change date:  September 30, 1998, klindlan

TYPE:
ykind: ref (added).
if (ykind == ref): yref (added).
The effect is to differentiate between "ykind ref" and "ykind ptr". 

************************************

Change date:  November 18, 1998, klindlan

ROUTINE:
rstatic (added)

Names are now compilable:  added space so that there would not be ">>"
with template instantiations.
Also, added comments to this document.

************************************

Change date:  December 2, 1998, klindlan

ROUTINE:
rstatic (reported for global static functions as well as member static
functions)

************************************

Change date:  February 19, 1999, klindlan

ROUTINE:
rpos (implemented)

CLASS:
cbloc (implemented)
cfrcloc (implemented)
cfrfloc (implemented)
cfloc (implemented)
cpos (implemented)

TYPE:
yenum (modified so that, on SUN4, enum values are now correct)

TEMPLATE:
tloc (modified so that it points to the name of the template)
tpos (implemented)

NAMESPACE:
npos (implemented)

NOTES AND CAVEATS:
Added this section.  Look here to determine limitations, especially for
rpos, cpos, tpos, and npos.

OTHER:
Improved algorithm for finding templates.

************************************

Change date: March 3, 1999, klindlan

ROUTINE:
rcall (not printed for this release)
rpos (if routine is compiler generated, rpos is not reported)

CLASS:
cbase & cbloc (merged, fileID dropped)
cfrclass & cfrcloc (merged, fileID dropped)
cfrfunc & cfrfloc (merged, fileID dropped)
cfunc & cfloc (merged, fileID dropped)

************************************

Change date: June 29, 1999, klindlan

ROUTINE:
rcgen (investigated: ductape "CGEN" messages pertain to macros)
rcall (reported again, ctors/dtors/new/delete reported, operators
reported (no change), no|virt added)

ROUTINE rcall, rpos,
CLASS cbase, cfrclass, cfrfunc, cfunc, cpos,
TEMPLATE tpos,
NAMESPACE npos:
locations now have form <fileID> <line> <column>

NOTES AND CAVEATS:
Various changes.

OTHER:
Reconfigured host environment (host_envir.h).  int.c files should no
longer be created.
Modified configure, bin/configure, and bin/cxxparse.proto to reflect
changes in ductape's files and handle egcs.
Upgraded to EDG v. 2.41.2 (from 2.39) and applied patch for IL
read/write problem.

************************************

Change date: July 8, 1999, sameer

Porting to SGI, Linux, Cray, Solaris, HP, IBM
For HP-UX fixed float_pt.c with __hpux so it recognizes 0.5F as 0.5.
Fixed configuration files so we can use -ARCH=IRIXN32|IRIXO32|IRIX64
Added getword and getcompdefines in bin to allow compiler options (-D...) to 
be recognized by invoking the compiler. Also, if the compiler doesn't work,
we can manually enter the include dir paths.
For Cray, disabled use of mmap (Cray specific options are in defines.h.CRAY).
For Cray, we need INTEGER_VALUE_REPR_IS_A_HOST_INTEGER to be 1
For SGI it is 1 (works with 0 but enums get 0x0001 instead of 1 in taucpdisp).
But for Solaris & HP & Linux & AIX it is 0.
For HP-UX, we compile src/host_envir.c using gcc and the rest of the files
using c89. Added CCHOST in Makefile.proto and src/Makefile for this.

************************************

Change date: July 21, 1999, klindlan

Added command-line option to taucpdisp: -t.  If -t is specified,
template text strings are not included in PDB files.

************************************

Change date: July 21, 1999, bmohr

Fixed pdbtree so it handles recursive function calls now.

************************************

Change date: December 14, 1999, klindlan

TYPE:
yargt (added <boolean> that specifies whether there is a default argument)

Modified internal configuration so that the default is to not remove
unneeded entities, but to make it possible via the EDG command-line
option "--remove_unneeded_entities".  Added comment to cxxparse.proto
on this option.

************************************

Change date: March 2, 2000, klindlan

Incorportated DUCTAPE repository in pdtoolkit repository, so that
the DUCTAPE library need not be included in releases.