1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2 <html xmlns="http://www.w3.org/1999/xhtml">
4 <meta http-equiv="Content-Type" content="text/html;
6 <link href="style.css" rel="stylesheet" type="text/css">
7 <title>LLDB Data Formatters</title>
10 <div class="www_title"> The <strong>LLDB</strong> Debugger </div>
13 <!--#include virtual="sidebar.incl"-->
16 <h1 class="postheader">Variable display</h1>
17 <div class="postcontent">
19 <p>LLDB has a data formatters subsystem that allows users to define custom display options for their variables.</p>
21 <p>Usually, when you type <code>frame variable</code> or
22 run some <code>expression</code> LLDB will
23 automatically choose the way to display your results on
24 a per-type basis, as in the following example:</p>
26 <p> <code> <b>(lldb)</b> frame variable<br>
28 (intptr_t) y = 124752287<br>
31 <p>However, in certain cases, you may want to associate a
32 different style to the display for certain datatypes.
33 To do so, you need to give hints to the debugger as to
34 how variables should be displayed.<br>
35 The LLDB <b>type</b> command allows you to do just that.<br>
38 <p>Using it you can change your visualization to look like this: </p>
40 <p> <code> <b>(lldb)</b> frame variable<br>
41 (uint8_t) x = chr='a' dec=65 hex=0x41<br>
42 (intptr_t) y = 0x76f919f<br>
45 <p>There are several features related to data visualization: <span
46 style="font-style: italic;">formats</span>, <span
47 style="font-style: italic;">summaries</span>, <span
48 style="font-style: italic;">filters</span>, <span
49 style="font-style: italic;">synthetic children</span>.</p>
51 <p>To reflect this, the <b>type</b> command has five
55 <p><code>type format</code></p>
56 <p><code>type summary</code></p>
57 <p><code>type filter</code></p>
58 <p><code>type synthetic</code></p>
59 <p><code>type category</code></p>
62 <p>These commands are meant to bind printing options to
63 types. When variables are printed, LLDB will first check
64 if custom printing options have been associated to a
65 variable's type and, if so, use them instead of picking
66 the default choices.<br>
69 <p>Each of the commands (except <code>type category</code>) has four subcommands available:<br>
71 <p><code>add</code>: associates a new printing option to one
73 <p><code>delete</code>: deletes an existing association</p>
74 <p><code>list</code>: provides a listing of all
76 <p><code>clear</code>: deletes all associations</p>
81 <h1 class="postheader">type format</h1>
82 <div class="postcontent">
84 <p>Type formats enable you to quickly override the default
85 format for displaying primitive types (the usual basic
86 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>
88 <p>If for some reason you want all <code>int</code>
89 variables in your program to print out as hex, you can add
90 a format to the <code>int</code> type.<br></p>
92 <p>This is done by typing
93 <table class="stats" width="620" cellspacing="0">
95 <b>(lldb)</b> type format add --format hex int
98 at the LLDB command line.</p>
100 <p>The <code>--format</code> (which you can shorten to <code>-f</code>) option accepts a <a
101 href="#formatstable">format name</a>. Then, you provide one or more
102 types to which you want the new format applied.</p>
104 <p>A frequent scenario is that your program has a <code>typedef</code>
105 for a numeric type that you know represents something
106 that must be printed in a certain way. Again, you can
107 add a format just to that typedef by using <code>type
108 format add</code> with the name alias.</p>
110 <p>But things can quickly get hierarchical. Let's say you
111 have a situation like the following:</p>
113 <p><code><font color="blue">typedef int</font> A;<br>
114 <font color="blue">typedef</font> A B;<br>
115 <font color="blue">typedef</font> B C;<br>
116 <font color="blue">typedef</font> C D;<br>
119 <p>and you want to show all <code>A</code>'s as hex, all
120 <code>C'</code>s as byte arrays and leave the defaults
121 untouched for other types (albeit its contrived look, the example is far
122 from unrealistic in large software systems).</p>
124 <p>If you simply type <br>
125 <table class="stats" width="620" cellspacing="0">
127 <b>(lldb)</b> type format add -f hex A<br>
128 <b>(lldb)</b> type format add -f uint8_t[] C
132 values of type <code>B</code> will be shown as hex
133 and values of type <code>D</code> as byte arrays, as in:</p>
136 <b>(lldb)</b> frame variable -T<br/>
137 (A) a = 0x00000001<br/>
138 (B) b = 0x00000002<br/>
139 (C) c = {0x03 0x00 0x00 0x00}<br/>
140 (D) d = {0x04 0x00 0x00 0x00}<br/>
143 <p>This is because by default LLDB <i>cascades</i>
144 formats through typedef chains. In order to avoid that
145 you can use the option <code>-C no</code> to prevent
146 cascading, thus making the two commands required to
147 achieve your goal:<br>
148 <table class="stats" width="620" cellspacing="0">
150 <b>(lldb)</b> type format add -C no -f hex A<br>
151 <b>(lldb)</b> type format add -C no -f uint8_t[] C
155 <p>which provides the desired output:</p>
157 <b>(lldb)</b> frame variable -T<br/>
158 (A) a = 0x00000001<br/>
160 (C) c = {0x03 0x00 0x00 0x00}<br/>
164 <p>Two additional options that you will want to look at
165 are <code>--skip-pointers</code> (<code>-p</code>) and <code>--skip-references</code> (<code>-r</code>). These two
166 options prevent LLDB from applying a format for type <code>T</code>
167 to values of type <code>T*</code> and <code>T&</code>
170 <p> <code> <b>(lldb)</b> type format add -f float32[]
172 <b>(lldb)</b> frame variable pointer *pointer -T<br>
173 (int *) pointer = {1.46991e-39 1.4013e-45}<br>
174 (int) *pointer = {1.53302e-42}<br>
175 <b>(lldb)</b> type format add -f float32[] int -p<br>
176 <b>(lldb)</b> frame variable pointer *pointer -T<br>
177 (int *) pointer = 0x0000000100100180<br>
178 (int) *pointer = {1.53302e-42}<br>
181 <p>While they can be applied to pointers and references, formats will make no attempt
182 to dereference the pointer and extract the value before applying the format, which means you
183 are effectively formatting the address stored in the pointer rather than the pointee value.
184 For this reason, you may want to use the <code>-p</code> option when defining formats.</p>
186 <p>If you need to delete a custom format simply type <code>type
187 format delete</code> followed by the name of the type
188 to which the format applies.Even if you
189 defined the same format for multiple types on the same command,
190 <code>type format delete</code> will only remove the format for
191 the type name passed as argument.<br>
194 To delete ALL formats, use
195 <code>type format clear</code>. To see all the formats
196 defined, use <code>type format list</code>.</p>
198 <p>If all you need to do, however, is display one variable
199 in a custom format, while leaving the others of the same
200 type untouched, you can simply type:<br>
202 <table class="stats" width="620" cellspacing="0">
204 <b>(lldb)</b> frame variable counter -f hex
208 <p>This has the effect of displaying the value of <code>counter</code>
209 as an hexadecimal number, and will keep showing it this
210 way until you either pick a different format or till you
211 let your program run again.</p>
213 <p>Finally, this is a list of formatting options available
215 which you can pick:</p><a name="formatstable"></a>
219 <td width="23%"><b>Format name</b></td>
220 <td><b>Abbreviation</b></td>
221 <td><b>Description</b></td>
224 <td><b>default</b></td>
227 <td>the default LLDB algorithm is used to pick a
231 <td><b>boolean</b></td>
233 <td>show this as a true/false boolean, using the
234 customary rule that 0 is false and everything else
238 <td><b>binary</b></td>
240 <td>show this as a sequence of bits</td>
243 <td><b>bytes</b></td>
245 <td>show the bytes one after the other<br>
246 e.g. <code>(int) s.x = 07 00 00 00</code></td>
249 <td><b>bytes with ASCII</b></td>
251 <td>show the bytes, but try to display them as ASCII
252 characters as well<br>
253 e.g. <code>(int *) c.sp.x = 50 f8 bf 5f ff 7f 00
254 00 P.._....</code></td>
257 <td><b>character</b></td>
259 <td>show the bytes as ASCII characters<br>
260 e.g. <code>(int *) c.sp.x =
261 P\xf8\xbf_\xff\x7f\0\0</code></td>
264 <td><b>printable character</b></td>
266 <td>show the bytes as printable ASCII
268 e.g. <code>(int *) c.sp.x = P.._....</code></td>
271 <td><b>complex float</b></td>
273 <td>interpret this value as the real and imaginary
274 part of a complex floating-point number<br>
275 e.g. <code>(int *) c.sp.x = 2.76658e+19 +
276 4.59163e-41i</code></td>
279 <td><b>c-string</b></td>
281 <td>show this as a 0-terminated C string</td>
284 <td><b>decimal</b></td>
286 <td>show this as a signed integer number (this does
287 not perform a cast, it simply shows the bytes as
288 an integer with sign)</td>
291 <td><b>enumeration</b></td>
293 <td>show this as an enumeration, printing the
294 value's name if available or the integer value
296 e.g. <code>(enum enumType) val_type = eValue2</code></td>
301 <td>show this as in hexadecimal notation (this does
302 not perform a cast, it simply shows the bytes as
306 <td><b>float</b></td>
308 <td>show this as a floating-point number (this does
309 not perform a cast, it simply interprets the bytes
310 as an IEEE754 floating-point value)</td>
313 <td><b>octal</b></td>
315 <td>show this in octal notation</td>
318 <td><b>OSType</b></td>
320 <td>show this as a MacOS OSType<br>
321 e.g. <code>(float) x = '\n\x1f\xd7\n'</code></td>
324 <td><b>unicode16</b></td>
326 <td>show this as UTF-16 characters<br>
327 e.g. <code>(float) x = 0xd70a 0x411f</code></td>
330 <td><b>unicode32</b></td>
333 <td>show this as UTF-32 characters<br>
334 e.g. <code>(float) x = 0x411fd70a</code></td>
337 <td><b>unsigned decimal</b></td>
339 <td>show this as an unsigned integer number (this
340 does not perform a cast, it simply shows the bytes
341 as unsigned integer)</td>
344 <td><b>pointer</b></td>
346 <td>show this as a native pointer (unless this is
347 really a pointer, the resulting address will
348 probably be invalid)</td>
351 <td><b>char[]</b></td>
354 <td>show this as an array of characters<br>
355 e.g. <code>(char) *c.sp.z = {X}</code></td>
358 <td><b>int8_t[], uint8_t[]<br>
359 int16_t[], uint16_t[]<br>
360 int32_t[], uint32_t[]<br>
361 int64_t[], uint64_t[]<br>
365 <td>show this as an array of the corresponding
368 <code>(int) x = {1 0 0 0}</code> (with uint8_t[])<br>
369 <code>(int) y = {0x00000001}</code> (with uint32_t[])</td>
372 <td><b>float32[], float64[]</b></td>
375 <td>show this as an array of the corresponding
376 floating-point type<br>
377 e.g. <code>(int *) pointer = {1.46991e-39
378 1.4013e-45}</code></td>
381 <td><b>complex integer</b></td>
383 <td>interpret this value as the real and imaginary
384 part of a complex integer number<br>
385 e.g. <code>(int *) pointer = 1048960 + 1i</code></td>
388 <td><b>character array</b></td>
390 <td>show this as a character array<br>
391 e.g. <code>(int *) pointer =
392 \x80\x01\x10\0\x01\0\0\0</code></td>
400 <h1 class="postheader">type summary</h1>
401 <div class="postcontent">
402 <p>Type formats work by showing a different kind of display for
403 the value of a variable. However, they only work for basic types.
404 When you want to display a class or struct in a custom format, you
405 cannot do that using formats.</p>
406 <p>A different feature, type summaries, works by extracting
407 information from classes, structures, ... (<i>aggregate types</i>)
408 and arranging it in a user-defined format, as in the following example:</p>
409 <p> <i>before adding a summary...</i><br>
410 <code> <b>(lldb)</b> frame variable -T one<br>
411 (i_am_cool) one = {<br>
412 (int) x = 3<br>
413 (float) y = 3.14159<br>
414 (char) z = 'E'<br>
417 <i>after adding a summary...</i><br>
418 <code> <b>(lldb)</b> frame variable one<br>
419 (i_am_cool) one = int = 3, float = 3.14159, char = 69<br>
422 <p>There are two ways to use type summaries: the first one is to bind a <i>
423 summary string</i> to the type; the second is to write a Python script that returns
424 the string to be used as summary. Both options are enabled by the <code>type summary add</code>
426 <p>The command to obtain the output shown in the example is:</p>
427 <table class="stats" width="620" cellspacing="0">
429 <b>(lldb)</b> type summary add --summary-string "int = ${var.x}, float = ${var.y}, char = ${var.z%u}" i_am_cool
433 <p>Initially, we will focus on summary strings, and then describe the Python binding
439 <h1 class="postheader">Summary Strings</h1>
440 <div class="postcontent">
441 <p>Summary strings are written using a simple control language, exemplified by the snippet above.
442 A summary string contains a sequence of tokens that are processed by LLDB to generate the summary.</p>
444 <p>Summary strings can contain plain text, control characters and
445 special variables that have access to information about
446 the current object and the overall program state.</p>
447 <p>Plain text is any sequence of characters that doesn't contain a <code><b>'{'</b></code>,
448 <code><b>'}'</b></code>, <code><b>'$'</b></code>, or <code><b>'\'</b></code>
449 character, which are the syntax control characters.</p>
450 <p>The special variables are found in between a <code><b>"${"</b></code>
451 prefix, and end with a <code><b>"}"</b></code> suffix. Variables can be a simple name
452 or they can refer to complex objects that have subitems themselves.
453 In other words, a variable looks like <code>"<b>${object}</b>"</code> or
454 <code>"<b>${object.child.otherchild}</b>"</code>. A variable can also be prefixed or
455 suffixed with other symbols meant to change the way its value is handled. An example is
456 <code>"<b>${*var.int_pointer[0-3]}</b>".</code></p>
457 <p>Basically, the syntax is the same one described <a
458 href="formats.html">Frame and Thread Formatting</a>
459 plus additional symbols specific for summary strings. The main of them is <code>${var</code>,
460 which is used refer to the variable that a summary is being created for.</p>
461 <p>The simplest thing you can do is grab a member variable
462 of a class or structure by typing its <i>expression
463 path</i>. In the previous example, the expression path
464 for the field <code>float y</code> is simply <code>.y</code>.
465 Thus, to ask the summary string to display <code>y</code>
466 you would type <code>${var.y}</code>.</p>
467 <p>If you have code like the following: <br>
468 <code> <font color="blue">struct</font> A {<br>
469 <font color="blue">int</font> x;<br>
470 <font color="blue">int</font> y;<br>
472 <font color="blue">struct</font> B {<br>
473 A x;<br>
474 A y;<br>
475 <font color="blue">int</font> *z;<br>
477 </code> the expression path for the <code>y</code>
478 member of the <code>x</code> member of an object of
479 type <code>B</code> would be <code>.x.y</code> and you
480 would type <code>${var.x.y}</code> to display it in a
481 summary string for type <code>B</code>. </p>
482 <p>By default, a summary defined for type <code>T</code>, also works for types
483 <code>T*</code> and <code>T&</code> (you can disable this behavior if desired).
484 For this reason, expression paths do not differentiate between <code>.</code>
485 and <code>-></code>, and the above expression path <code>.x.y</code>
486 would be just as good if you were displaying a <code>B*</code>,
487 or even if the actual definition of <code>B</code>
489 <font color="blue">struct</font> B {<br>
490 A *x;<br>
491 A y;<br>
492 <font color="blue">int</font> *z;<br>
495 <p>This is unlike the behavior of <code>frame variable</code>
496 which, on the contrary, will enforce the distinction. As
497 hinted above, the rationale for this choice is that
498 waiving this distinction enables you to write a summary
499 string once for type <code>T</code> and use it for both
500 <code>T</code> and <code>T*</code> instances. As a
501 summary string is mostly about extracting nested
502 members' information, a pointer to an object is just as
503 good as the object itself for the purpose.</p>
504 <p>If you need to access the value of the integer pointed to by <code>B::z</code>, you
505 cannot simply say <code>${var.z}</code> because that symbol refers to the pointer <code>z</code>.
506 In order to dereference it and get the pointed value, you should say <code>${*var.z}</code>. The <code>${*var</code>
507 tells LLDB to get the object that the expression paths leads to, and then dereference it. In this example is it
508 equivalent to <code>*(bObject.z)</code> in C/C++ syntax. Because <code>.</code> and <code>-></code> operators can both be
509 used, there is no need to have dereferences in the middle of an expression path (e.g. you do not need to type
510 <code>${*(var.x).x})</code> to read <code>A::x</code> as contained in <code>*(B::x)</code>. To achieve that effect
511 you can simply write <code>${var.x->x}</code>, or even <code>${var.x.x}</code>. The <code>*</code> operator only binds
512 to the result of the whole expression path, rather than piecewise, and there is no way to use parentheses to change
514 <p>Of course, a summary string can contain more than one <code>${var</code> specifier,
515 and can use <code>${var</code> and <code>${*var</code> specifiers together.</p>
519 <h1 class="postheader">Formatting summary elements</h1>
520 <div class="postcontent">
521 <p>An expression path can include formatting codes.
522 Much like the type formats discussed previously, you can also customize
523 the way variables are displayed in summary strings, regardless of the format they have
524 applied to their types. To do that, you can use <code>%<i>format</i></code> inside an expression path,
525 as in <code>${var.x->x%u}</code>, which would display the value of <code>x</code> as an unsigned integer.
527 <p>You can also use some other special format markers, not available
528 for formats themselves, but which carry a special meaning when used in this
534 <td width="23%"><b>Symbol</b></td>
535 <td><b>Description</b></td>
539 <td>Use this object's summary (the default for aggregate types)</td>
543 <td>Use this object's value (the default for non-aggregate types)</td>
547 <td>Use a language-runtime specific description (for C++ this does nothing,
548 for Objective-C it calls the NSPrintForDebugger API)</td>
552 <td>Use this object's location (memory address, register name, ...)</td>
556 <td>Use the count of the children of this object</td>
560 <td>Use this object's datatype name</td>
564 <td>Print the variable's basename</td>
568 <td>Print the expression path for this item</td>
573 <p>Starting with SVN r228207, you can also specify ${script.var:<i>pythonFuncName</i>}. Previously, back to r220821, this was
574 specified with a different syntax: ${var.script:<i>pythonFuncName</i>}.
575 <br/>It is expected that the function name you use specifies a function whose signature is the same
576 as a Python summary function. The return string from the function will be placed verbatim in the output.
578 You cannot use element access, or formatting symbols, in combination with this syntax. For example the following:
579 <table class="stats" width="620" cellspacing="0">
581 ${script.var.element[0]:myFunctionName%@}
584 is not valid and will cause the summary to fail to evaluate.
590 <h1 class="postheader">Element inlining</h1>
591 <div class="postcontent">
593 <p>Option <code>--inline-children</code> (<code>-c</code>) to <code>type summary add</code>
594 tells LLDB not to look for a summary string, but instead
595 to just print a listing of all the object's children on
597 <p> As an example, given a type <code>pair</code>:
599 <b>(lldb)</b> frame variable --show-types a_pair<br>
600 (pair) a_pair = {<br>
601 (int) first = 1;<br/>
602 (int) second = 2;<br/>
605 If one types the following commands:
606 <table class="stats" width="620" cellspacing="0">
608 <b>(lldb)</b> type summary add --inline-children pair<br>
611 the output becomes: <br><code>
613 <b>(lldb)</b> frame variable a_pair<br>
614 (pair) a_pair = (first=1, second=2)<br>
617 Of course, one can obtain the same effect by typing
618 <table class="stats" width="620" cellspacing="0">
620 <b>(lldb)</b> type summary add pair --summary-string "(first=${var.first}, second=${var.second})"<br>
624 While the final result is the same, using <code>--inline-children</code> can often save time. If one does not need to
625 see the names of the variables, but just their values, the option <code>--omit-names</code> (<code>-O</code>, uppercase letter o), can be combined with <code>--inline-children</code> to obtain:
628 <b>(lldb)</b> frame variable a_pair<br>
629 (pair) a_pair = (1, 2)<br>
632 which is of course the same as
634 <table class="stats" width="620" cellspacing="0">
636 <b>(lldb)</b> type summary add pair --summary-string "(${var.first}, ${var.second})"<br>
642 <h1 class="postheader">Bitfields and array syntax</h1>
643 <div class="postcontent">
644 <p>Sometimes, a basic type's value actually represents
645 several different values packed together in a bitfield.<br/>
646 With the classical view, there is no way to look at
647 them. Hexadecimal display can help, but if the bits
648 actually span nibble boundaries, the help is limited.<br/>
649 Binary view would show it all without ambiguity, but is
650 often too detailed and hard to read for real-life
653 To cope with the issue, LLDB supports native
654 bitfield formatting in summary strings. If your
655 expression paths leads to a so-called <i>scalar type</i>
656 (the usual int, float, char, double, short, long, long
657 long, double, long double and unsigned variants), you
658 can ask LLDB to only grab some bits out of the value and
659 display them in any format you like. If you only need one bit
660 you can use the <code>[</code><i>n</i><code>]</code>, just like
661 indexing an array. To extract multiple bits, you can use
662 a slice-like syntax: <code>[</code><i>n</i>-<i>m</i><code>]</code>, e.g. <br><p>
663 <code> <b>(lldb)</b> frame variable float_point<br>
664 (float) float_point = -3.14159<br> </code>
665 <table class="stats" width="620" cellspacing="0">
667 <b>(lldb)</b> type summary add --summary-string "Sign: ${var[31]%B}
668 Exponent: ${var[30-23]%x} Mantissa: ${var[0-22]%u}"
674 <b>(lldb)</b> frame variable float_point<br>
675 (float) float_point = -3.14159 Sign: true Exponent:
676 0x00000080 Mantissa: 4788184<br>
677 </code> In this example, LLDB shows the internal
678 representation of a <code>float</code> variable by
679 extracting bitfields out of a float object.</p>
681 <p> When typing a range, the extremes <i>n</i> and <i>m</i> are always
682 included, and the order of the indices is irrelevant. </p>
684 <p>LLDB also allows to use a similar syntax to display
685 array members inside a summary string. For instance, you
686 may want to display all arrays of a given type using a
687 more compact notation than the default, and then just
688 delve into individual array members that prove
689 interesting to your debugging task. You can tell
690 LLDB to format arrays in special ways, possibly
691 independent of the way the array members' datatype is formatted. <br>
693 <code> <b>(lldb)</b> frame variable sarray<br>
694 (Simple [3]) sarray = {<br>
695 [0] = {<br>
696 x = 1<br>
697 y = 2<br>
698 z = '\x03'<br>
699 }<br>
700 [1] = {<br>
701 x = 4<br>
702 y = 5<br>
703 z = '\x06'<br>
704 }<br>
705 [2] = {<br>
706 x = 7<br>
707 y = 8<br>
708 z = '\t'<br>
709 }<br>
712 <table class="stats" width="620" cellspacing="0">
714 <b>(lldb)</b> type summary add --summary-string "${var[].x}" "Simple
720 <b>(lldb)</b> frame variable sarray<br>
721 (Simple [3]) sarray = [1,4,7]<br></code></p>
723 <p>The <code>[]</code> symbol amounts to: <i>if <code>var</code>
724 is an array and I know its size, apply this summary
725 string to every element of the array</i>. Here, we are
726 asking LLDB to display <code>.x</code> for every
727 element of the array, and in fact this is what happens.
728 If you find some of those integers anomalous, you can
729 then inspect that one item in greater detail, without
730 the array format getting in the way: <br>
731 <code> <b>(lldb)</b> frame variable sarray[1]<br>
732 (Simple) sarray[1] = {<br>
733 x = 4<br>
734 y = 5<br>
735 z = '\x06'<br>
738 <p>You can also ask LLDB to only print a subset of the
739 array range by using the same syntax used to extract bit
741 <table class="stats" width="620" cellspacing="0">
743 <b>(lldb)</b> type summary add --summary-string "${var[1-2].x}" "Simple
748 <b>(lldb)</b> frame variable sarray<br>
749 (Simple [3]) sarray = [4,7]<br></code></p>
751 <p>If you are dealing with a pointer that you know is an array, you can use this
752 syntax to display the elements contained in the pointed array instead of just
753 the pointer value. However, because pointers have no notion of their size, the
754 empty brackets <code>[]</code> operator does not work, and you must explicitly provide
755 higher and lower bounds.</p>
757 <p>In general, LLDB needs the square brackets operator <code>[]</code> in
758 order to handle arrays and pointers correctly, and for pointers it also
759 needs a range. However, a few special cases are defined to make your life easier:
761 <li>you can print a 0-terminated string (<i>C-string</i>) using the %s format,
762 omitting square brackets, as in:
763 <table class="stats" width="620" cellspacing="0">
765 <b>(lldb)</b> type summary add --summary-string "${var%s}" "char *"
769 This syntax works for <code>char*</code> as well as for <code>char[]</code>
770 because LLDB can rely on the final <code>\0</code> terminator to know when the string
772 LLDB has default summary strings for <code>char*</code> and <code>char[]</code> that use
773 this special case. On debugger startup, the following are defined automatically:
774 <table class="stats" width="620" cellspacing="0">
776 <b>(lldb)</b> type summary add --summary-string "${var%s}" "char *"<br/>
777 <b>(lldb)</b> type summary add --summary-string "${var%s}" -x "char \[[0-9]+]"<br/>
784 <li>any of the array formats (<code>int8_t[]</code>,
785 <code>float32{}</code>, ...), and the <code>y</code>, <code>Y</code>
786 and <code>a</code> formats
787 work to print an array of a non-aggregate
788 type, even if square brackets are omitted.
789 <table class="stats" width="620" cellspacing="0">
791 <b>(lldb)</b> type summary add --summary-string "${var%int32_t[]}" "int [10]"
796 This feature, however, is not enabled for pointers because there is no
797 way for LLDB to detect the end of the pointed data.
799 This also does not work for other formats (e.g. <code>boolean</code>), and you must
800 specify the square brackets operator to get the expected output.
806 <h1 class="postheader">Python scripting</h1>
807 <div class="postcontent">
809 <p>Most of the times, summary strings prove good enough for the job of summarizing
810 the contents of a variable. However, as soon as you need to do more than picking
811 some values and rearranging them for display, summary strings stop being an
812 effective tool. This is because summary strings lack the power to actually perform
813 any kind of computation on the value of variables.</p>
814 <p>To solve this issue, you can bind some Python scripting code as a summary for
815 your datatype, and that script has the ability to both extract children variables
816 as the summary strings do and to perform active computation on the extracted
817 values. As a small example, let's say we have a Rectangle class:</p>
820 <font color="blue">class</font> Rectangle<br/>
822 <font color="blue">private</font>:<br/>
823 <font color="blue">int</font> height;<br/>
824 <font color="blue">int</font> width;<br/>
825 <font color="blue">public</font>:<br/>
826 Rectangle() : height(3), width(5) {}<br/>
827 Rectangle(<font color="blue">int</font> H) : height(H), width(H*2-1) {}<br/>
828 Rectangle(<font color="blue">int</font> H, <font color="blue">int</font> W) : height(H), width(W) {}<br/>
830 <font color="blue">int</font> GetHeight() { return height; }<br/>
831 <font color="blue">int</font> GetWidth() { return width; }<br/>
836 <p>Summary strings are effective to reduce the screen real estate used by
837 the default viewing mode, but are not effective if we want to display the
838 area and perimeter of <code>Rectangle</code> objects</p>
840 <p>To obtain this, we can simply attach a small Python script to the <code>Rectangle</code>
841 class, as shown in this example:</p>
843 <table class="stats" width="620" cellspacing="0">
845 <b>(lldb)</b> type summary add -P Rectangle<br/>
846 Enter your Python command(s). Type 'DONE' to end.<br/>
847 def function (valobj,internal_dict):<br/>
848 height_val = valobj.GetChildMemberWithName('height')<br/>
849 width_val = valobj.GetChildMemberWithName('width')<br/>
850 height = height_val.GetValueAsUnsigned(0)<br/>
851 width = width_val.GetValueAsUnsigned(0)<br/>
852 area = height*width<br/>
853 perimeter = 2*(height + width)<br/>
854 return 'Area: ' + str(area) + ', Perimeter: ' + str(perimeter)<br/>
855 DONE<br/>
856 <b>(lldb)</b> frame variable<br/>
857 (Rectangle) r1 = Area: 20, Perimeter: 18<br/>
858 (Rectangle) r2 = Area: 72, Perimeter: 36<br/>
859 (Rectangle) r3 = Area: 16, Perimeter: 16<br/>
863 <p>In order to write effective summary scripts, you need to know the LLDB public
864 API, which is the way Python code can access the LLDB object model. For further
865 details on the API you should look at <a href="scripting.html">this page</a>, or at
866 the LLDB <a href="docs.html">API reference documentation</a>.</p>
868 <p>As a brief introduction, your script is encapsulated into a function that is
869 passed two parameters: <code>valobj</code> and <code>internal_dict</code>.</p>
871 <p><code>internal_dict</code> is an internal support parameter used by LLDB and you should
872 not touch it.<br/><code>valobj</code> is the object encapsulating the actual
873 variable being displayed, and its type is <a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/API/SBValue.h">SBValue</a>.
874 Out of the many possible operations on an SBValue, the basic one is retrieve the children objects
875 it contains (essentially, the fields of the object wrapped by it), by calling
876 <code>GetChildMemberWithName()</code>, passing it the child's name as a string.<br/>
877 If the variable has a value, you can ask for it, and return it as a string using <code>GetValue()</code>,
878 or as a signed/unsigned number using <code>GetValueAsSigned()</code>, <code>GetValueAsUnsigned()</code>.
879 It is also possible to retrieve an <a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/API/SBData.h"><code>SBData</code></a> object by calling <code>GetData()</code> and then read
880 the object's contents out of the <code>SBData</code>.
882 <p>If you need to delve into several levels of hierarchy, as you can do with summary
883 strings, you can use the method <code>GetValueForExpressionPath()</code>, passing it
884 an expression path just like those you could use for summary strings (one of the differences
885 is that dereferencing a pointer does not occur by prefixing the path with a <code>*</code>,
886 but by calling the <code>Dereference()</code> method on the returned SBValue).
887 If you need to access array slices, you cannot do that (yet) via this method call, and you must
888 use <code>GetChildAtIndex()</code> querying it for the array items one by one.
889 Also, handling custom formats is something you have to deal with on your own.
891 <p>Other than interactively typing a Python script there are two other ways for you
892 to input a Python script as a summary:
895 <li> using the --python-script option to <code>type summary add </code> and typing the script
896 code as an option argument; as in: </ul>
898 <table class="stats" width="620" cellspacing="0">
900 <b>(lldb)</b> type summary add --python-script "height =
901 valobj.GetChildMemberWithName('height').GetValueAsUnsigned(0);width =
902 valobj.GetChildMemberWithName('width').GetValueAsUnsigned(0);
903 return 'Area: %d' % (height*width)" Rectangle<br/>
907 <li> using the <code>--python-function</code> (<code>-F</code>) option to <code>type summary add </code> and giving the name of a
908 Python function with the correct prototype. Most probably, you will define (or have
909 already defined) the function in the interactive interpreter, or somehow
910 loaded it from a file, using the <code>command script import</code> command. LLDB will emit a warning if it is unable to find the function you passed, but will still register the binding.
915 <p>Starting in SVN r222593, Python summary formatters can optionally define a third argument: <code>options</code><br/>
916 This is an object of type lldb.SBTypeSummaryOptions that can be passed into the formatter, allowing for a few customizations of the result.
917 The decision to adopt or not this third argument - and the meaning of options thereof - is within the individual formatters' writer.<br/>
923 <h1 class="postheader">Regular expression typenames</h1>
924 <div class="postcontent">
925 <p>As you noticed, in order to associate the custom
926 summary string to the array types, one must give the
927 array size as part of the typename. This can long become
928 tiresome when using arrays of different sizes, <code>Simple
930 [3]</code>, <code>Simple [9]</code>, <code>Simple
932 <p>If you use the <code>-x</code> option, type names are
933 treated as regular expressions instead of type names.
934 This would let you rephrase the above example
935 for arrays of type <code>Simple [3]</code> as: <br>
937 <table class="stats" width="620" cellspacing="0">
939 <b>(lldb)</b> type summary add --summary-string "${var[].x}"
940 -x "Simple \[[0-9]+\]"
945 <b>(lldb)</b> frame variable<br>
946 (Simple [3]) sarray = [1,4,7]<br>
947 (Simple [2]) sother = [3,6]<br>
948 </code> The above scenario works for <code>Simple [3]</code>
949 as well as for any other array of <code>Simple</code>
951 <p>While this feature is mostly useful for arrays, you
952 could also use regular expressions to catch other type
953 sets grouped by name. However, as regular expression
954 matching is slower than normal name matching, LLDB will
955 first try to match by name in any way it can, and only
956 when this fails, will it resort to regular expression
958 <p>One of the ways LLDB uses this feature internally, is to match
959 the names of STL container classes, regardless of the template
960 arguments provided. The details for this are found at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/source/DataFormatters/FormatManager.cpp">FormatManager.cpp</a></p>
962 <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
963 compliant implementation.
969 <h1 class="postheader">Named summaries</h1>
970 <div class="postcontent">
971 <p>For a given type, there may be different meaningful summary
972 representations. However, currently, only one summary can be associated
973 to a type at each moment. If you need to temporarily override the association
974 for a variable, without changing the summary string for to its type,
975 you can use named summaries.</p>
977 <p>Named summaries work by attaching a name to a summary when creating
978 it. Then, when there is a need to attach the summary to a variable, the
979 <code>frame variable</code> command, supports a <code>--summary</code> option
980 that tells LLDB to use the named summary given instead of the default one.</p>
982 <table class="stats" width="620" cellspacing="0">
984 <b>(lldb)</b> type summary add --summary-string "x=${var.integer}" --name NamedSummary
987 <code> <b>(lldb)</b> frame variable one<br>
988 (i_am_cool) one = int = 3, float = 3.14159, char = 69<br>
989 <b>(lldb)</b> frame variable one --summary NamedSummary<br>
990 (i_am_cool) one = x=3<br>
993 <p>When defining a named summary, binding it to one or more types becomes optional.
994 Even if you bind the named summary to a type, and later change the summary string
995 for that type, the named summary will not be changed by that. You can delete
996 named summaries by using the <code>type summary delete</code> command, as if the
997 summary name was the datatype that the summary is applied to</p>
999 <p>A summary attached to a variable using the </code>--summary</code> option,
1000 has the same semantics that a custom format attached using the <code>-f</code>
1001 option has: it stays attached till you attach a new one, or till you let
1002 your program run again.</p>
1008 <h1 class="postheader">Synthetic children</h1>
1009 <div class="postcontent">
1010 <p>Summaries work well when one is able to navigate through an expression path.
1011 In order for LLDB to do so, appropriate debugging information must be available.</p>
1012 <p>Some types are <i>opaque</i>, i.e. no knowledge of their internals is provided.
1013 When that's the case, expression paths do not work correctly.</p>
1014 <p>In other cases, the internals are available to use in expression paths, but they
1015 do not provide a user-friendly representation of the object's value.</p>
1016 <p>For instance, consider an STL vector, as implemented by the <a href="http://gcc.gnu.org/onlinedocs/libstdc++/">GNU C++ Library</a>:</p>
1018 <b>(lldb)</b> frame variable numbers -T<br/>
1019 (std::vector<int>) numbers = {<br/>
1020 (std::_Vector_base<int, std::allocator<int> >) std::_Vector_base<int, std::allocator<int> > = {<br/>
1021 (std::_Vector_base<int, std::allocator&tl;int> >::_Vector_impl) _M_impl = {<br/>
1022 (int *) _M_start = 0x00000001001008a0<br/>
1023 (int *) _M_finish = 0x00000001001008a8<br/>
1024 (int *) _M_end_of_storage = 0x00000001001008a8<br/>
1025 }<br/>
1026 }<br/>
1029 <p>Here, you can see how the type is implemented, and you can write a summary for that implementation
1030 but that is not going to help you infer what items are actually stored in the vector.</p>
1031 <p>What you would like to see is probably something like:</p>
1033 <b>(lldb)</b> frame variable numbers -T<br/>
1034 (std::vector<int>) numbers = {<br/>
1035 (int) [0] = 1<br/>
1036 (int) [1] = 12<br/>
1037 (int) [2] = 123<br/>
1038 (int) [3] = 1234<br/>
1041 <p>Synthetic children are a way to get that result.</p>
1042 <p>The feature is based upon the idea of providing a new set of children for a variable that replaces the ones
1043 available by default through the debug information. In the example, we can use synthetic children to provide
1044 the vector items as children for the std::vector object.</p>
1045 <p>In order to create synthetic children, you need to provide a Python class that adheres to a given <i>interface</i>
1046 (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
1047 must be implemented by the Python class):</p>
1049 <font color=blue>class</font> SyntheticChildrenProvider:<br/>
1050 <font color=blue>def</font> __init__(self, valobj, internal_dict):<br/>
1051 <i>this call should initialize the Python object using valobj as the variable to provide synthetic children for</i> <br/>
1052 <font color=blue>def</font> num_children(self): <br/>
1053 <i>this call should return the number of children that you want your object to have</i> <br/>
1054 <font color=blue>def</font> get_child_index(self,name): <br/>
1055 <i>this call should return the index of the synthetic child whose name is given as argument</i> <br/>
1056 <font color=blue>def</font> get_child_at_index(self,index): <br/>
1057 <i>this call should return a new LLDB SBValue object representing the child at the index given as argument</i> <br/>
1058 <font color=blue>def</font> update(self): <br/>
1059 <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/>
1060 <font color=blue>def</font> has_children(self): <br/>
1061 <i>this call should return True if this object might have children, and False if this object can be guaranteed not to have children.</i><sup>[2]</sup><br/>
1062 <font color=blue>def</font> get_value(self): <br/>
1063 <i>this call can return an SBValue to be presented as the value of the synthetic value under consideration.</i><sup>[3]</sup><br/>
1066 <sup>[1]</sup> This method is optional. Also, it may optionally choose to return a value (starting with SVN rev153061/LLDB-134). If it returns a value, and that value is <font color=blue><code>True</code></font>, LLDB will be allowed to cache the children and the children count it previously obtained, and will not return to the provider class to ask. If nothing, <font color=blue><code>None</code></font>, or anything other than <font color=blue><code>True</code></font> is returned, LLDB will discard the cached information and ask. Regardless, whenever necessary LLDB will call <code>update</code>.
1068 <sup>[2]</sup> This method is optional (starting with SVN rev166495/LLDB-175). While implementing it in terms of <code>num_children</code> is acceptable, implementors are encouraged to look for optimized coding alternatives whenever reasonable.
1070 <sup>[3]</sup> This method is optional (starting with SVN revision 219330). The SBValue you return here will most likely be a numeric type (int, float, ...) as its value bytes will be used as-if they were the value of the root SBValue proper. As a shortcut for this, you can inherit from lldb.SBSyntheticValueProvider, and just define get_value as other methods are defaulted in the superclass as returning default no-children responses.
1071 <p>If a synthetic child provider supplies a special child named <code>$$dereference$$</code> then it will be used when evaluating <code>opertaor*</code> and <code>operator-></code> in the <code>frame variable</code> command and related SB API functions.</p>
1072 <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. Please, be aware that the code in those files (except bitfield/)
1073 is legacy code and is not maintained.
1074 You may especially want to begin looking at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/synthetic/bitfield">this example</a> to get
1075 a feel for this feature, as it is a very easy and well commented example.</p>
1076 The design pattern consistently used in synthetic providers shipping with LLDB
1077 is to use the <code>__init__</code> to store the SBValue instance as a part of <code>self</code>. The <code>update</code> function is then used
1078 to perform the actual initialization.
1081 <p>Once a synthetic children provider is written, one must load it into LLDB before it can be used.
1082 Currently, one can use the LLDB <code>script</code> command to type Python code interactively,
1083 or use the <code>command script import <i>fileName </i></code> command to load Python code from a Python module
1084 (ordinary rules apply to importing modules this way). A third option is to type the code for
1085 the provider class interactively while adding it.</p>
1087 <p>For example, let's pretend we have a class <code>Foo</code> for which a synthetic children provider class
1088 <code>Foo_Provider</code> is available, in a Python module contained in file <code>~/Foo_Tools.py</code>. The following interaction
1089 sets <code>Foo_Provider</code> as a synthetic children provider in LLDB:</p>
1091 <table class="stats" width="620" cellspacing="0">
1092 <td class="content">
1093 <b>(lldb)</b> command script import ~/Foo_Tools.py<br/>
1094 <b>(lldb)</b> type synthetic add Foo --python-class Foo_Tools.Foo_Provider
1097 <code> <b>(lldb)</b> frame variable a_foo<br/>
1098 (Foo) a_foo = {<br/>
1099 x = 1<br/>
1100 y = "Hello world"<br/>
1104 <p>LLDB has synthetic children providers for a core subset of STL classes, both in the version provided by <a href="http://gcc.gnu.org/libstdc++/">libstdcpp</a> and by <a href="http://libcxx.llvm.org/">libcxx</a>, as well as for several Foundation classes.</p>
1106 <p>Synthetic children extend summary strings by enabling a new special variable: <code>${svar</code>.<br/>
1107 This symbol tells LLDB to refer expression paths to the
1108 synthetic children instead of the real ones. For instance,</p>
1110 <table class="stats" width="620" cellspacing="0">
1111 <td class="content">
1112 <b>(lldb)</b> type summary add --expand -x "std::vector<" --summary-string "${svar%#} items"
1115 <code> <b>(lldb)</b> frame variable numbers<br/>
1116 (std::vector<int>) numbers = 4 items {<br/>
1117 (int) [0] = 1<br/>
1118 (int) [1] = 12<br/>
1119 (int) [2] = 123<br/>
1120 (int) [3] = 1234<br/>
1123 <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
1124 synthetic children. While in summaries it is best to always use <code>${svar</code> to make your intentions clearer, interactive debugging
1125 can benefit from this behavior, as in:
1126 <code> <b>(lldb)</b> frame variable numbers[0] numbers[1]<br/>
1127 (int) numbers[0] = 1<br/>
1128 (int) numbers[1] = 12<br/>
1130 Unlike many other visualization features, however, the access to synthetic children only works when using <code>frame variable</code>, and is
1131 not supported in <code>expression</code>:<br/>
1132 <code> <b>(lldb)</b> expression numbers[0]<br/>
1133 Error [IRForTarget]: Call to a function '_ZNSt33vector<int, std::allocator<int> >ixEm' that is not present in the target<br/>
1134 error: Couldn't convert the expression to DWARF<br/>
1136 The reason for this is that classes might have an overloaded <code><font color="blue">operator</font> []</code>, or other special provisions
1137 and the <code>expression</code> command chooses to ignore synthetic children in the interest of equivalency with code you asked to have compiled from source.
1142 <h1 class="postheader">Filters</h1>
1143 <div class="postcontent">
1144 <p>Filters are a solution to the display of complex classes.
1145 At times, classes have many member variables but not all of these are actually
1146 necessary for the user to see.</p>
1147 <p>A filter will solve this issue by only letting the user see those member
1148 variables he cares about. Of course, the equivalent of a filter can be implemented easily
1149 using synthetic children, but a filter lets you get the job done without having to write
1151 <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
1152 the ones named <code>B</code>, <code>H</code> and <code>Q</code>, you can define a filter:
1153 <table class="stats" width="620" cellspacing="0">
1154 <td class="content">
1155 <b>(lldb)</b> type filter add Foobar --child B --child H --child Q
1158 <code> <b>(lldb)</b> frame variable a_foobar<br/>
1159 (Foobar) a_foobar = {<br/>
1160 (int) B = 1<br/>
1161 (char) H = 'H'<br/>
1162 (std::string) Q = "Hello world"<br/>
1169 <h1 class="postheader">Objective-C dynamic type discovery</h1>
1170 <div class="postcontent">
1171 <p>When doing Objective-C development, you may notice that some of your variables
1172 come out as of type <code>id</code> (for instance, items extracted from <code>NSArray</code>).
1173 By default, LLDB will not show you the real type of the object. it can actually dynamically discover the type of an Objective-C
1174 variable, much like the runtime itself does when invoking a selector. In order
1175 to be shown the result of that discovery that, however, a special option to <code>frame variable</code> or <code>expression</code> is
1176 required: <br/><code>--dynamic-type</code>.</p>
1177 <p><code>--dynamic-type</code> can have one of three values:
1179 <li><code>no-dynamic-values</code>: the default, prevents dynamic type discovery</li>
1180 <li><code>no-run-target</code>: enables dynamic type discovery as long as running
1181 code on the target is not required</li>
1182 <li><code>run-target</code>: enables code execution on the target in order to perform
1183 dynamic type discovery</li>
1187 If you specify a value of either <code>no-run-target</code> or <code>run-target</code>,
1188 LLDB will detect the dynamic type of your variables and show the appropriate formatters
1189 for them. As an example:
1191 <p><table class="stats" width="620" cellspacing="0">
1192 <td class="content">
1193 <b>(lldb)</b> expr @"Hello"
1196 <code>(NSString *) $0 = 0x00000001048000b0 @"Hello"<br/>
1198 <p><table class="stats" width="620" cellspacing="0">
1199 <td class="content">
1200 <b>(lldb)</b> expr -d no-run @"Hello"
1203 <code>(__NSCFString *) $1 = 0x00000001048000b0 @"Hello"<br/>
1206 Because LLDB uses a detection algorithm that does not need to invoke any functions
1207 on the target process, <code>no-run-target</code> is enough for this to work.</p>
1208 As a side note, the summary for NSString shown in the example is built right into LLDB.
1209 It was initially implemented through Python (the code is still available for reference at <a href="http://llvm.org/svn/llvm-project/lldb/trunk/examples/summaries/cocoa/CFString.py">CFString.py</a>).
1210 However, this is out of sync with the current implementation of the NSString formatter (which is a C++ function compiled into the LLDB core).
1216 <h1 class="postheader">Categories</h1>
1217 <div class="postcontent">
1218 <p>Categories are a way to group related formatters. For instance, LLDB itself groups
1219 the formatters for the libstdc++ types in a category named <code>gnu-libstdc++</code>.
1220 Basically, categories act like containers in which to store formatters for a same library
1222 <p>By default, several categories are created in LLDB:
1224 <li><code>default</code>: this is the category where every formatter ends up, unless another category is specified
1225 <li><code>objc</code>: formatters for basic and common Objective-C types that do not specifically depend on Mac OS X
1226 <li><code>gnu-libstdc++</code>: formatters for std::string, std::vector, std::list and std::map as implemented by libstdcpp
1227 <li><code>libcxx</code>: formatters for std::string, std::vector, std::list and std::map as implemented by <a href="http://libcxx.llvm.org/">libcxx</a>
1228 <li><code>system</code>: truly basic types for which a formatter is required
1229 <li><a href="https://developer.apple.com/library/mac/#documentation/Cocoa/Reference/Foundation/ObjC_classic/_index.html#//apple_ref/doc/uid/20001091"><code>AppKit</code></a>: Cocoa classes
1230 <li><a href="https://developer.apple.com/corefoundation/"><code>CoreFoundation</code></a>: CF classes
1231 <li><a href="https://developer.apple.com/library/mac/#documentation/CoreGraphics/Reference/CoreGraphicsConstantsRef/Reference/reference.html"><code>CoreGraphics</code></a>: CG classes
1232 <li><a href="http://developer.apple.com/library/mac/#documentation/Carbon/reference/CoreServicesReferenceCollection/_index.html"><code>CoreServices</code></a>: CS classes
1233 <li><code>VectorTypes</code>: compact display for several vector types
1235 If you want to use a custom category for your formatters, all the <code>type ... add</code>
1236 provide a <code>--category</code> (<code>-w</code>) option, that names the category to add the formatter to.
1237 To delete the formatter, you then have to specify the correct category.</p>
1238 <p>Categories can be in one of two states: enabled and disabled. A category is initially disabled,
1239 and can be enabled using the <code>type category enable</code> command. To disable an enabled category,
1240 the command to use is <code>type category disable</code>.
1241 <p>The order in which categories are enabled or disabled
1242 is significant, in that LLDB uses that order when looking for formatters. Therefore, when you enable a category, it becomes
1243 the second one to be searched (after <code>default</code>, which always stays on top of the list). The default categories are enabled in such a way that the search order is:
1247 <li>CoreFoundation</li>
1249 <li>CoreServices</li>
1250 <li>CoreGraphics</li>
1251 <li>gnu-libstdc++</li>
1253 <li>VectorTypes</li>
1256 <p>As said, <code>gnu-libstdc++</code> and <code>libcxx</code> contain formatters for C++ STL
1257 data types. <code>system</code> contains formatters for <code>char*</code> and <code>char[]</code>, which reflect the behavior
1258 of older versions of LLDB which had built-in formatters for these types. Because now these are formatters, you can even
1259 replace them with your own if so you wish.</p>
1260 <p>There is no special command to create a category. When you place a formatter in a category, if that category does not
1261 exist, it is automatically created. For instance,</p>
1262 <p><table class="stats" width="620" cellspacing="0">
1263 <td class="content">
1264 <b>(lldb)</b> type summary add Foobar --summary-string "a foobar" --category newcategory
1267 automatically creates a (disabled) category named newcategory.</p>
1268 <p>Another way to create a new (empty) category, is to enable it, as in:</p>
1269 <p><table class="stats" width="620" cellspacing="0">
1270 <td class="content">
1271 <b>(lldb)</b> type category enable newcategory
1274 <p>However, in this case LLDB warns you that enabling an empty category has no effect. If you add formatters to the
1275 category after enabling it, they will be honored. But an empty category <i>per se</i> does not change the way any
1276 type is displayed. The reason the debugger warns you is that enabling an empty category might be a typo, and you
1277 effectively wanted to enable a similarly-named but not-empty category.</p>
1282 <h1 class="postheader">Finding formatters 101</h1>
1283 <div class="postcontent">
1284 <p>Searching for a formatter
1285 (including formats, starting in SVN rev <a href="http://llvm.org/viewvc/llvm-project?view=revision&revision=192217">r192217</a>)
1286 given a variable goes through
1287 a rather intricate set of rules. Namely, what happens is that LLDB
1288 starts looking in each enabled category, according to the order in which
1289 they were enabled (latest enabled first). In each category, LLDB does
1292 <li>If there is a formatter for the type of the variable,
1294 <li>If this object is a pointer, and there is a formatter
1295 for the pointee type that does not skip pointers, use
1297 <li>If this object is a reference, and there is a
1298 formatter for the referred type that does not skip
1299 references, use it</li>
1300 <li>If this object is an Objective-C class and dynamic types are enabled,
1301 look for a formatter for the dynamic type of the object. If dynamic types are disabled,
1302 or the search failed, look for a formatter for the declared type of the object</li>
1303 <li>If this object's type is a typedef, go through
1304 typedef hierarchy (LLDB might not be able to do this if
1305 the compiler has not emitted enough information. If the
1306 required information to traverse typedef hierarchies is
1307 missing, type cascading will not work. The
1308 <a href="http://clang.llvm.org/">clang compiler</a>,
1309 part of the LLVM project, emits the correct debugging
1310 information for LLDB to cascade). If at any level of the hierarchy
1311 there is a valid formatter that can cascade, use it.</li>
1312 <li>If everything has failed, repeat the above search,
1313 looking for regular expressions instead of exact
1316 <p>If any of those attempts returned a valid formatter to be used,
1317 that one is used, and the search is terminated (without going to look
1318 in other categories). If nothing was found in the current category, the next
1319 enabled category is scanned according to the same algorithm. If there are no
1320 more enabled categories, the search has failed.</p>
1321 <p><font color=red>Warning</font>: previous versions of LLDB defined cascading to mean
1322 not only going through typedef chains, but also through inheritance chains.
1323 This feature has been removed since it significantly degrades performance.
1324 You need to set up your formatters for every type in inheritance chains to which
1325 you want the formatter to apply.</p>
projects / FreeBSD / FreeBSD.git / blob