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 a short description 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
  18 <p>KDbg's default type tables are located under <tt>$prefix/share/apps/kdbg/types</tt>.
  19 User defined type tables can be placed in <tt>${KDEHOME}/share/apps/kdbg/types</tt>, where
  20 <tt>${KDEHOME}</tt> is <tt>~/.kde</tt> if it is not a defined environment variable.
  21 The file names end with <tt>.kdbgtt</tt>. Example: The type table for <tt>libqt.so</tt>
  22 is named <tt>qt.kdbgtt</tt>.
  23 User defined type tables override the type tables provided by the system.</p>
  24 <p>A type table file obeys the regular KDE configuration file syntax. The
  25 file has the following groups:</p>
  26 <ul>
  27 <li>
  28 A group <tt>[Type Table]</tt> which lists the types and information how
  29 the debugger can identify whether the program is linked against the library.</li>
  30
  31 <li>
  32 A group for each type which has information about how the value of such
  33 a type is displayed by KDbg.</li>
  34 </ul>
  35 <p>In order to determine which type tables apply to the program being debugged
  36 KDbg lists the shared libraries it is linked to. Then it matches the names
  37 against the <tt>ShlibRE</tt> entries of all type tables. Those that match
  38 are used. If a type appears in several type tables, it is unspecified which
  39 one will be used.</p>
  40 <p>KDbg's type recognition only works for libraries that are linked dynamically
  41 to the program being debugged.</p>
  42 <h2>
  43 The <tt>[Type Table]</tt> group</h2>
  44 <p>This group contains the following entries:</p>
  45 <ul>
  46 <li>
  47 <tt>Types1</tt>, <tt>Types2</tt>, etc. These entries name the types,
  48 separated by commas.
  49 Each of the entries can list any number of types. The entries must be numbered
  50 consecutively (KDbg stops reading at the first gap), although an entry may be
  51 empty (i.e. contain no type at all).
  52 Sometimes the order in which the names are listed is important
  53 (see <tt>Alias</tt> types below).</li>
  54
  55 <li>
  56 <tt>ShlibRE</tt>. KDbg uses this entry to determine if the type table applies
  57 to the program being debugged. For this purpose KDbg determines the shared
  58 libraries to which the program is linked. If any of the libraries matches
  59 this entry, the type table applies. The regular expression is a Qt-regular
  60 expression (the metacharacters <tt>.*?[]^$\</tt> are recognized in the
  61 usual way, but there is no possibility to group characters.)</li>
  62
  63 <li>
  64 <tt>LibDisplayName</tt>. This entry is used in lists where the available
  65 type tables are listed to identify this type table.
  66
  67 <br><font size=-1>This is not used currently.</font></li>
  68
  69 <li>
  70 <tt>EnableBuiltin</tt> lists extensions that must be enabled if this
  71 library is used. Currently, two builtins are supported:
  72 <ul>
  73 <li>
  74 <tt>QString::Data</tt> is used to display unicode strings of Qt's <tt>QString</tt>
  75 class. See below.</li>
  76 <li><tt>QCharIsShort</tt> is used only in connection with <tt>QString::Data</tt>
  77 to specify that a unicode character is stored in an object of type <tt>short</tt>.
  78 See <tt>qt3.kdbgtt</tt> for examples.</li></ul></li>
  79 </ul>
  80
  81 <p>In the case of regular types the names of types should follow the output of the
  82 <tt>whatis</tt> gdb command less any <tt>const</tt>, <i>spaces</i>, or trailing
  83 <tt>&</tt>.
  84 If the type contains a a comma in its name, it must be escaped with a backslash.
  85 But note that the comma should not be escaped in the type's group (which is described
  86 in the next section).
  87 </p>
  88 <p>In the case of template types the name can be arbitrary because the type's group
  89 will mention the template name and a type parameter list.</p>
  90
  91 <h2>
  92 The type's group</h2>
  93 <p>There is one group for each type that is named exactly as the type. <font size=-1>At
  94 the moment C++ template classes are not supported.</font> Each group contains
  95 the following entries:</p>
  96 <ul>
  97 <li>An optional <tt>Template</tt> entry that specifies the exact template type
  98 name as it is reported by gdb's <tt>whatis</tt> command. However, it is
  99 possible to replace template parameter types at the top-most level by an
 100 asterisk&nbsp;<tt>*</tt>, which acts as a wildcard: It matches <b>one</b>
 101 template type argument that is reported by <tt>whatis</tt> (except that an
 102 asterisk in the last position matches all remaining template type arguments).
 103 </li>
 104 <li>
 105 <tt>Display</tt> determines how the value of the type is displayed by KDbg.
 106 The string must contain 1 to 5 percent characters '<tt>%</tt>'. These are
 107 replaced by the results of the expressions printed by the <tt>Expr</tt><i>x</i>
 108 entries.</li>
 109
 110 <li>
 111 One or more of <tt>Expr1</tt>, <tt>Expr2</tt>, etc. Each of them must contain
 112 one or more <tt>%s</tt> sequence, which will be replaced by the expression
 113 whose value is investigated. The so constructed expression is submitted
 114 to gdb, and the result substituted back for the corresponding percent character
 115 in the <tt>Display</tt> string.</li>
 116
 117 <li>
 118 An optional <tt>FunctionGuard</tt><i>x</i> that is associated with the corresponding <tt>Expr</tt><i>x</i>.
 119 If the evaluation of the resulting gdb expression returns an error, the corresponding expression from <tt>Expr</tt><i>x</i> is not evaluated. (This is used to guard function calls.)
 120 <li>
 121 <tt>Alias</tt> names an alias type. If this entry is present, the type
 122 is treated like the specified type. That alias type must appear before
 123 this type in the <tt>Types</tt><i>x</i> entries in the <tt>Type Table</tt>.</li>
 124 </ul>
 125 <p><font size=-1>Currently the number of expressions per type is limited to
 126 5. This can easily be changed if it's too restrictive, but I recommend
 127 not to go to that limit at all - it will slow down the debugging process.</font></p>
 128 <p>KDbg recognizes a special extension that is used to display Qt 2.x's and Qt 3.x's
 129 unicode strings: If an <tt>Expr</tt><i>x</i> is prepended with <tt>/QString::Data</tt>,
 130 it is assumed that the result of the expression is a pointer to a <tt>QString::Data</tt>.
 131 The value displayed is the unicode string that this instance of <tt>QString::Data</tt>
 132 represents (which can be <tt>QString::null</tt> if it is Qt's well-defined
 133 null string or <tt>(null)</tt> if the <tt>unicode</tt> member is the null
 134 pointer). See <tt>qt2.kdbgtt</tt> for examples.</p>
 135 <p>Tip: It is not necessary to define derived types if they ought to be
 136 treated the same as the base class - KDbg can deduce derived types and
 137 uses the type specification of the (leftmost) base class. You can use the
 138 <tt>Alias</tt>
 139 entry to quickly specify that a type should be treated like a non-leftmost
 140 base class for a multiple-inheritance class.</p>
 141 <h2>
 142 An example</h2>
 143 <p>The example shows how <tt>QString</tt> and <tt>QRect</tt> are defined
 144 in <tt>qt3.kdbgtt</tt>. Furthermore, the template type <tt>QValueVector</tt>
 145 is defined. This example applies to Qt 3.x, which is located in shared library
 146 whose name ends in <tt>libqt-mt.so.3</tt>.</p>
 147 <pre>[Type Table]
 148 Types1=QString,QRect
 149 Types2=QValueVector
 150 LibDisplayName=libqt 3.x
 151 ShlibRE=libqt-mt\.so\.3$
 152 EnableBuiltin=QString::Data,QCharIsShort
 153
 154 [QString]
 155 Display={ % }
 156 Expr1=/QString::Data (%s).d
 157
 158 [QValueVector]
 159 Template=QValueVector<*>
 160 Display={ size=% shared=% capacity=% }
 161 Expr1=($tmp=(%s).sh)->finish-$tmp->start
 162 Expr2=(%s).sh->count
 163 Expr3=($tmp=(%s).sh)->end-$tmp->start
 164
 165 [QRect]
 166 Display={ tl=(%,%) br=(%,%) }
 167 Expr1=(%s).x1
 168 Expr2=(%s).y1
 169 Expr3=(%s).x2
 170 Expr4=(%s).y2</pre>
 171 <p>This example shows these features:</p>
 172 <ul>
 173 <li>The name of the template type, <tt>QValueVector</tt> is irrelevant.
 174 The exact type name is specified under the <tt>Template=</tt> entry.
 175 It specifies a single wildcard so that it applies to all specializations.
 176 </li>
 177 <li>In order to evaluate the expression that was supplied in the <tt>%s</tt>
 178 only once, the result is stored in a temporary gdb variable and reused later in
 179 the same expression.</li>
 180 <li>Note that it is safer to wrap the <tt>%s</tt> in parentheses.</li>
 181 </ul>
 182 </body>
 183 </html>