diff options
Diffstat (limited to 'doc/en/types.html')
| -rw-r--r-- | doc/en/types.html | 183 |
1 files changed, 183 insertions, 0 deletions
diff --git a/doc/en/types.html b/doc/en/types.html new file mode 100644 index 0000000..6f233a3 --- /dev/null +++ b/doc/en/types.html @@ -0,0 +1,183 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> +<html> +<head> + <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> + <meta name="Author" content="Johannes Sixt"> + <title>KDbg - User's Manual - Type Tables</title> +</head> +<body text="#000000" bgcolor="#FFFFFF"> +<p><a href="index.html">Contents</a></p> +<h1> +KDbg's Type Table</h1> +<p>KDbg can display a short description of structured types, so +that it is not necessary to expand the variable in the <a href="localvars.html">local +variables window</a> or <a href="watches.html">watched expressions window</a>. +The information which member variable is displayed is stored in <em>type +tables</em>. There is generally one type table per shared library.</p> + +<p>KDbg's default type tables are located under <tt>$prefix/share/apps/kdbg/types</tt>. +User defined type tables can be placed in <tt>${TDEHOME}/share/apps/kdbg/types</tt>, where +<tt>${TDEHOME}</tt> is <tt>~/.kde</tt> if it is not a defined environment variable. +The file names end with <tt>.kdbgtt</tt>. Example: The type table for <tt>libtqt.so</tt> +is named <tt>qt.kdbgtt</tt>. +User defined type tables override the type tables provided by the system.</p> +<p>A type table file obeys the regular KDE configuration file syntax. The +file has the following groups:</p> +<ul> +<li> +A group <tt>[Type Table]</tt> which lists the types and information how +the debugger can identify whether the program is linked against the library.</li> + +<li> +A group for each type which has information about how the value of such +a type is displayed by KDbg.</li> +</ul> +<p>In order to determine which type tables apply to the program being debugged +KDbg lists the shared libraries it is linked to. Then it matches the names +against the <tt>ShlibRE</tt> entries of all type tables. Those that match +are used. If a type appears in several type tables, it is unspecified which +one will be used.</p> +<p>KDbg's type recognition only works for libraries that are linked dynamically +to the program being debugged.</p> +<h2> +The <tt>[Type Table]</tt> group</h2> +<p>This group contains the following entries:</p> +<ul> +<li> +<tt>Types1</tt>, <tt>Types2</tt>, etc. These entries name the types, +separated by commas. +Each of the entries can list any number of types. The entries must be numbered +consecutively (KDbg stops reading at the first gap), although an entry may be +empty (i.e. contain no type at all). +Sometimes the order in which the names are listed is important +(see <tt>Alias</tt> types below).</li> + +<li> +<tt>ShlibRE</tt>. KDbg uses this entry to determine if the type table applies +to the program being debugged. For this purpose KDbg determines the shared +libraries to which the program is linked. If any of the libraries matches +this entry, the type table applies. The regular expression is a TQt-regular +expression (the metacharacters <tt>.*?[]^$\</tt> are recognized in the +usual way, but there is no possibility to group characters.)</li> + +<li> +<tt>LibDisplayName</tt>. This entry is used in lists where the available +type tables are listed to identify this type table. + +<br><font size=-1>This is not used currently.</font></li> + +<li> +<tt>EnableBuiltin</tt> lists extensions that must be enabled if this +library is used. Currently, two builtins are supported: +<ul> +<li> +<tt>TQString::Data</tt> is used to display unicode strings of TQt's <tt>TQString</tt> +class. See below.</li> +<li><tt>TQCharIsShort</tt> is used only in connection with <tt>TQString::Data</tt> +to specify that a unicode character is stored in an object of type <tt>short</tt>. +See <tt>qt3.kdbgtt</tt> for examples.</li></ul></li> +</ul> + +<p>In the case of regular types the names of types should follow the output of the +<tt>whatis</tt> gdb command less any <tt>const</tt>, <i>spaces</i>, or trailing +<tt>&</tt>. +If the type contains a a comma in its name, it must be escaped with a backslash. +But note that the comma should not be escaped in the type's group (which is described +in the next section). +</p> +<p>In the case of template types the name can be arbitrary because the type's group +will mention the template name and a type parameter list.</p> + +<h2> +The type's group</h2> +<p>There is one group for each type that is named exactly as the type. <font size=-1>At +the moment C++ template classes are not supported.</font> Each group contains +the following entries:</p> +<ul> +<li>An optional <tt>Template</tt> entry that specifies the exact template type +name as it is reported by gdb's <tt>whatis</tt> command. However, it is +possible to replace template parameter types at the top-most level by an +asterisk <tt>*</tt>, which acts as a wildcard: It matches <b>one</b> +template type argument that is reported by <tt>whatis</tt> (except that an +asterisk in the last position matches all remaining template type arguments). +</li> +<li> +<tt>Display</tt> determines how the value of the type is displayed by KDbg. +The string must contain 1 to 5 percent characters '<tt>%</tt>'. These are +replaced by the results of the expressions printed by the <tt>Expr</tt><i>x</i> +entries.</li> + +<li> +One or more of <tt>Expr1</tt>, <tt>Expr2</tt>, etc. Each of them must contain +one or more <tt>%s</tt> sequence, which will be replaced by the expression +whose value is investigated. The so constructed expression is submitted +to gdb, and the result substituted back for the corresponding percent character +in the <tt>Display</tt> string.</li> + +<li> +An optional <tt>FunctionGuard</tt><i>x</i> that is associated with the corresponding <tt>Expr</tt><i>x</i>. +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.) +<li> +<tt>Alias</tt> names an alias type. If this entry is present, the type +is treated like the specified type. That alias type must appear before +this type in the <tt>Types</tt><i>x</i> entries in the <tt>Type Table</tt>.</li> +</ul> +<p><font size=-1>Currently the number of expressions per type is limited to +5. This can easily be changed if it's too restrictive, but I recommend +not to go to that limit at all - it will slow down the debugging process.</font></p> +<p>KDbg recognizes a special extension that is used to display TQt 2.x's and TQt 3.x's +unicode strings: If an <tt>Expr</tt><i>x</i> is prepended with <tt>/TQString::Data</tt>, +it is assumed that the result of the expression is a pointer to a <tt>TQString::Data</tt>. +The value displayed is the unicode string that this instance of <tt>TQString::Data</tt> +represents (which can be <tt>TQString::null</tt> if it is TQt's well-defined +null string or <tt>(null)</tt> if the <tt>unicode</tt> member is the null +pointer). See <tt>qt2.kdbgtt</tt> for examples.</p> +<p>Tip: It is not necessary to define derived types if they ought to be +treated the same as the base class - KDbg can deduce derived types and +uses the type specification of the (leftmost) base class. You can use the +<tt>Alias</tt> +entry to quickly specify that a type should be treated like a non-leftmost +base class for a multiple-inheritance class.</p> +<h2> +An example</h2> +<p>The example shows how <tt>TQString</tt> and <tt>TQRect</tt> are defined +in <tt>qt3.kdbgtt</tt>. Furthermore, the template type <tt>TQValueVector</tt> +is defined. This example applies to TQt 3.x, which is located in shared library +whose name ends in <tt>libtqt-mt.so.3</tt>.</p> +<pre>[Type Table] +Types1=TQString,TQRect +Types2=TQValueVector +LibDisplayName=libtqt 3.x +ShlibRE=libtqt-mt\.so\.3$ +EnableBuiltin=TQString::Data,TQCharIsShort + +[TQString] +Display={ % } +Expr1=/TQString::Data (%s).d + +[TQValueVector] +Template=TQValueVector<*> +Display={ size=% shared=% capacity=% } +Expr1=($tmp=(%s).sh)->finish-$tmp->start +Expr2=(%s).sh->count +Expr3=($tmp=(%s).sh)->end-$tmp->start + +[TQRect] +Display={ tl=(%,%) br=(%,%) } +Expr1=(%s).x1 +Expr2=(%s).y1 +Expr3=(%s).x2 +Expr4=(%s).y2</pre> +<p>This example shows these features:</p> +<ul> +<li>The name of the template type, <tt>TQValueVector</tt> is irrelevant. +The exact type name is specified under the <tt>Template=</tt> entry. +It specifies a single wildcard so that it applies to all specializations. +</li> +<li>In order to evaluate the expression that was supplied in the <tt>%s</tt> +only once, the result is stored in a temporary gdb variable and reused later in +the same expression.</li> +<li>Note that it is safer to wrap the <tt>%s</tt> in parentheses.</li> +</ul> +</body> +</html> |