<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> <link href="style.css" rel="stylesheet" type="text/css"> <title>LLDB Data Formatters</title> </head> <body> <div class="www_title"> The <strong>LLDB</strong> Debugger </div> <div id="container"> <div id="content"> <!--#include virtual="sidebar.incl"--> <div id="middle"> <div class="post"> <h1 class="postheader">Variable display</h1> <div class="postcontent"> <p>LLDB was recently modified to allow users to define custom formatting options for the variables display.</p> <p>Usually, when you type <code>frame variable</code> or run some <code>expression</code> LLDB will automatically choose the way to display your results on a per-type basis, as in the following example:</p> <p> <code> <b>(lldb)</b> frame variable<br> (uint8_t) x = 'a'<br> (intptr_t) y = 124752287<br> </code> </p> <p>However, in certain cases, you may want to associate a different style to the display for certain datatypes. To do so, you need to give hints to the debugger as to how variables should be displayed.<br> A new <b>type</b> command has been introduced in LLDB which allows to do just that.<br> </p> <p>Using it you can change your visualization to look like this: </p> <p> <code> <b>(lldb)</b> frame variable<br> (uint8_t) x = chr='a' dec=65 hex=0x41<br> (intptr_t) y = 0x76f919f<br> </code> </p> <p>There are several features related to data visualization: <span style="font-style: italic;">formats</span>, <span style="font-style: italic;">summaries</span>, <span style="font-style: italic;">filters</span>, <span style="font-style: italic;">synthetic children</span>.</p> <p>To reflect this, the <b>type</b> command has four subcommands:<br> </p> <p><code>type format</code></p> <p><code>type summary</code></p> <p><code>type filter</code></p> <p><code>type synthetic</code></p> <p>These commands are meant to bind printing options to types. When variables are printed, LLDB will first check if custom printing options have been associated to a variable's type and, if so, use them instead of picking the default choices.<br> </p> <p>Each of the commands has four subcommands available:<br> </p> <p><code>add</code>: associates a new printing option to one or more types</p> <p><code>delete</code>: deletes an existing association</p> <p><code>list</code>: provides a listing of all associations</p> <p><code>clear</code>: deletes all associations</p> </div> </div> <div class="post"> <h1 class="postheader">type format</h1> <div class="postcontent"> <p>Type formats enable you to quickly override the default format for displaying primitive types (the usual basic C/C++/ObjC types: <code><font color="blue">int</font></code>, <code><font color="blue">float</font></code>, <code><font color="blue">char</font></code>, ...).</p> <p>If for some reason you want all <code>int</code> variables in your program to print out as hex, you can add a format to the <code>int</code> type.<br></p> <p>This is done by typing <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type format add --format hex int </td> <table> at the LLDB command line.</p> <p>The <code>--format</code> (which you can shorten to <code>-f</code>) option accepts a <a href="#formatstable">format name</a>. Then, you provide one or more types to which you want the new format applied.</p> <p>A frequent scenario is that your program has a <code>typedef</code> for a numeric type that you know represents something that must be printed in a certain way. Again, you can add a format just to that typedef by using <code>type format add</code> with the name alias.</p> <p>But things can quickly get hierarchical. Let's say you have a situation like the following:</p> <p><code><font color="blue">typedef int</font> A;<br> <font color="blue">typedef</font> A B;<br> <font color="blue">typedef</font> B C;<br> <font color="blue">typedef</font> C D;<br> </code></p> <p>and you want to show all <code>A</code>'s as hex, all <code>C'</code>s as byte arrays and leave the defaults untouched for other types (albeit its contrived look, the example is far from unrealistic in large software systems).</p> <p>If you simply type <br> <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type format add -f hex A<br> <b>(lldb)</b> type format add -f uint8_t[] C </td> <table> <br> values of type <code>B</code> will be shown as hex and values of type <code>D</code> as byte arrays, as in:</p> <p> <code> <b>(lldb)</b> frame variable -T<br/> (A) a = 0x00000001<br/> (B) b = 0x00000002<br/> (C) c = {0x03 0x00 0x00 0x00}<br/> (D) d = {0x04 0x00 0x00 0x00}<br/> </code> </p> <p>This is because by default LLDB <i>cascades</i> formats through typedef chains. In order to avoid that you can use the option <code>-C no</code> to prevent cascading, thus making the two commands required to achieve your goal:<br> <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type format add -C no -f hex A<br> <b>(lldb)</b> type format add -C no -f uint8_t[] C </td> <table> <p>which provides the desired output:</p> <p> <code> <b>(lldb)</b> frame variable -T<br/> (A) a = 0x00000001<br/> (B) b = 2<br/> (C) c = {0x03 0x00 0x00 0x00}<br/> (D) d = 4<br/> </code> </p> <p>Two additional options that you will want to look at are <code>--skip-pointers</code> (<code>-p</code>) and <code>--skip-references</code> (<code>-r</code>). These two options prevent LLDB from applying a format for type <code>T</code> to values of type <code>T*</code> and <code>T&</code> respectively.</p> <p> <code> <b>(lldb)</b> type format add -f float32[] int<br> <b>(lldb)</b> frame variable pointer *pointer -T<br> (int *) pointer = {1.46991e-39 1.4013e-45}<br> (int) *pointer = {1.53302e-42}<br> <b>(lldb)</b> type format add -f float32[] int -p<br> <b>(lldb)</b> frame variable pointer *pointer -T<br> (int *) pointer = 0x0000000100100180<br> (int) *pointer = {1.53302e-42}<br> </code> </p> <p>While they can be applied to pointers and references, formats will make no attempt to dereference the pointer and extract the value before applying the format, which means you are effectively formatting the address stored in the pointer rather than the pointee value. For this reason, you may want to use the <code>-p</code> option when defining formats.</p> <p>If you need to delete a custom format simply type <code>type format delete</code> followed by the name of the type to which the format applies.Even if you defined the same format for multiple types on the same command, <code>type format delete</code> will only remove the format for the type name passed as argument.<br> </p> <p> To delete ALL formats, use <code>type format clear</code>. To see all the formats defined, use <code>type format list</code>.</p> <p>If all you need to do, however, is display one variable in a custom format, while leaving the others of the same type untouched, you can simply type:<br> <br> <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> frame variable counter -f hex </td> <table> <p>This has the effect of displaying the value of <code>counter</code> as an hexadecimal number, and will keep showing it this way until you either pick a different format or till you let your program run again.</p> <p>Finally, this is a list of formatting options available out of which you can pick:</p><a name="formatstable"></a> <table border="1"> <tbody> <tr valign="top"> <td width="23%"><b>Format name</b></td> <td><b>Abbreviation</b></td> <td><b>Description</b></td> </tr> <tr valign="top"> <td><b>default</b></td> <td><br> </td> <td>the default LLDB algorithm is used to pick a format</td> </tr> <tr valign="top"> <td><b>boolean</b></td> <td>B</td> <td>show this as a true/false boolean, using the customary rule that 0 is false and everything else is true</td> </tr> <tr valign="top"> <td><b>binary</b></td> <td>b</td> <td>show this as a sequence of bits</td> </tr> <tr valign="top"> <td><b>bytes</b></td> <td>y</td> <td>show the bytes one after the other<br> e.g. <code>(int) s.x = 07 00 00 00</code></td> </tr> <tr valign="top"> <td><b>bytes with ASCII</b></td> <td>Y</td> <td>show the bytes, but try to display them as ASCII characters as well<br> e.g. <code>(int *) c.sp.x = 50 f8 bf 5f ff 7f 00 00 P.._....</code></td> </tr> <tr valign="top"> <td><b>character</b></td> <td>c</td> <td>show the bytes as ASCII characters<br> e.g. <code>(int *) c.sp.x = P\xf8\xbf_\xff\x7f\0\0</code></td> </tr> <tr valign="top"> <td><b>printable character</b></td> <td>C</td> <td>show the bytes as printable ASCII characters<br> e.g. <code>(int *) c.sp.x = P.._....</code></td> </tr> <tr valign="top"> <td><b>complex float</b></td> <td>F</td> <td>interpret this value as the real and imaginary part of a complex floating-point number<br> e.g. <code>(int *) c.sp.x = 2.76658e+19 + 4.59163e-41i</code></td> </tr> <tr valign="top"> <td><b>c-string</b></td> <td>s</td> <td>show this as a 0-terminated C string</td> </tr> <tr valign="top"> <td><b>decimal</b></td> <td>i</td> <td>show this as a signed integer number (this does not perform a cast, it simply shows the bytes as an integer with sign)</td> </tr> <tr valign="top"> <td><b>enumeration</b></td> <td>E</td> <td>show this as an enumeration, printing the value's name if available or the integer value otherwise<br> e.g. <code>(enum enumType) val_type = eValue2</code></td> </tr> <tr valign="top"> <td><b>hex</b></td> <td>x</td> <td>show this as in hexadecimal notation (this does not perform a cast, it simply shows the bytes as hex)</td> </tr> <tr valign="top"> <td><b>float</b></td> <td>f</td> <td>show this as a floating-point number (this does not perform a cast, it simply interprets the bytes as an IEEE754 floating-point value)</td> </tr> <tr valign="top"> <td><b>octal</b></td> <td>o</td> <td>show this in octal notation</td> </tr> <tr valign="top"> <td><b>OSType</b></td> <td>O</td> <td>show this as a MacOS OSType<br> e.g. <code>(float) x = '\n\x1f\xd7\n'</code></td> </tr> <tr valign="top"> <td><b>unicode16</b></td> <td>U</td> <td>show this as UTF-16 characters<br> e.g. <code>(float) x = 0xd70a 0x411f</code></td> </tr> <tr valign="top"> <td><b>unicode32</b></td> <td><br> </td> <td>show this as UTF-32 characters<br> e.g. <code>(float) x = 0x411fd70a</code></td> </tr> <tr valign="top"> <td><b>unsigned decimal</b></td> <td>u</td> <td>show this as an unsigned integer number (this does not perform a cast, it simply shows the bytes as unsigned integer)</td> </tr> <tr valign="top"> <td><b>pointer</b></td> <td>p</td> <td>show this as a native pointer (unless this is really a pointer, the resulting address will probably be invalid)</td> </tr> <tr valign="top"> <td><b>char[]</b></td> <td><br> </td> <td>show this as an array of characters<br> e.g. <code>(char) *c.sp.z = {X}</code></td> </tr> <tr valign="top"> <td><b>int8_t[], uint8_t[]<br> int16_t[], uint16_t[]<br> int32_t[], uint32_t[]<br> int64_t[], uint64_t[]<br> uint128_t[]</b></td> <td><br> </td> <td>show this as an array of the corresponding integer type<br> e.g.<br> <code>(int) x = {1 0 0 0}</code> (with uint8_t[])<br> <code>(int) y = {0x00000001}</code> (with uint32_t[])</td> </tr> <tr valign="top"> <td><b>float32[], float64[]</b></td> <td><br> </td> <td>show this as an array of the corresponding floating-point type<br> e.g. <code>(int *) pointer = {1.46991e-39 1.4013e-45}</code></td> </tr> <tr valign="top"> <td><b>complex integer</b></td> <td>I</td> <td>interpret this value as the real and imaginary part of a complex integer number<br> e.g. <code>(int *) pointer = 1048960 + 1i</code></td> </tr> <tr valign="top"> <td><b>character array</b></td> <td>a</td> <td>show this as a character array<br> e.g. <code>(int *) pointer = \x80\x01\x10\0\x01\0\0\0</code></td> </tr> </tbody> </table> </div> </div> <div class="post"> <h1 class="postheader">type summary</h1> <div class="postcontent"> <p>Type formats work by showing a different kind of display for the value of a variable. However, they only work for basic types. When you want to display a class or struct in a custom format, you cannot do that using formats.</p> <p>A different feature, type summaries, works by extracting information from classes, structures, ... (<i>aggregate types</i>) and arranging it in a user-defined format, as in the following example:</p> <p> <i>before adding a summary...</i><br> <code> <b>(lldb)</b> frame variable -T one<br> (i_am_cool) one = {<br> (int) x = 3<br> (float) y = 3.14159<br> (char) z = 'E'<br> }<br> </code> <br> <i>after adding a summary...</i><br> <code> <b>(lldb)</b> frame variable one<br> (i_am_cool) one = int = 3, float = 3.14159, char = 69<br> </code> </p> <p>There are two ways to use type summaries: the first one is to bind a <i> summary string</i> to the type; the second is to write a Python script that returns the string to be used as summary. Both options are enabled by the <code>type summary add</code> command.</p> <p>The command to obtain the output shown in the example is:</p> <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add --summary-string "int = ${var.x}, float = ${var.y}, char = ${var.z%u}" i_am_cool </td> <table> <p>Initially, we will focus on summary strings, and then describe the Python binding mechanism.</p> </div> </div> <div class="post"> <h1 class="postheader">Summary Strings</h1> <div class="postcontent"> <p>Summary strings are written using a simple control language, exemplified by the snippet above. A summary string contains a sequence of tokens that are processed by LLDB to generate the summary.</p> <p>Summary strings can contain plain text, control characters and special variables that have access to information about the current object and the overall program state.</p> <p>Plain text is any sequence of characters that doesn't contain a <code><b>'{'</b></code>, <code><b>'}'</b></code>, <code><b>'$'</b></code>, or <code><b>'\'</b></code> character, which are the syntax control characters.</p> <p>The special variables are found in between a <code><b>"${"</b></code> prefix, and end with a <code><b>"}"</b></code> suffix. Variables can be a simple name or they can refer to complex objects that have subitems themselves. In other words, a variable looks like <code>"<b>${object}</b>"</code> or <code>"<b>${object.child.otherchild}</b>"</code>. A variable can also be prefixed or suffixed with other symbols meant to change the way its value is handled. An example is <code>"<b>${*var.int_pointer[0-3]}</b>".</code></p> <p>Basically, the syntax is the same one described <a href="formats.html">Frame and Thread Formatting</a> are accepted. Beyond what's described there, additional symbols have become available in the syntax for summary strings. The main of them is <code>${var</code>, which is used refer to the variable that a summary is being created for.</p> <p>The simplest thing you can do is grab a member variable of a class or structure by typing its <i>expression path</i>. In the previous example, the expression path for the field <code>float y</code> is simply <code>.y</code>. Thus, to ask the summary string to display <code>y</code> you would type <code>${var.y}</code>.</p> <p>If you have code like the following: <br> <code> <font color="blue">struct</font> A {<br> <font color="blue">int</font> x;<br> <font color="blue">int</font> y;<br> };<br> <font color="blue">struct</font> B {<br> A x;<br> A y;<br> <font color="blue">int</font> *z;<br> };<br> </code> the expression path for the <code>y</code> member of the <code>x</code> member of an object of type <code>B</code> would be <code>.x.y</code> and you would type <code>${var.x.y}</code> to display it in a summary string for type <code>B</code>. </p> <p>By default, a summary defined for type <code>T</code>, also works for types <code>T*</code> and <code>T&</code> (you can disable this behavior if desired). For this reason, expression paths do not differentiate between <code>.</code> and <code>-></code>, and the above expression path <code>.x.y</code> would be just as good if you were displaying a <code>B*</code>, or even if the actual definition of <code>B</code> were: <code><br> <font color="blue">struct</font> B {<br> A *x;<br> A y;<br> <font color="blue">int</font> *z;<br> };<br> </code> </p> <p>This is unlike the behavior of <code>frame variable</code> which, on the contrary, will enforce the distinction. As hinted above, the rationale for this choice is that waiving this distinction enables you to write a summary string once for type <code>T</code> and use it for both <code>T</code> and <code>T*</code> instances. As a summary string is mostly about extracting nested members' information, a pointer to an object is just as good as the object itself for the purpose.</p> <p>If you need to access the value of the integer pointed to by <code>B::z</code>, you cannot simply say <code>${var.z}</code> because that symbol refers to the pointer <code>z</code>. In order to dereference it and get the pointed value, you should say <code>${*var.z}</code>. The <code>${*var</code> tells LLDB to get the object that the expression paths leads to, and then dereference it. In this example is it equivalent to <code>*(bObject.z)</code> in C/C++ syntax. Because <code>.</code> and <code>-></code> operators can both be used, there is no need to have dereferences in the middle of an expression path (e.g. you do not need to type <code>${*(var.x).x})</code> to read <code>A::x</code> as contained in <code>*(B::x)</code>. To achieve that effect you can simply write <code>${var.x->x}</code>, or even <code>${var.x.x}</code>. The <code>*</code> operator only binds to the result of the whole expression path, rather than piecewise, and there is no way to use parentheses to change that behavior.</p> <p>Of course, a summary string can contain more than one <code>${var</code> specifier, and can use <code>${var</code> and <code>${*var</code> specifiers together.</p> </div> </div> <div class="post"> <h1 class="postheader">Formatting summary elements</h1> <div class="postcontent"> <p>An expression path can include formatting codes. Much like the type formats discussed previously, you can also customize the way variables are displayed in summary strings, regardless of the format they have applied to their types. To do that, you can use <code>%<i>format</i></code> inside an expression path, as in <code>${var.x->x%u}</code>, which would display the value of <code>x</code> as an unsigned integer. <p>You can also use some other special format markers, not available for type formatters, but which carry a special meaning when used in this context:</p> <table border="1"> <tbody> <tr valign="top"> <td width="23%"><b>Symbol</b></td> <td><b>Description</b></td> </tr> <tr valign="top"> <td><b>%S</b></td> <td>Use this object's summary (the default for aggregate types)</td> </tr> <tr valign="top"> <td><b>%V</b></td> <td>Use this object's value (the default for non-aggregate types)</td> </tr> <tr valign="top"> <td><b>%@</b></td> <td>Use a language-runtime specific description (for C++ this does nothing, for Objective-C it calls the NSPrintForDebugger API)</td> </tr> <tr valign="top"> <td><b>%L</b></td> <td>Use this object's location (memory address, register name, ...)</td> </tr> <tr valign="top"> <td><b>%#</b></td> <td>Use the count of the children of this object</td> </tr> <tr valign="top"> <td><b>%T</b></td> <td>Use this object's datatype name</td> </tr> </tbody> </table> <p>Option <code>--inline-children</code> (<code>-c</code>) to <code>type summary add</code> tells LLDB not to look for a summary string, but instead to just print a listing of all the object's children on one line.</p> <p> As an example, given a type <code>pair</code>: <code> <br> <b>(lldb)</b> frame variable --show-types a_pair<br> (pair) a_pair = {<br> (int) first = 1;<br/> (int) second = 2;<br/> }<br> </code><br> If one types the following commands: <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add --inline-children pair<br> </td> <table> the output becomes: <br><code> <b>(lldb)</b> frame variable a_pair<br> (pair) a_pair = (first=1, second=2)<br> </code> </p> Of course, one can obtain the same effect by typing <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add pair --summary-string "(first=${var.first}, second=${var.second})"<br> </td> <table> While the final result is the same, using <code>--inline-children</code> can often save time. </div> </div> <div class="post"> <h1 class="postheader">Bitfields and array syntax</h1> <div class="postcontent"> <p>Sometimes, a basic type's value actually represents several different values packed together in a bitfield.<br/> With the classical view, there is no way to look at them. Hexadecimal display can help, but if the bits actually span nibble boundaries, the help is limited.<br/> Binary view would show it all without ambiguity, but is often too detailed and hard to read for real-life scenarios. <p> To cope with the issue, LLDB supports native bitfield formatting in summary strings. If your expression paths leads to a so-called <i>scalar type</i> (the usual int, float, char, double, short, long, long long, double, long double and unsigned variants), you can ask LLDB to only grab some bits out of the value and display them in any format you like. If you only need one bit you can use the <code>[</code><i>n</i><code>]</code>, just like indexing an array. To extract multiple bits, you can use a slice-like syntax: <code>[</code><i>n</i>-<i>m</i><code>]</code>, e.g. <br><p> <code> <b>(lldb)</b> frame variable float_point<br> (float) float_point = -3.14159<br> </code> <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add --summary-string "Sign: ${var[31]%B} Exponent: ${var[30-23]%x} Mantissa: ${var[0-22]%u}" float </td> </table><br></code> <code> <b>(lldb)</b> frame variable float_point<br> (float) float_point = -3.14159 Sign: true Exponent: 0x00000080 Mantissa: 4788184<br> </code> In this example, LLDB shows the internal representation of a <code>float</code> variable by extracting bitfields out of a float object.</p> <p> When typing a range, the extremes <i>n</i> and <i>m</i> are always included, and the order of the indices is irrelevant. </p> <p>LLDB also allows to use a similar syntax to display array members inside a summary string. For instance, you may want to display all arrays of a given type using a more compact notation than the default, and then just delve into individual array members that prove interesting to your debugging task. You can tell LLDB to format arrays in special ways, possibly independent of the way the array members' datatype is formatted. <br> e.g. <br> <code> <b>(lldb)</b> frame variable sarray<br> (Simple [3]) sarray = {<br> [0] = {<br> x = 1<br> y = 2<br> z = '\x03'<br> }<br> [1] = {<br> x = 4<br> y = 5<br> z = '\x06'<br> }<br> [2] = {<br> x = 7<br> y = 8<br> z = '\t'<br> }<br> }<br></code> <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add --summary-string "${var[].x}" "Simple [3]" </td> <table><br> <code> <b>(lldb)</b> frame variable sarray<br> (Simple [3]) sarray = [1,4,7]<br></code></p> <p>The <code>[]</code> symbol amounts to: <i>if <code>var</code> is an array and I knows its size, apply this summary string to every element of the array</i>. Here, we are asking LLDB to display <code>.x</code> for every element of the array, and in fact this is what happens. If you find some of those integers anomalous, you can then inspect that one item in greater detail, without the array format getting in the way: <br> <code> <b>(lldb)</b> frame variable sarray[1]<br> (Simple) sarray[1] = {<br> x = 4<br> y = 5<br> z = '\x06'<br> }<br> </code> </p> <p>You can also ask LLDB to only print a subset of the array range by using the same syntax used to extract bit for bitfields: <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add --summary-string "${var[1-2].x}" "Simple [3]" </td> <table><br> <code> <b>(lldb)</b> frame variable sarray<br> (Simple [3]) sarray = [4,7]<br></code></p> <p>If you are dealing with a pointer that you know is an array, you can use this syntax to display the elements contained in the pointed array instead of just the pointer value. However, because pointers have no notion of their size, the empty brackets <code>[]</code> operator does not work, and you must explicitly provide higher and lower bounds.</p> <p>In general, LLDB needs the square brackets operator <code>[]</code> in order to handle arrays and pointers correctly, and for pointers it also needs a range. However, a few special cases are defined to make your life easier: <ul> <li>you can print a 0-terminated string (<i>C-string</i>) using the %s format, omitting square brackets, as in: <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add --summary-string "${var%s}" "char *" </td> <table> <p> This syntax works for <code>char*</code> as well as for <code>char[]</code> because LLDB can rely on the final <code>\0</code> terminator to know when the string has ended.</p> LLDB has default summary strings for <code>char*</code> and <code>char[]</code> that use this special case. On debugger startup, the following are defined automatically: <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add --summary-string "${var%s}" "char *"<br/> <b>(lldb)</b> type summary add --summary-string "${var%s}" -x "char \[[0-9]+]"<br/> </td> <table> </li> </ul> <ul> <li>any of the array formats (<code>int8_t[]</code>, <code>float32{}</code>, ...), and the <code>y</code>, <code>Y</code> and <code>a</code> formats work to print an array of a non-aggregate type, even if square brackets are omitted. <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add --summary-string "${var%int32_t[]}" "int [10]" </td> <table> </ul> This feature, however, is not enabled for pointers because there is no way for LLDB to detect the end of the pointed data. <br> This also does not work for other formats (e.g. <code>boolean</code>), and you must specify the square brackets operator to get the expected output. </p> </div> </div> <div class="post"> <h1 class="postheader">Python scripting</h1> <div class="postcontent"> <p>Most of the times, summary strings prove good enough for the job of summarizing the contents of a variable. However, as soon as you need to do more than picking some values and rearranging them for display, summary strings stop being an effective tool. This is because summary strings lack the power to actually perform some computation on the value of variables.</p> <p>To solve this issue, you can bind some Python scripting code as a summary for your datatype, and that script has the ability to both extract children variables as the summary strings do and to perform active computation on the extracted values. As a small example, let's say we have a Rectangle class:</p> <code> <font color="blue">class</font> Rectangle<br/> {<br/> <font color="blue">private</font>:<br/> <font color="blue">int</font> height;<br/> <font color="blue">int</font> width;<br/> <font color="blue">public</font>:<br/> Rectangle() : height(3), width(5) {}<br/> Rectangle(<font color="blue">int</font> H) : height(H), width(H*2-1) {}<br/> Rectangle(<font color="blue">int</font> H, <font color="blue">int</font> W) : height(H), width(W) {}<br/> <font color="blue">int</font> GetHeight() { return height; }<br/> <font color="blue">int</font> GetWidth() { return width; }<br/> };<br/> </code> <p>Summary strings are effective to reduce the screen real estate used by the default viewing mode, but are not effective if we want to display the area and perimeter of <code>Rectangle</code> objects</p> <p>To obtain this, we can simply attach a small Python script to the <code>Rectangle</code> class, as shown in this example:</p> <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add -P Rectangle<br/> Enter your Python command(s). Type 'DONE' to end.<br/> def function (valobj,dict):<br/> height_val = valobj.GetChildMemberWithName('height')<br/> width_val = valobj.GetChildMemberWithName('width')<br/> height = height_val.GetValueAsUnsigned(0)<br/> width = width_val.GetValueAsUnsigned(0)<br/> area = height*width<br/> perimeter = 2*(height + width)<br/> return 'Area: ' + str(area) + ', Perimeter: ' + str(perimeter)<br/> DONE<br/> <b>(lldb)</b> frame variable<br/> (Rectangle) r1 = Area: 20, Perimeter: 18<br/> (Rectangle) r2 = Area: 72, Perimeter: 36<br/> (Rectangle) r3 = Area: 16, Perimeter: 16<br/> </td> </table> <p>In order to write effective summary scripts, you need to know the LLDB public API, which is the way Python code can access the LLDB object model. For further details on the API you should look at <a href="scripting.html">this page</a>, or at the LLDB <a href="docs.html">doxygen documentation</a> when it becomes available.</p> <p>As a brief introduction, your script is encapsulated into a function that is passed two parameters: <code>valobj</code> and <code>dict</code>.</p> <p><code>dict</code> is an internal support parameter used by LLDB and you should not use it.<br/><code>valobj</code> is the object encapsulating the actual variable being displayed, and its type is <a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/API/SBValue.h">SBValue</a>. Out of the many possible operations on an SBValue, the basic one is retrieve the children objects it contains (essentially, the fields of the object wrapped by it), by calling <code>GetChildMemberWithName()</code>, passing it the child's name as a string.<br/> If the variable has a value, you can ask for it, and return it as a string using <code>GetValue()</code>, or as a signed/unsigned number using <code>GetValueAsSigned()</code>, <code>GetValueAsUnsigned()</code>. <p>If you need to delve into several levels of hierarchy, as you can do with summary strings, you can use the method <code>GetValueForExpressionPath()</code>, passing it an expression path just like those you could use for summary strings (one of the differences is that dereferencing a pointer does not occur by prefixing the path with a <code>*</code>, but by calling the <code>Dereference()</code> method on the returned SBValue). If you need to access array slices, you cannot do that (yet) via this method call, and you must use <code>GetChildAtIndex()</code> querying it for the array items one by one. Also, handling custom formats is something you have to deal with on your own. <p>Other than interactively typing a Python script there are two other ways for you to input a Python script as a summary: <ul> <li> using the --python-script option to <code>type summary add </code> and typing the script code as an option argument; as in: </ul> <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add --python-script "height = int(valobj.GetChildMemberWithName('height').GetValue());width = int(valobj.GetChildMemberWithName('width').GetValue()); return 'Area: ' + str(height*width)" Rectangle<br/> </td> </table> <ul> <li> using the <code>--python-function</code> (<code>-F</code>) option to <code>type summary add </code> and giving the name of a Python function with the correct prototype. Most probably, you will define (or have already defined) the function in the interactive interpreter, or somehow loaded it from a file, using the <code>script import</code> command. LLDB will not make any attempt at determining whether the function is defined and syntactically correct, until you try to call it. Any errors will be shown at that stage, as if you were executing your function inside the Python interactive interpreter itself. </ul> </p> </div> </div> <div class="post"> <h1 class="postheader">Regular expression typenames</h1> <div class="postcontent"> <p>As you noticed, in order to associate the custom summary string to the array types, one must give the array size as part of the typename. This can long become tiresome when using arrays of different sizes, <code>Simple [3]</code>, <code>Simple [9]</code>, <code>Simple [12]</code>, ...</p> <p>If you use the <code>-x</code> option, type names are treated as regular expressions instead of type names. This would let you rephrase the above example for arrays of type <code>Simple [3]</code> as: <br> <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add --summary-string "${var[].x}" -x "Simple \[[0-9]+\]" </td> <table> <code> <b>(lldb)</b> frame variable sarray<br> (Simple [3]) sarray = [1,4,7]<br> </code> The above scenario works for <code>Simple [3]</code> as well as for any other array of <code>Simple</code> objects. </p> <p>While this feature is mostly useful for arrays, you could also use regular expressions to catch other type sets grouped by name. However, as regular expression matching is slower than normal name matching, LLDB will first try to match by name in any way it can, and only when this fails, will it resort to regular expression matching. Thus, if your type has a base class with a cascading summary, this will be preferred over any regular expression match for your type itself.</p> <p>One of the ways LLDB uses this feature internally, is to match the names of STL container classes, regardless of the template arguments provided (e.g. <code>std::vector<T></code> for any type argument <code>T</code>). The regular expressions used for this are: </p> <ul> <li><code>^(std::)?vector<.+>$</code> for <code>std::vector<T></code></li> <li><code>^(std::)?list<.+>$</code> for <code>std::list<T></code></li> <li><code>^(std::)?map<.+> >$</code> for <code>std::map<K,V></code></li> </ul> As you can see, the actual template arguments are ignored by the regular expression. <p>The regular expression language used by LLDB is the <a href="http://en.wikipedia.org/wiki/Regular_expression#POSIX_Extended_Regular_Expressions">POSIX extended language</a>, as defined by the <a href="http://pubs.opengroup.org/onlinepubs/7908799/xsh/regex.h.html">Single UNIX Specification</a>, of which Mac OS X is a compliant implementation. </div> </div> <div class="post"> <h1 class="postheader">Named summaries</h1> <div class="postcontent"> <p>For a given type, there may be different meaningful summary representations. However, currently, only one summary can be associated to a type at each moment. If you need to temporarily override the association for a variable, without changing the summary string for to its type, you can use named summaries.</p> <p>Named summaries work by attaching a name to a summary when creating it. Then, when there is a need to attach the summary to a variable, the <code>frame variable</code> command, supports a <code>--summary</code> option that tells LLDB to use the named summary given instead of the default one.</p> <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add --summary-string "x=${var.integer}" --name NamedSummary </td> <table> <code> <b>(lldb)</b> frame variable one<br> (i_am_cool) one = int = 3, float = 3.14159, char = 69<br> <b>(lldb)</b> frame variable one --summary NamedSummary<br> (i_am_cool) one = x=3<br> </code> </p> <p>When defining a named summmary, binding it to one or more types becomes optional. Even if you bind the named summary to a type, and later change the summary string for that type, the named summary will not be changed by that. You can delete named summaries by using the <code>type summary delete</code> command, as if the summary name was the datatype that the summary is applied to</p> <p>A summary attached to a variable using the </code>--summary</code> option, has the same semantics that a custom format attached using the <code>-f</code> option has: it stays attached till you attach a new one, or till you let your program run again.</p> </div> </div> <div class="post"> <h1 class="postheader">Synthetic children</h1> <div class="postcontent"> <p>Summaries work well when one is able to navigate through an expression path. In order for LLDB to do so, appropriate debugging information must be available.</p> <p>Some types are <i>opaque</i>, i.e. no knowledge of their internals is provided. When that's the case, expression paths do not work correctly.</p> <p>In other cases, the internals are available to use in expression paths, but they do not provide a user-friendly representation of the object's value.</p> <p>For instance, consider an STL vector, as implemented by the <a href="http://gcc.gnu.org/onlinedocs/libstdc++/">GNU C++ Library</a>:</p> <code> <b>(lldb)</b> frame variable numbers -T<br/> (std::vector<int>) numbers = {<br/> (std::_Vector_base<int, std::allocator<int> >) std::_Vector_base<int, std::allocator<int> > = {<br/> (std::_Vector_base<int, std::allocator&tl;int> >::_Vector_impl) _M_impl = {<br/> (int *) _M_start = 0x00000001001008a0<br/> (int *) _M_finish = 0x00000001001008a8<br/> (int *) _M_end_of_storage = 0x00000001001008a8<br/> }<br/> }<br/> }<br/> </code> <p>Here, you can see how the type is implemented, and you can write a summary for that implementation but that is not going to help you infer what items are actually stored in the vector.</p> <p>What you would like to see is probably something like:</p> <code> <b>(lldb)</b> frame variable numbers -T<br/> (std::vector<int>) numbers = {<br/> (int) [0] = 1<br/> (int) [1] = 12<br/> (int) [2] = 123<br/> (int) [3] = 1234<br/> }<br/> </code> <p>Synthetic children are a way to get that result.</p> <p>The feature is based upon the idea of providing a new set of children for a variable that replaces the ones available by default through the debug information. In the example, we can use synthetic children to provide the vector items as children for the std::vector object.</p> <p>In order to create synthetic children, you need to provide a Python class that adheres to a given <i>interface</i> (the word is italicized because <a href="http://en.wikipedia.org/wiki/Duck_typing">Python has no explicit notion of interface</a>, by that word we mean a given set of methods must be implemented by the Python class):</p> <code> <font color=blue>class</font> SyntheticChildrenProvider:<br/> <font color=blue>def</font> __init__(self, valobj, dict):<br/> <i>this call should initialize the Python object using valobj as the variable to provide synthetic children for</i> <br/> <font color=blue>def</font> num_children(self): <br/> <i>this call should return the number of children that you want your object to have</i> <br/> <font color=blue>def</font> get_child_index(self,name): <br/> <i>this call should return the index of the synthetic child whose name is given as argument</i> <br/> <font color=blue>def</font> get_child_at_index(self,index): <br/> <i>this call should return a new LLDB SBValue object representing the child at the index given as argument</i> <br/> <font color=blue>def</font> update(self): <br/> <i>this call should be used to update the internal state of this Python object whenever the state of the variables in LLDB changes.</i><sup>[1]</sup><br/> </code> <sup>[1]</sup> Currently this method is optional, because the internal state of synthetic children providers will not be preserved. However, this is meant to change in future versions of LLDB. <p>For examples of how synthetic children are created, you are encouraged to look at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/">examples/synthetic</a> in the LLDB trunk. You may especially want to begin looking at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/StdVectorSynthProvider.py">StdVector</a> to get a feel for this feature, as it is a relatively easy and well commented example.</p> <p>While the <code>update</code> method is optional, the design pattern consistently used in synthetic providers shipping with LLDB is to use the <code>__init__</code> to store the SBValue instance as a part of <code>self</code>, and then call <code>update</code> to perform the actual initialization. This pattern should make for a transparent transition to a future version of LLDB that persists synthetic children. For example:</p> <code> <font color=blue>def</font> __init__(self, valobj, dict):<br/> self.valobj = valobj;<br/> self.update() </code> <p>Once a synthetic children provider is written, one must load it into LLDB before it can be used. Currently, one can use the LLDB <code>script</code> command to type Python code interactively, or use the <code>script import <i>module</i></code> command to load Python code from a Python module (ordinary rules apply to importing modules this way). A third option is to type the code for the provider class interactively while adding it.</p> <p>For example, let's pretend we have a class <code>Foo</code> for which a synthetic children provider class <code>Foo_Provider</code> is available, in a Python module named <code>Foo_Tools</code>. The following interaction sets <code>Foo_Provider</code> as a synthetic children provider in LLDB:</p> <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> script import Foo_Tools<br/> <b>(lldb)</b> type synthetic add Foo --python-class Foo_Tools.Foo_Provider </td> <table> <code> <b>(lldb)</b> frame variable a_foo<br/> (Foo) a_foo = {<br/> x = 1<br/> y = "Hello world"<br/> } <br/> </code> </p> <p>Currently, in LLDB <a href="http://llvm.org/svn/llvm-project/lldb/trunk/">top of tree</a>, synthetic children providers are enabled for <code>std::vector<T></code>, <code>std::list<T></code> and <code>std::map<K,V></code>.</p> <p>Synthetic children extend summary strings by enabling a new special variable: <code>${svar</code>.<br/> This symbol tells LLDB to refer expression paths to the synthetic children instead of the real ones. For instance,</p> <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add --expand -x "std::vector<" --summary-string "${svar%#} items" </td> </table> <code> <b>(lldb)</b> frame variable numbers<br/> (std::vector<int>) numbers = 4 items {<br/> (int) [0] = 1<br/> (int) [1] = 12<br/> (int) [2] = 123<br/> (int) [3] = 1234<br/> }<br/> </code> </p> <p>In some cases, if LLDB is unable to use the real object to get a child specified in an expression path, it will automatically refer to the synthetic children. While in summaries it is best to always use <code>${svar</code> to make your intentions clearer, interactive debugging can benefit from this behavior, as in: <code> <b>(lldb)</b> frame variable numbers[0] numbers[1]<br/> (int) numbers[0] = 1<br/> (int) numbers[1] = 12<br/> </code> </p> Unlike many other visualization features, however, the access to synthetic children only works when using <code>frame variable</code>, and is not supported in <code>expression</code>:<br/> <code> <b>(lldb)</b> expression numbers[0]<br/> Error [IRForTarget]: Call to a function '_ZNSt33vector<int, std::allocator<int> >ixEm' that is not present in the target<br/> error: Couldn't convert the expression to DWARF<br/> </code> </p> The reason for this is that classes might have an overloaded <code><font color="blue">operator</font> []</code>, or other special provisions and the <code>expression</code> command ignores synthetic children when evaluating its arguments. </div> </div> <div class="post"> <h1 class="postheader">Filters</h1> <div class="postcontent"> <p>Filters are a solution to the display of complex classes. At times, classes have many member variables but not all of these are actually necessary for the user to see.</p> <p>A filter will solve this issue by only letting the user see those member variables he cares about. Of course, the equivalent of a filter can be implemented easily using synthetic children, but a filter lets you get the job done without having to write Python code.</p> <p>For instance, if your class <code>Foobar</code> has member variables named <code>A</code> thru <code>Z</code>, but you only need to see the ones named <code>B</code>, <code>H</code> and <code>Q</code>, you can define a filter: <table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type filter add Foobar --child B --child H --child Q </td> </table> <code> <b>(lldb)</b> frame variable a_foobar<br/> (Foobar) a_foobar = {<br/> (int) B = 1<br/> (char) H = 'H'<br/> (std::string) Q = "Hello world"<br/> }<br/> </code> </p> </div> </div> <div class="post"> <h1 class="postheader">Objective-C dynamic type discovery</h1> <div class="postcontent"> <p>When doing Objective-C development, you may notice that some of your variables come out as of type <code>id</code> (for instance, items extracted from <code>NSArray</code>). While this does not influence the ability of the runtime to send messages to them, it could make it impossible for LLDB to determine the actual formatters for that object, given its type-based algorithm.</p> <p>The debugger, however, can dynamically discover the type of an Objective-C variable, much like the runtime itself does when invoking a selector. In order to let LLDB do that, however, a special option to <code>frame variable</code> is required: <code>--dynamic-type</code>.</p> <p><code>--dynamic-type</code> can have one of three values: <ul> <li><code>no-dynamic-values</code>: the default, prevents dynamic type discovery</li> <li><code>no-run-target</code>: enables dynamic type discovery as long as running code on the target is not required</li> <li><code>run-target</code>: enables code execution on the target in order to perform dynamic type discovery</li> </ul> </p> <p> If you specify a value of either <code>no-run-target</code> or <code>run-target</code>, LLDB will detect the dynamic type of your variables and show the appropriate formatters for them. As an example: </p> <p><table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> frame variable ns_string --dynamic-type no-run-target --show-types </td> </table> <code>(id, dynamic type: __NSCFString) ns_string = 0x00000001001183d0 @"An NSString saying hello world"<br/> </code> <p> Because LLDB uses a detection algorithm that does not need to invoke any functions on the target process, <code>no-run-target</code> is enough for this to work. As a final sidenote on this, LLDB is currently able to provide a summary string for <code>NSString</code> that shows the content of the string, without requiring you to run code on the target process. <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/CFString.py"> CFString.py</a> contains the code for such a Python summary provider (the code is well commented, but you may find it hard to follow if it is your first time dealing with LLDB formatting features) and <a href="http://llvm.org/svn/llvm-project/lldb/trunk/test/functionalities/data-formatter/data-formatter-objc/"> this test case</a> contains an usage example. </p> </div> </div> <div class="post"> <h1 class="postheader">Categories</h1> <div class="postcontent"> <p>Categories are a way to group related formatters. For instance, LLDB itself groups the formatters for the C++ STL objects in a category named <code>gnu-libstdc++</code>. Basically, categories act like containers in which to store formatters for a same library or OS release.</p> <p>By default, three categories are created in LLDB: <code>system</code>, <code>gnu-libstdc++</code> and <code>default</code>. Every formatter that is not created inside a category, is by default a part of the <code>default</code> category. If you want to use a custom category for your formatters, all the <code>type ... add</code> (except for <code>type format add</code>), provide a <code>--category</code> (<code>-w</code>) option, that names the category to add the formatter to. To delete the formatter, you then have to specify the correct category.</p> <p>Categories can be in one of two states: enabled and disabled. A category is initially disabled, and can be enabled using the <code>type category enable</code> command. To disable an enabled category, the command to use is <code>type category disable</code>. The order in which categories are enabled or disabled is significant, in that LLDB uses that order when looking for formatters. Therefore, when you enable a category, it becomes the first one to be searched. The default categories are enabled in such a way that the search order is: <code>default</code> then <code>gnu-libstdc++</code> then finally <code>system</code>. As said, <code>gnu-libstdc++</code> contains formatters for C++ STL data types. <code>system</code> contains formatters for <code>char*</code> and <code>char[]</code>, which reflect the behavior of previous versions of LLDB which had built-in formatters for these types. Because now these are formatters, you can even replace them with your own if so you wish.</p> <p>There is no special command to create a category. When you place a formatter in a category, if that category does not exist, it is automatically created. For instance,</p> <p><table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type summary add Foobar --summary-string "a foobar" --category newcategory </td> </table> automatically creates a (disabled) category named newcategory.</p> <p>Another way to create a new (empty) category, is to enable it, as in:</p> <p><table class="stats" width="620" cellspacing="0"> <td class="content"> <b>(lldb)</b> type category enable newcategory </td> </table> <p>However, in this case LLDB warns you that enabling an empty category has no effect. If you add formatters to the category after enabling it, they will be honored. But an empty category <i>per se</i> does not change the way any type is displayed. The reason the debugger warns you is that enabling an empty category might be a typo, and you effectively wanted to enable a similarly-named but not-empty category.</p> </div> </div> <div class="post"> <h1 class="postheader">Finding formatters 101</h1> <div class="postcontent"> <p>While the rules for finding an appropriate format for a type are relatively simple (just go through typedef hierarchies), searching other formatters goes through a rather intricate set of rules. Namely, what happens is that LLDB starts looking in each enabled category, according to the order in which they were enabled (latest enabled first). In each category, LLDB does the following:</p> <ul> <li>If there is a formatter for the type of the variable, use it</li> <li>If this object is a pointer, and there is a formatter for the pointee type that does not skip pointers, use it</li> <li>If this object is a reference, and there is a formatter for the referred type that does not skip references, use it</li> <li>If this object is an Objective-C class with a parent class, look at the parent class (and parent of parent, ...). This phase can be based upon the actual type of the object as inferred by the value of its <code>isa</code> pointer, or upon the debugging information inferred by the debugger. The user can use the dynamic typing settings to elect one or the other behavior.</li> <li>If this object is a C++ class with base classes, look at base classes (and bases of bases, ...)</li> <li>If this object is a C++ class with virtual base classes, look at the virtual base classes (and bases of bases, ...)</li> <li>If this object's type is a typedef, go through typedef hierarchy (LLDB might not be able to do this if the compiler has not emitted enough information. If the required information to traverse typedef hierarchies is missing, type cascading will not work. The <a href="http://clang.llvm.org/">clang compiler</a>, part of the LLVM project, emits the correct debugging information for LLDB to cascade)</li> <li>If everything has failed, repeat the above search, looking for regular expressions instead of exact matches</li> </ul> <p>If any of those attempts returned a valid formatter to be used, that one is used, and the search is terminated (without going to look in other categories). If nothing was found in the current category, the next enabled category is scanned according to the same algorithm. If there are no more enabled categories, the search has failed.</p> </div> </div> <div class="post"> <h1 class="postheader">TODOs</h1> <div class="postcontent"> <ul> <li>There's no way to do multiple dereferencing, and you need to be careful what the dereferencing operation is binding to in complicated scenarios</li> <li>Synthetic children providers cannot have a permanent state</li> <li>Smarter algorithm to detect possible typos in category names</li> <li><code>type format add</code> does not support the <code>-x</code> option</li> </ul> </div> </div> </div> </div> </div> </body> </html>