kdbg/doc/en/types.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <html>
   3 <head>
   4    <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
   5    <meta name="Author" content="Johannes Sixt">
   6    <title>KDbg - User's Manual - Type Tables</title>
   7 </head>
   8 <body text="#000000" bgcolor="#FFFFFF">
   9 <p><a href="index.html">Contents</a></p>
  10 <h1>
  11 KDbg's Type Table</h1>
  12 <p>KDbg can display the contents of single members of structured types, so
  13 that it is not necessary to expand the variable in the <a href="localvars.html">local
  14 variables window</a> or <a href="watches.html">watched expressions window</a>.
  15 The information which member variable is displayed is stored in <em>type
  16 tables</em>. There is generally one type table per shared library.</p>
  17 <p>KDbg's type tables are located under <tt>$prefix/share/apps/kdbg/types</tt>.
  18 The file names end with <tt>.kdbgtt</tt>. Example: The type table for <tt>libqt.so</tt>
  19 is named <tt>qt.kdbgtt</tt>.</p>
  20 <p>A type table file obeys the regular KDE configuration file syntax. The
  21 file has the following groups:</p>
  22 <ul>
  23 <li>
  24 A group <tt>[Type Table]</tt> which lists the types and information how
  25 the debugger can identify whether the program is linked against the library.</li>
  26
  27 <li>
  28 A group for each type which has information about how the value of such
  29 a type is displayed by KDbg.</li>
  30 </ul>
  31 <p>In order to determine which type tables apply to the program being debugged
  32 KDbg lists the shared libraries it is linked to. Then it matches the names
  33 against the <tt>ShlibRE</tt> entries of all type tables. Those that match
  34 are used. If a type appears in several type tables, it is unspecified which
  35 one will be used.</p>
  36 <p>KDbg's type recognition only works for libraries that are linked dynamically
  37 to the program being debugged.</p>
  38 <h2>
  39 The <tt>[Type Table]</tt> group</h2>
  40 <p>This group contains the following entries:</p>
  41 <ul>
  42 <li>
  43 <tt>Types1</tt>, <tt>Types2</tt>, etc. These entries name the types. Each
  44 of them is a comma-separated list of type names. Each of the entries can
  45 list any number of types. (The types names can be distributed to several
  46 lines just so that the lines don't get excessivly long.) No blank space
  47 is allowed in these lines. The entries must be numbered consecutively (KDbg
  48 stops reading at the first gap), although an entry may be empty (i.e. contain
  49 no type at all). Sometimes the order in which the names are listed is important
  50 (see <tt>Alias</tt> types below).</li>
  51
  52 <li>
  53 <tt>ShlibRE</tt>. KDbg uses this entry to determine if the type table applies
  54 to the program being debugged. For this purpose KDbg determines the shared
  55 libraries to which the program is linked. If any of the libraries matches
  56 this entry, the type table applies. The regular expression is a Qt-regular
  57 expression (the metacharacters <tt>.*?[]^$\</tt> are recognized in the
  58 usual way, but there is no possibility to group characters.)</li>
  59
  60 <li>
  61 <tt>LibDisplayName</tt>. This entry is used in lists where the available
  62 type tables are listed to identify this type table.
  63
  64 <br><font size=-1>This is not used currently.</font></li>
  65
  66 <li>
  67 <tt>EnableBuiltin</tt> lists extensions that must be enabled if this
  68 library is used. Currently, two builtins are supported:
  69 <ul>
  70 <li>
  71 <tt>QString::Data</tt> is used to display unicode strings of Qt's <tt>QString</tt>
  72 class. See below.</li>
  73 <li><tt>QCharIsShort</tt> is used only in connection with <tt>QString::Data</tt>
  74 to specify that a unicode character is stored in an object of type <tt>short</tt>.
  75 See <tt>qt3.kdbgtt</tt> for examples.</li></ul></li>
  76 </ul>
  77
  78 <h2>
  79 The type's group</h2>
  80 <p>There is one group for each type that is named exactly as the type. <font size=-1>At
  81 the moment C++ template classes are not supported.</font> Each group contains
  82 the following entries:</p>
  83 <ul>
  84 <li>
  85 <tt>Display</tt> determines how the value of the type is displayed by KDbg.
  86 The string must contain 1 to 5 percent characters '<tt>%</tt>'. These are
  87 replaced by the results of the expressions printed by the <tt>Expr</tt><i>x</i>
  88 entries.</li>
  89
  90 <li>
  91 One or more of <tt>Expr1</tt>, <tt>Expr2</tt>, etc. Each of them must contain
  92 <b>exactly
  93 one</b> <tt>%s</tt> sequence, which will be replaced by the expression
  94 whose value is investigate. The so constructed expression is submitted
  95 to gdb, and the result substituted back for the corresponding percent character
  96 in the <tt>Display</tt> string.</li>
  97
  98 <li>
  99 <tt>Alias</tt> names an alias type. If this entry is present, the type
 100 is treated like the specified type. That alias type must appear before
 101 this type in the <tt>Types</tt><i>x</i> entries in the <tt>Type Table</tt>.</li>
 102 </ul>
 103 <p><font size=-1>Currently the number of expressions per type is limited to
 104 5. This can easily be changed if it's too restrictive, but I recommend
 105 not to go to that limit at all - it will slow down the debugging process.</font></p>
 106 <p>KDbg recognizes a special extension that is used to display Qt 2.x's and Qt 3.x's
 107 unicode strings: If an <tt>Expr</tt><i>x</i> is prepended with <tt>/QString::Data</tt>,
 108 it is assumed that the result of the expression is a pointer to a <tt>QString::Data</tt>.
 109 The value displayed is the unicode string that this instance of <tt>QString::Data</tt>
 110 represents (which can be <tt>QString::null</tt> if it is Qt's well-defined
 111 null string or <tt>(null)</tt> if the <tt>unicode</tt> member is the null
 112 pointer). See <tt>qt2.kdbgtt</tt> for examples.</p>
 113 <p>Tip: It is not necessary to define derived types if they ought to be
 114 treated the same as the base class - KDbg can deduce derived types and
 115 uses the type specification of the (leftmost) base class. You can use the
 116 <tt>Alias</tt>
 117 entry to quickly specify that a type should be treated like a non-leftmost
 118 base class for a multiple-inheritance class.</p>
 119 <h2>
 120 An example</h2>
 121 <p>The example shows how <tt>QString</tt> and <tt>QObject</tt> are defined
 122 in <tt>qt.kdbgtt</tt>. Additionally, <tt>QTableView</tt> is defined as
 123 an alias of <tt>QObject</tt>. This example applies to Qt 1.x, which is
 124 located in shared library whose name ends in <tt>libqt.so.1</tt>.</p>
 125 <pre>[Type Table]
 126 Types1=QString
 127 Types2=QObject,QTableView
 128 LibDisplayName=libqt 1.x
 129 ShlibRE=libqt\.so\.1$
 130 [QString]
 131 Display={ % }
 132 Expr1=(%s).shd->data
 133 [QObject]
 134 Display={ name=% #chld=% }
 135 Expr1=(%s).objname
 136 Expr2=(%s).childObjects->numNodes
 137 [QTableView]
 138 Alias=QObject</pre>
 139 <p>Note that it is safer to wrap the <tt>%s</tt> in parentheses.</p>
 140 </body>
 141 </html>