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"> 3 <head> 4 <meta http-equiv="Content-Type" content="text/html; 5 charset=ISO-8859-1"> 6 <link href="style.css" rel="stylesheet" type="text/css"> 7 <title>LLDB Data Formatters</title> 8 </head> 9 <body> 10 <div class="www_title"> The <strong>LLDB</strong> Debugger </div> 11 <div id="container"> 12 <div id="content"> 13 <!--#include virtual="sidebar.incl"--> 14 <div id="middle"> 15 <div class="post"> 16 <h1 class="postheader">Variable display</h1> 17 <div class="postcontent"> 18 19 <p>LLDB has a data formatters subsystem that allows users to define custom display options for their variables.</p> 20 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> 25 26 <p> <code> <b>(lldb)</b> frame variable<br> 27 (uint8_t) x = 'a'<br> 28 (intptr_t) y = 124752287<br> 29 </code> </p> 30 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> 36 </p> 37 38 <p>Using it you can change your visualization to look like this: </p> 39 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> 43 </code> </p> 44 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> 50 51 <p>To reflect this, the <b>type</b> command has four 52 subcommands (plus one specific for <i>categories</i>):<br> 53 </p> 54 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 60 61 <p>These commands are meant to bind printing options to 62 types. When variables are printed, LLDB will first check 63 if custom printing options have been associated to a 64 variable's type and, if so, use them instead of picking 65 the default choices.<br> 66 </p> 67 68 <p>Each of the commands has four subcommands available:<br> 69 </p> 70 <p><code>add</code>: associates a new printing option to one 71 or more types</p> 72 <p><code>delete</code>: deletes an existing association</p> 73 <p><code>list</code>: provides a listing of all 74 associations</p> 75 <p><code>clear</code>: deletes all associations</p> 76 </div> 77 </div> 78 79 <div class="post"> 80 <h1 class="postheader">type format</h1> 81 <div class="postcontent"> 82 83 <p>Type formats enable you to quickly override the default 84 format for displaying primitive types (the usual basic 85 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> 86 87 <p>If for some reason you want all <code>int</code> 88 variables in your program to print out as hex, you can add 89 a format to the <code>int</code> type.<br></p> 90 91 <p>This is done by typing 92 <table class="stats" width="620" cellspacing="0"> 93 <td class="content"> 94 <b>(lldb)</b> type format add --format hex int 95 </td> 96 <table> 97 at the LLDB command line.</p> 98 99 <p>The <code>--format</code> (which you can shorten to <code>-f</code>) option accepts a <a 100 href="#formatstable">format name</a>. Then, you provide one or more 101 types to which you want the new format applied.</p> 102 103 <p>A frequent scenario is that your program has a <code>typedef</code> 104 for a numeric type that you know represents something 105 that must be printed in a certain way. Again, you can 106 add a format just to that typedef by using <code>type 107 format add</code> with the name alias.</p> 108 109 <p>But things can quickly get hierarchical. Let's say you 110 have a situation like the following:</p> 111 112 <p><code><font color="blue">typedef int</font> A;<br> 113 <font color="blue">typedef</font> A B;<br> 114 <font color="blue">typedef</font> B C;<br> 115 <font color="blue">typedef</font> C D;<br> 116 </code></p> 117 118 <p>and you want to show all <code>A</code>'s as hex, all 119 <code>C'</code>s as byte arrays and leave the defaults 120 untouched for other types (albeit its contrived look, the example is far 121 from unrealistic in large software systems).</p> 122 123 <p>If you simply type <br> 124 <table class="stats" width="620" cellspacing="0"> 125 <td class="content"> 126 <b>(lldb)</b> type format add -f hex A<br> 127 <b>(lldb)</b> type format add -f uint8_t[] C 128 </td> 129 <table> 130 <br> 131 values of type <code>B</code> will be shown as hex 132 and values of type <code>D</code> as byte arrays, as in:</p> 133 134 <p> <code> 135 <b>(lldb)</b> frame variable -T<br/> 136 (A) a = 0x00000001<br/> 137 (B) b = 0x00000002<br/> 138 (C) c = {0x03 0x00 0x00 0x00}<br/> 139 (D) d = {0x04 0x00 0x00 0x00}<br/> 140 </code> </p> 141 142 <p>This is because by default LLDB <i>cascades</i> 143 formats through typedef chains. In order to avoid that 144 you can use the option <code>-C no</code> to prevent 145 cascading, thus making the two commands required to 146 achieve your goal:<br> 147 <table class="stats" width="620" cellspacing="0"> 148 <td class="content"> 149 <b>(lldb)</b> type format add -C no -f hex A<br> 150 <b>(lldb)</b> type format add -C no -f uint8_t[] C 151 </td> 152 <table> 153 154 <p>which provides the desired output:</p> 155 <p> <code> 156 <b>(lldb)</b> frame variable -T<br/> 157 (A) a = 0x00000001<br/> 158 (B) b = 2<br/> 159 (C) c = {0x03 0x00 0x00 0x00}<br/> 160 (D) d = 4<br/> 161 </code> </p> 162 163 <p>Two additional options that you will want to look at 164 are <code>--skip-pointers</code> (<code>-p</code>) and <code>--skip-references</code> (<code>-r</code>). These two 165 options prevent LLDB from applying a format for type <code>T</code> 166 to values of type <code>T*</code> and <code>T&</code> 167 respectively.</p> 168 169 <p> <code> <b>(lldb)</b> type format add -f float32[] 170 int<br> 171 <b>(lldb)</b> frame variable pointer *pointer -T<br> 172 (int *) pointer = {1.46991e-39 1.4013e-45}<br> 173 (int) *pointer = {1.53302e-42}<br> 174 <b>(lldb)</b> type format add -f float32[] int -p<br> 175 <b>(lldb)</b> frame variable pointer *pointer -T<br> 176 (int *) pointer = 0x0000000100100180<br> 177 (int) *pointer = {1.53302e-42}<br> 178 </code> </p> 179 180 <p>While they can be applied to pointers and references, formats will make no attempt 181 to dereference the pointer and extract the value before applying the format, which means you 182 are effectively formatting the address stored in the pointer rather than the pointee value. 183 For this reason, you may want to use the <code>-p</code> option when defining formats.</p> 184 185 <p>If you need to delete a custom format simply type <code>type 186 format delete</code> followed by the name of the type 187 to which the format applies.Even if you 188 defined the same format for multiple types on the same command, 189 <code>type format delete</code> will only remove the format for 190 the type name passed as argument.<br> 191 </p> 192 <p> 193 To delete ALL formats, use 194 <code>type format clear</code>. To see all the formats 195 defined, use <code>type format list</code>.</p> 196 197 <p>If all you need to do, however, is display one variable 198 in a custom format, while leaving the others of the same 199 type untouched, you can simply type:<br> 200 <br> 201 <table class="stats" width="620" cellspacing="0"> 202 <td class="content"> 203 <b>(lldb)</b> frame variable counter -f hex 204 </td> 205 <table> 206 207 <p>This has the effect of displaying the value of <code>counter</code> 208 as an hexadecimal number, and will keep showing it this 209 way until you either pick a different format or till you 210 let your program run again.</p> 211 212 <p>Finally, this is a list of formatting options available 213 out of 214 which you can pick:</p><a name="formatstable"></a> 215 <table border="1"> 216 <tbody> 217 <tr valign="top"> 218 <td width="23%"><b>Format name</b></td> 219 <td><b>Abbreviation</b></td> 220 <td><b>Description</b></td> 221 </tr> 222 <tr valign="top"> 223 <td><b>default</b></td> 224 <td><br> 225 </td> 226 <td>the default LLDB algorithm is used to pick a 227 format</td> 228 </tr> 229 <tr valign="top"> 230 <td><b>boolean</b></td> 231 <td>B</td> 232 <td>show this as a true/false boolean, using the 233 customary rule that 0 is false and everything else 234 is true</td> 235 </tr> 236 <tr valign="top"> 237 <td><b>binary</b></td> 238 <td>b</td> 239 <td>show this as a sequence of bits</td> 240 </tr> 241 <tr valign="top"> 242 <td><b>bytes</b></td> 243 <td>y</td> 244 <td>show the bytes one after the other<br> 245 e.g. <code>(int) s.x = 07 00 00 00</code></td> 246 </tr> 247 <tr valign="top"> 248 <td><b>bytes with ASCII</b></td> 249 <td>Y</td> 250 <td>show the bytes, but try to display them as ASCII 251 characters as well<br> 252 e.g. <code>(int *) c.sp.x = 50 f8 bf 5f ff 7f 00 253 00 P.._....</code></td> 254 </tr> 255 <tr valign="top"> 256 <td><b>character</b></td> 257 <td>c</td> 258 <td>show the bytes as ASCII characters<br> 259 e.g. <code>(int *) c.sp.x = 260 P\xf8\xbf_\xff\x7f\0\0</code></td> 261 </tr> 262 <tr valign="top"> 263 <td><b>printable character</b></td> 264 <td>C</td> 265 <td>show the bytes as printable ASCII 266 characters<br> 267 e.g. <code>(int *) c.sp.x = P.._....</code></td> 268 </tr> 269 <tr valign="top"> 270 <td><b>complex float</b></td> 271 <td>F</td> 272 <td>interpret this value as the real and imaginary 273 part of a complex floating-point number<br> 274 e.g. <code>(int *) c.sp.x = 2.76658e+19 + 275 4.59163e-41i</code></td> 276 </tr> 277 <tr valign="top"> 278 <td><b>c-string</b></td> 279 <td>s</td> 280 <td>show this as a 0-terminated C string</td> 281 </tr> 282 <tr valign="top"> 283 <td><b>decimal</b></td> 284 <td>i</td> 285 <td>show this as a signed integer number (this does 286 not perform a cast, it simply shows the bytes as 287 an integer with sign)</td> 288 </tr> 289 <tr valign="top"> 290 <td><b>enumeration</b></td> 291 <td>E</td> 292 <td>show this as an enumeration, printing the 293 value's name if available or the integer value 294 otherwise<br> 295 e.g. <code>(enum enumType) val_type = eValue2</code></td> 296 </tr> 297 <tr valign="top"> 298 <td><b>hex</b></td> 299 <td>x</td> 300 <td>show this as in hexadecimal notation (this does 301 not perform a cast, it simply shows the bytes as 302 hex)</td> 303 </tr> 304 <tr valign="top"> 305 <td><b>float</b></td> 306 <td>f</td> 307 <td>show this as a floating-point number (this does 308 not perform a cast, it simply interprets the bytes 309 as an IEEE754 floating-point value)</td> 310 </tr> 311 <tr valign="top"> 312 <td><b>octal</b></td> 313 <td>o</td> 314 <td>show this in octal notation</td> 315 </tr> 316 <tr valign="top"> 317 <td><b>OSType</b></td> 318 <td>O</td> 319 <td>show this as a MacOS OSType<br> 320 e.g. <code>(float) x = '\n\x1f\xd7\n'</code></td> 321 </tr> 322 <tr valign="top"> 323 <td><b>unicode16</b></td> 324 <td>U</td> 325 <td>show this as UTF-16 characters<br> 326 e.g. <code>(float) x = 0xd70a 0x411f</code></td> 327 </tr> 328 <tr valign="top"> 329 <td><b>unicode32</b></td> 330 <td><br> 331 </td> 332 <td>show this as UTF-32 characters<br> 333 e.g. <code>(float) x = 0x411fd70a</code></td> 334 </tr> 335 <tr valign="top"> 336 <td><b>unsigned decimal</b></td> 337 <td>u</td> 338 <td>show this as an unsigned integer number (this 339 does not perform a cast, it simply shows the bytes 340 as unsigned integer)</td> 341 </tr> 342 <tr valign="top"> 343 <td><b>pointer</b></td> 344 <td>p</td> 345 <td>show this as a native pointer (unless this is 346 really a pointer, the resulting address will 347 probably be invalid)</td> 348 </tr> 349 <tr valign="top"> 350 <td><b>char[]</b></td> 351 <td><br> 352 </td> 353 <td>show this as an array of characters<br> 354 e.g. <code>(char) *c.sp.z = {X}</code></td> 355 </tr> 356 <tr valign="top"> 357 <td><b>int8_t[], uint8_t[]<br> 358 int16_t[], uint16_t[]<br> 359 int32_t[], uint32_t[]<br> 360 int64_t[], uint64_t[]<br> 361 uint128_t[]</b></td> 362 <td><br> 363 </td> 364 <td>show this as an array of the corresponding 365 integer type<br> 366 e.g.<br> 367 <code>(int) x = {1 0 0 0}</code> (with uint8_t[])<br> 368 <code>(int) y = {0x00000001}</code> (with uint32_t[])</td> 369 </tr> 370 <tr valign="top"> 371 <td><b>float32[], float64[]</b></td> 372 <td><br> 373 </td> 374 <td>show this as an array of the corresponding 375 floating-point type<br> 376 e.g. <code>(int *) pointer = {1.46991e-39 377 1.4013e-45}</code></td> 378 </tr> 379 <tr valign="top"> 380 <td><b>complex integer</b></td> 381 <td>I</td> 382 <td>interpret this value as the real and imaginary 383 part of a complex integer number<br> 384 e.g. <code>(int *) pointer = 1048960 + 1i</code></td> 385 </tr> 386 <tr valign="top"> 387 <td><b>character array</b></td> 388 <td>a</td> 389 <td>show this as a character array<br> 390 e.g. <code>(int *) pointer = 391 \x80\x01\x10\0\x01\0\0\0</code></td> 392 </tr> 393 </tbody> 394 </table> 395 </div> 396 </div> 397 398 <div class="post"> 399 <h1 class="postheader">type summary</h1> 400 <div class="postcontent"> 401 <p>Type formats work by showing a different kind of display for 402 the value of a variable. However, they only work for basic types. 403 When you want to display a class or struct in a custom format, you 404 cannot do that using formats.</p> 405 <p>A different feature, type summaries, works by extracting 406 information from classes, structures, ... (<i>aggregate types</i>) 407 and arranging it in a user-defined format, as in the following example:</p> 408 <p> <i>before adding a summary...</i><br> 409 <code> <b>(lldb)</b> frame variable -T one<br> 410 (i_am_cool) one = {<br> 411 (int) x = 3<br> 412 (float) y = 3.14159<br> 413 (char) z = 'E'<br> 414 }<br> 415 </code> <br> 416 <i>after adding a summary...</i><br> 417 <code> <b>(lldb)</b> frame variable one<br> 418 (i_am_cool) one = int = 3, float = 3.14159, char = 69<br> 419 </code> </p> 420 421 <p>There are two ways to use type summaries: the first one is to bind a <i> 422 summary string</i> to the type; the second is to write a Python script that returns 423 the string to be used as summary. Both options are enabled by the <code>type summary add</code> 424 command.</p> 425 <p>The command to obtain the output shown in the example is:</p> 426 <table class="stats" width="620" cellspacing="0"> 427 <td class="content"> 428 <b>(lldb)</b> type summary add --summary-string "int = ${var.x}, float = ${var.y}, char = ${var.z%u}" i_am_cool 429 </td> 430 <table> 431 432 <p>Initially, we will focus on summary strings, and then describe the Python binding 433 mechanism.</p> 434 435 </div> 436 </div> 437 <div class="post"> 438 <h1 class="postheader">Summary Strings</h1> 439 <div class="postcontent"> 440 <p>Summary strings are written using a simple control language, exemplified by the snippet above. 441 A summary string contains a sequence of tokens that are processed by LLDB to generate the summary.</p> 442 443 <p>Summary strings can contain plain text, control characters and 444 special variables that have access to information about 445 the current object and the overall program state.</p> 446 <p>Plain text is any sequence of characters that doesn't contain a <code><b>'{'</b></code>, 447 <code><b>'}'</b></code>, <code><b>'$'</b></code>, or <code><b>'\'</b></code> 448 character, which are the syntax control characters.</p> 449 <p>The special variables are found in between a <code><b>"${"</b></code> 450 prefix, and end with a <code><b>"}"</b></code> suffix. Variables can be a simple name 451 or they can refer to complex objects that have subitems themselves. 452 In other words, a variable looks like <code>"<b>${object}</b>"</code> or 453 <code>"<b>${object.child.otherchild}</b>"</code>. A variable can also be prefixed or 454 suffixed with other symbols meant to change the way its value is handled. An example is 455 <code>"<b>${*var.int_pointer[0-3]}</b>".</code></p> 456 <p>Basically, the syntax is the same one described <a 457 href="formats.html">Frame and Thread Formatting</a> 458 plus additional symbols specific for summary strings. The main of them is <code>${var</code>, 459 which is used refer to the variable that a summary is being created for.</p> 460 <p>The simplest thing you can do is grab a member variable 461 of a class or structure by typing its <i>expression 462 path</i>. In the previous example, the expression path 463 for the field <code>float y</code> is simply <code>.y</code>. 464 Thus, to ask the summary string to display <code>y</code> 465 you would type <code>${var.y}</code>.</p> 466 <p>If you have code like the following: <br> 467 <code> <font color="blue">struct</font> A {<br> 468 <font color="blue">int</font> x;<br> 469 <font color="blue">int</font> y;<br> 470 };<br> 471 <font color="blue">struct</font> B {<br> 472 A x;<br> 473 A y;<br> 474 <font color="blue">int</font> *z;<br> 475 };<br> 476 </code> the expression path for the <code>y</code> 477 member of the <code>x</code> member of an object of 478 type <code>B</code> would be <code>.x.y</code> and you 479 would type <code>${var.x.y}</code> to display it in a 480 summary string for type <code>B</code>. </p> 481 <p>By default, a summary defined for type <code>T</code>, also works for types 482 <code>T*</code> and <code>T&</code> (you can disable this behavior if desired). 483 For this reason, expression paths do not differentiate between <code>.</code> 484 and <code>-></code>, and the above expression path <code>.x.y</code> 485 would be just as good if you were displaying a <code>B*</code>, 486 or even if the actual definition of <code>B</code> 487 were: <code><br> 488 <font color="blue">struct</font> B {<br> 489 A *x;<br> 490 A y;<br> 491 <font color="blue">int</font> *z;<br> 492 };<br> 493 </code> </p> 494 <p>This is unlike the behavior of <code>frame variable</code> 495 which, on the contrary, will enforce the distinction. As 496 hinted above, the rationale for this choice is that 497 waiving this distinction enables you to write a summary 498 string once for type <code>T</code> and use it for both 499 <code>T</code> and <code>T*</code> instances. As a 500 summary string is mostly about extracting nested 501 members' information, a pointer to an object is just as 502 good as the object itself for the purpose.</p> 503 <p>If you need to access the value of the integer pointed to by <code>B::z</code>, you 504 cannot simply say <code>${var.z}</code> because that symbol refers to the pointer <code>z</code>. 505 In order to dereference it and get the pointed value, you should say <code>${*var.z}</code>. The <code>${*var</code> 506 tells LLDB to get the object that the expression paths leads to, and then dereference it. In this example is it 507 equivalent to <code>*(bObject.z)</code> in C/C++ syntax. Because <code>.</code> and <code>-></code> operators can both be 508 used, there is no need to have dereferences in the middle of an expression path (e.g. you do not need to type 509 <code>${*(var.x).x})</code> to read <code>A::x</code> as contained in <code>*(B::x)</code>. To achieve that effect 510 you can simply write <code>${var.x->x}</code>, or even <code>${var.x.x}</code>. The <code>*</code> operator only binds 511 to the result of the whole expression path, rather than piecewise, and there is no way to use parentheses to change 512 that behavior.</p> 513 <p>Of course, a summary string can contain more than one <code>${var</code> specifier, 514 and can use <code>${var</code> and <code>${*var</code> specifiers together.</p> 515 </div> 516 </div> 517 <div class="post"> 518 <h1 class="postheader">Formatting summary elements</h1> 519 <div class="postcontent"> 520 <p>An expression path can include formatting codes. 521 Much like the type formats discussed previously, you can also customize 522 the way variables are displayed in summary strings, regardless of the format they have 523 applied to their types. To do that, you can use <code>%<i>format</i></code> inside an expression path, 524 as in <code>${var.x->x%u}</code>, which would display the value of <code>x</code> as an unsigned integer. 525 526 <p>You can also use some other special format markers, not available 527 for formats themselves, but which carry a special meaning when used in this 528 context:</p> 529 530 <table border="1"> 531 <tbody> 532 <tr valign="top"> 533 <td width="23%"><b>Symbol</b></td> 534 <td><b>Description</b></td> 535 </tr> 536 <tr valign="top"> 537 <td><b>%S</b></td> 538 <td>Use this object's summary (the default for aggregate types)</td> 539 </tr> 540 <tr valign="top"> 541 <td><b>%V</b></td> 542 <td>Use this object's value (the default for non-aggregate types)</td> 543 </tr> 544 <tr valign="top"> 545 <td><b>%@</b></td> 546 <td>Use a language-runtime specific description (for C++ this does nothing, 547 for Objective-C it calls the NSPrintForDebugger API)</td> 548 </tr> 549 <tr valign="top"> 550 <td><b>%L</b></td> 551 <td>Use this object's location (memory address, register name, ...)</td> 552 </tr> 553 <tr valign="top"> 554 <td><b>%#</b></td> 555 <td>Use the count of the children of this object</td> 556 </tr> 557 <tr valign="top"> 558 <td><b>%T</b></td> 559 <td>Use this object's datatype name</td> 560 </tr> 561 </tbody> 562 </table> 563 564 <p>Option <code>--inline-children</code> (<code>-c</code>) to <code>type summary add</code> 565 tells LLDB not to look for a summary string, but instead 566 to just print a listing of all the object's children on 567 one line.</p> 568 <p> As an example, given a type <code>pair</code>: 569 <code> <br> 570 <b>(lldb)</b> frame variable --show-types a_pair<br> 571 (pair) a_pair = {<br> 572 (int) first = 1;<br/> 573 (int) second = 2;<br/> 574 }<br> 575 </code><br> 576 If one types the following commands: 577 <table class="stats" width="620" cellspacing="0"> 578 <td class="content"> 579 <b>(lldb)</b> type summary add --inline-children pair<br> 580 </td> 581 <table> 582 the output becomes: <br><code> 583 584 <b>(lldb)</b> frame variable a_pair<br> 585 (pair) a_pair = (first=1, second=2)<br> 586 </code> </p> 587 588 Of course, one can obtain the same effect by typing 589 <table class="stats" width="620" cellspacing="0"> 590 <td class="content"> 591 <b>(lldb)</b> type summary add pair --summary-string "(first=${var.first}, second=${var.second})"<br> 592 </td> 593 <table> 594 595 While the final result is the same, using <code>--inline-children</code> can often save time. If one does not need to 596 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: 597 <br><code> 598 599 <b>(lldb)</b> frame variable a_pair<br> 600 (pair) a_pair = (1, 2)<br> 601 </code> </p> 602 603 which is of course the same as 604 typing 605 <table class="stats" width="620" cellspacing="0"> 606 <td class="content"> 607 <b>(lldb)</b> type summary add pair --summary-string "(${var.first}, ${var.second})"<br> 608 </td> 609 <table> 610 </div> 611 </div> 612 <div class="post"> 613 <h1 class="postheader">Bitfields and array syntax</h1> 614 <div class="postcontent"> 615 <p>Sometimes, a basic type's value actually represents 616 several different values packed together in a bitfield.<br/> 617 With the classical view, there is no way to look at 618 them. Hexadecimal display can help, but if the bits 619 actually span nibble boundaries, the help is limited.<br/> 620 Binary view would show it all without ambiguity, but is 621 often too detailed and hard to read for real-life 622 scenarios. 623 <p> 624 To cope with the issue, LLDB supports native 625 bitfield formatting in summary strings. If your 626 expression paths leads to a so-called <i>scalar type</i> 627 (the usual int, float, char, double, short, long, long 628 long, double, long double and unsigned variants), you 629 can ask LLDB to only grab some bits out of the value and 630 display them in any format you like. If you only need one bit 631 you can use the <code>[</code><i>n</i><code>]</code>, just like 632 indexing an array. To extract multiple bits, you can use 633 a slice-like syntax: <code>[</code><i>n</i>-<i>m</i><code>]</code>, e.g. <br><p> 634 <code> <b>(lldb)</b> frame variable float_point<br> 635 (float) float_point = -3.14159<br> </code> 636 <table class="stats" width="620" cellspacing="0"> 637 <td class="content"> 638 <b>(lldb)</b> type summary add --summary-string "Sign: ${var[31]%B} 639 Exponent: ${var[30-23]%x} Mantissa: ${var[0-22]%u}" 640 float 641 </td> 642 </table><br></code> 643 644 <code> 645 <b>(lldb)</b> frame variable float_point<br> 646 (float) float_point = -3.14159 Sign: true Exponent: 647 0x00000080 Mantissa: 4788184<br> 648 </code> In this example, LLDB shows the internal 649 representation of a <code>float</code> variable by 650 extracting bitfields out of a float object.</p> 651 652 <p> When typing a range, the extremes <i>n</i> and <i>m</i> are always 653 included, and the order of the indices is irrelevant. </p> 654 655 <p>LLDB also allows to use a similar syntax to display 656 array members inside a summary string. For instance, you 657 may want to display all arrays of a given type using a 658 more compact notation than the default, and then just 659 delve into individual array members that prove 660 interesting to your debugging task. You can tell 661 LLDB to format arrays in special ways, possibly 662 independent of the way the array members' datatype is formatted. <br> 663 e.g. <br> 664 <code> <b>(lldb)</b> frame variable sarray<br> 665 (Simple [3]) sarray = {<br> 666 [0] = {<br> 667 x = 1<br> 668 y = 2<br> 669 z = '\x03'<br> 670 }<br> 671 [1] = {<br> 672 x = 4<br> 673 y = 5<br> 674 z = '\x06'<br> 675 }<br> 676 [2] = {<br> 677 x = 7<br> 678 y = 8<br> 679 z = '\t'<br> 680 }<br> 681 }<br></code> 682 683 <table class="stats" width="620" cellspacing="0"> 684 <td class="content"> 685 <b>(lldb)</b> type summary add --summary-string "${var[].x}" "Simple 686 [3]" 687 </td> 688 <table><br> 689 690 <code> 691 <b>(lldb)</b> frame variable sarray<br> 692 (Simple [3]) sarray = [1,4,7]<br></code></p> 693 694 <p>The <code>[]</code> symbol amounts to: <i>if <code>var</code> 695 is an array and I know its size, apply this summary 696 string to every element of the array</i>. Here, we are 697 asking LLDB to display <code>.x</code> for every 698 element of the array, and in fact this is what happens. 699 If you find some of those integers anomalous, you can 700 then inspect that one item in greater detail, without 701 the array format getting in the way: <br> 702 <code> <b>(lldb)</b> frame variable sarray[1]<br> 703 (Simple) sarray[1] = {<br> 704 x = 4<br> 705 y = 5<br> 706 z = '\x06'<br> 707 }<br> 708 </code> </p> 709 <p>You can also ask LLDB to only print a subset of the 710 array range by using the same syntax used to extract bit 711 for bitfields: 712 <table class="stats" width="620" cellspacing="0"> 713 <td class="content"> 714 <b>(lldb)</b> type summary add --summary-string "${var[1-2].x}" "Simple 715 [3]" 716 </td> 717 <table><br> 718 <code> 719 <b>(lldb)</b> frame variable sarray<br> 720 (Simple [3]) sarray = [4,7]<br></code></p> 721 722 <p>If you are dealing with a pointer that you know is an array, you can use this 723 syntax to display the elements contained in the pointed array instead of just 724 the pointer value. However, because pointers have no notion of their size, the 725 empty brackets <code>[]</code> operator does not work, and you must explicitly provide 726 higher and lower bounds.</p> 727 728 <p>In general, LLDB needs the square brackets operator <code>[]</code> in 729 order to handle arrays and pointers correctly, and for pointers it also 730 needs a range. However, a few special cases are defined to make your life easier: 731 <ul> 732 <li>you can print a 0-terminated string (<i>C-string</i>) using the %s format, 733 omitting square brackets, as in: 734 <table class="stats" width="620" cellspacing="0"> 735 <td class="content"> 736 <b>(lldb)</b> type summary add --summary-string "${var%s}" "char *" 737 </td> 738 <table> 739 <p> 740 This syntax works for <code>char*</code> as well as for <code>char[]</code> 741 because LLDB can rely on the final <code>\0</code> terminator to know when the string 742 has ended.</p> 743 LLDB has default summary strings for <code>char*</code> and <code>char[]</code> that use 744 this special case. On debugger startup, the following are defined automatically: 745 <table class="stats" width="620" cellspacing="0"> 746 <td class="content"> 747 <b>(lldb)</b> type summary add --summary-string "${var%s}" "char *"<br/> 748 <b>(lldb)</b> type summary add --summary-string "${var%s}" -x "char \[[0-9]+]"<br/> 749 </td> 750 <table> 751 </li> 752 </ul> 753 <ul> 754 755 <li>any of the array formats (<code>int8_t[]</code>, 756 <code>float32{}</code>, ...), and the <code>y</code>, <code>Y</code> 757 and <code>a</code> formats 758 work to print an array of a non-aggregate 759 type, even if square brackets are omitted. 760 <table class="stats" width="620" cellspacing="0"> 761 <td class="content"> 762 <b>(lldb)</b> type summary add --summary-string "${var%int32_t[]}" "int [10]" 763 </td> 764 <table> 765 766 </ul> 767 This feature, however, is not enabled for pointers because there is no 768 way for LLDB to detect the end of the pointed data. 769 <br> 770 This also does not work for other formats (e.g. <code>boolean</code>), and you must 771 specify the square brackets operator to get the expected output. 772 </p> 773 </div> 774 </div> 775 776 <div class="post"> 777 <h1 class="postheader">Python scripting</h1> 778 <div class="postcontent"> 779 780 <p>Most of the times, summary strings prove good enough for the job of summarizing 781 the contents of a variable. However, as soon as you need to do more than picking 782 some values and rearranging them for display, summary strings stop being an 783 effective tool. This is because summary strings lack the power to actually perform 784 any kind of computation on the value of variables.</p> 785 <p>To solve this issue, you can bind some Python scripting code as a summary for 786 your datatype, and that script has the ability to both extract children variables 787 as the summary strings do and to perform active computation on the extracted 788 values. As a small example, let's say we have a Rectangle class:</p> 789 790 <code> 791 <font color="blue">class</font> Rectangle<br/> 792 {<br/> 793 <font color="blue">private</font>:<br/> 794 <font color="blue">int</font> height;<br/> 795 <font color="blue">int</font> width;<br/> 796 <font color="blue">public</font>:<br/> 797 Rectangle() : height(3), width(5) {}<br/> 798 Rectangle(<font color="blue">int</font> H) : height(H), width(H*2-1) {}<br/> 799 Rectangle(<font color="blue">int</font> H, <font color="blue">int</font> W) : height(H), width(W) {}<br/> 800 801 <font color="blue">int</font> GetHeight() { return height; }<br/> 802 <font color="blue">int</font> GetWidth() { return width; }<br/> 803 804 };<br/> 805 </code> 806 807 <p>Summary strings are effective to reduce the screen real estate used by 808 the default viewing mode, but are not effective if we want to display the 809 area and perimeter of <code>Rectangle</code> objects</p> 810 811 <p>To obtain this, we can simply attach a small Python script to the <code>Rectangle</code> 812 class, as shown in this example:</p> 813 814 <table class="stats" width="620" cellspacing="0"> 815 <td class="content"> 816 <b>(lldb)</b> type summary add -P Rectangle<br/> 817 Enter your Python command(s). Type 'DONE' to end.<br/> 818 def function (valobj,internal_dict):<br/> 819 height_val = valobj.GetChildMemberWithName('height')<br/> 820 width_val = valobj.GetChildMemberWithName('width')<br/> 821 height = height_val.GetValueAsUnsigned(0)<br/> 822 width = width_val.GetValueAsUnsigned(0)<br/> 823 area = height*width<br/> 824 perimeter = 2*(height + width)<br/> 825 return 'Area: ' + str(area) + ', Perimeter: ' + str(perimeter)<br/> 826 DONE<br/> 827 <b>(lldb)</b> frame variable<br/> 828 (Rectangle) r1 = Area: 20, Perimeter: 18<br/> 829 (Rectangle) r2 = Area: 72, Perimeter: 36<br/> 830 (Rectangle) r3 = Area: 16, Perimeter: 16<br/> 831 </td> 832 </table> 833 834 <p>In order to write effective summary scripts, you need to know the LLDB public 835 API, which is the way Python code can access the LLDB object model. For further 836 details on the API you should look at <a href="scripting.html">this page</a>, or at 837 the LLDB <a href="docs.html">API reference documentation</a>.</p> 838 839 <p>As a brief introduction, your script is encapsulated into a function that is 840 passed two parameters: <code>valobj</code> and <code>internal_dict</code>.</p> 841 842 <p><code>internal_dict</code> is an internal support parameter used by LLDB and you should 843 not touch it.<br/><code>valobj</code> is the object encapsulating the actual 844 variable being displayed, and its type is <a href="http://llvm.org/svn/llvm-project/lldb/trunk/include/lldb/API/SBValue.h">SBValue</a>. 845 Out of the many possible operations on an SBValue, the basic one is retrieve the children objects 846 it contains (essentially, the fields of the object wrapped by it), by calling 847 <code>GetChildMemberWithName()</code>, passing it the child's name as a string.<br/> 848 If the variable has a value, you can ask for it, and return it as a string using <code>GetValue()</code>, 849 or as a signed/unsigned number using <code>GetValueAsSigned()</code>, <code>GetValueAsUnsigned()</code>. 850 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 851 the object's contents out of the <code>SBData</code>. 852 853 <p>If you need to delve into several levels of hierarchy, as you can do with summary 854 strings, you can use the method <code>GetValueForExpressionPath()</code>, passing it 855 an expression path just like those you could use for summary strings (one of the differences 856 is that dereferencing a pointer does not occur by prefixing the path with a <code>*</code>, 857 but by calling the <code>Dereference()</code> method on the returned SBValue). 858 If you need to access array slices, you cannot do that (yet) via this method call, and you must 859 use <code>GetChildAtIndex()</code> querying it for the array items one by one. 860 Also, handling custom formats is something you have to deal with on your own. 861 862 <p>Other than interactively typing a Python script there are two other ways for you 863 to input a Python script as a summary: 864 865 <ul> 866 <li> using the --python-script option to <code>type summary add </code> and typing the script 867 code as an option argument; as in: </ul> 868 869 <table class="stats" width="620" cellspacing="0"> 870 <td class="content"> 871 <b>(lldb)</b> type summary add --python-script "height = 872 valobj.GetChildMemberWithName('height').GetValueAsUnsigned(0);width = 873 valobj.GetChildMemberWithName('width').GetValueAsUnsigned(0); 874 return 'Area: %d' % (height*width)" Rectangle<br/> 875 </td> 876 </table> 877 <ul> 878 <li> using the <code>--python-function</code> (<code>-F</code>) option to <code>type summary add </code> and giving the name of a 879 Python function with the correct prototype. Most probably, you will define (or have 880 already defined) the function in the interactive interpreter, or somehow 881 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. 882 </ul> 883 884 </p> 885 886 </div> 887 </div> 888 889 <div class="post"> 890 <h1 class="postheader">Regular expression typenames</h1> 891 <div class="postcontent"> 892 <p>As you noticed, in order to associate the custom 893 summary string to the array types, one must give the 894 array size as part of the typename. This can long become 895 tiresome when using arrays of different sizes, <code>Simple 896 897 [3]</code>, <code>Simple [9]</code>, <code>Simple 898 [12]</code>, ...</p> 899 <p>If you use the <code>-x</code> option, type names are 900 treated as regular expressions instead of type names. 901 This would let you rephrase the above example 902 for arrays of type <code>Simple [3]</code> as: <br> 903 904 <table class="stats" width="620" cellspacing="0"> 905 <td class="content"> 906 <b>(lldb)</b> type summary add --summary-string "${var[].x}" 907 -x "Simple \[[0-9]+\]" 908 </td> 909 <table> 910 911 <code> 912 <b>(lldb)</b> frame variable<br> 913 (Simple [3]) sarray = [1,4,7]<br> 914 (Simple [2]) sother = [3,6]<br> 915 </code> The above scenario works for <code>Simple [3]</code> 916 as well as for any other array of <code>Simple</code> 917 objects. </p> 918 <p>While this feature is mostly useful for arrays, you 919 could also use regular expressions to catch other type 920 sets grouped by name. However, as regular expression 921 matching is slower than normal name matching, LLDB will 922 first try to match by name in any way it can, and only 923 when this fails, will it resort to regular expression 924 matching. </p> 925 <p>One of the ways LLDB uses this feature internally, is to match 926 the names of STL container classes, regardless of the template 927 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> 928 929 <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 930 compliant implementation. 931 932 </div> 933 </div> 934 935 <div class="post"> 936 <h1 class="postheader">Named summaries</h1> 937 <div class="postcontent"> 938 <p>For a given type, there may be different meaningful summary 939 representations. However, currently, only one summary can be associated 940 to a type at each moment. If you need to temporarily override the association 941 for a variable, without changing the summary string for to its type, 942 you can use named summaries.</p> 943 944 <p>Named summaries work by attaching a name to a summary when creating 945 it. Then, when there is a need to attach the summary to a variable, the 946 <code>frame variable</code> command, supports a <code>--summary</code> option 947 that tells LLDB to use the named summary given instead of the default one.</p> 948 949 <table class="stats" width="620" cellspacing="0"> 950 <td class="content"> 951 <b>(lldb)</b> type summary add --summary-string "x=${var.integer}" --name NamedSummary 952 </td> 953 <table> 954 <code> <b>(lldb)</b> frame variable one<br> 955 (i_am_cool) one = int = 3, float = 3.14159, char = 69<br> 956 <b>(lldb)</b> frame variable one --summary NamedSummary<br> 957 (i_am_cool) one = x=3<br> 958 </code> </p> 959 960 <p>When defining a named summmary, binding it to one or more types becomes optional. 961 Even if you bind the named summary to a type, and later change the summary string 962 for that type, the named summary will not be changed by that. You can delete 963 named summaries by using the <code>type summary delete</code> command, as if the 964 summary name was the datatype that the summary is applied to</p> 965 966 <p>A summary attached to a variable using the </code>--summary</code> option, 967 has the same semantics that a custom format attached using the <code>-f</code> 968 option has: it stays attached till you attach a new one, or till you let 969 your program run again.</p> 970 971 </div> 972 </div> 973 974 <div class="post"> 975 <h1 class="postheader">Synthetic children</h1> 976 <div class="postcontent"> 977 <p>Summaries work well when one is able to navigate through an expression path. 978 In order for LLDB to do so, appropriate debugging information must be available.</p> 979 <p>Some types are <i>opaque</i>, i.e. no knowledge of their internals is provided. 980 When that's the case, expression paths do not work correctly.</p> 981 <p>In other cases, the internals are available to use in expression paths, but they 982 do not provide a user-friendly representation of the object's value.</p> 983 <p>For instance, consider an STL vector, as implemented by the <a href="http://gcc.gnu.org/onlinedocs/libstdc++/">GNU C++ Library</a>:</p> 984 <code> 985 <b>(lldb)</b> frame variable numbers -T<br/> 986 (std::vector<int>) numbers = {<br/> 987 (std::_Vector_base<int, std::allocator<int> >) std::_Vector_base<int, std::allocator<int> > = {<br/> 988 (std::_Vector_base<int, std::allocator&tl;int> >::_Vector_impl) _M_impl = {<br/> 989 (int *) _M_start = 0x00000001001008a0<br/> 990 (int *) _M_finish = 0x00000001001008a8<br/> 991 (int *) _M_end_of_storage = 0x00000001001008a8<br/> 992 }<br/> 993 }<br/> 994 }<br/> 995 </code> 996 <p>Here, you can see how the type is implemented, and you can write a summary for that implementation 997 but that is not going to help you infer what items are actually stored in the vector.</p> 998 <p>What you would like to see is probably something like:</p> 999 <code> 1000 <b>(lldb)</b> frame variable numbers -T<br/> 1001 (std::vector<int>) numbers = {<br/> 1002 (int) [0] = 1<br/> 1003 (int) [1] = 12<br/> 1004 (int) [2] = 123<br/> 1005 (int) [3] = 1234<br/> 1006 }<br/> 1007 </code> 1008 <p>Synthetic children are a way to get that result.</p> 1009 <p>The feature is based upon the idea of providing a new set of children for a variable that replaces the ones 1010 available by default through the debug information. In the example, we can use synthetic children to provide 1011 the vector items as children for the std::vector object.</p> 1012 <p>In order to create synthetic children, you need to provide a Python class that adheres to a given <i>interface</i> 1013 (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 1014 must be implemented by the Python class):</p> 1015 <code> 1016 <font color=blue>class</font> SyntheticChildrenProvider:<br/> 1017 <font color=blue>def</font> __init__(self, valobj, internal_dict):<br/> 1018 <i>this call should initialize the Python object using valobj as the variable to provide synthetic children for</i> <br/> 1019 <font color=blue>def</font> num_children(self): <br/> 1020 <i>this call should return the number of children that you want your object to have</i> <br/> 1021 <font color=blue>def</font> get_child_index(self,name): <br/> 1022 <i>this call should return the index of the synthetic child whose name is given as argument</i> <br/> 1023 <font color=blue>def</font> get_child_at_index(self,index): <br/> 1024 <i>this call should return a new LLDB SBValue object representing the child at the index given as argument</i> <br/> 1025 <font color=blue>def</font> update(self): <br/> 1026 <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/> 1027 <font color=blue>def</font> has_children(self): <br/> 1028 <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/> 1029 </code> 1030 <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>. 1031 <br/> 1032 <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. 1033 <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/) 1034 is legacy code and is not maintained. 1035 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 1036 a feel for this feature, as it is a very easy and well commented example.</p> 1037 The design pattern consistently used in synthetic providers shipping with LLDB 1038 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 1039 to perform the actual initialization. 1040 1041 1042 <p>Once a synthetic children provider is written, one must load it into LLDB before it can be used. 1043 Currently, one can use the LLDB <code>script</code> command to type Python code interactively, 1044 or use the <code>command script import <i>fileName </i></code> command to load Python code from a Python module 1045 (ordinary rules apply to importing modules this way). A third option is to type the code for 1046 the provider class interactively while adding it.</p> 1047 1048 <p>For example, let's pretend we have a class <code>Foo</code> for which a synthetic children provider class 1049 <code>Foo_Provider</code> is available, in a Python module contained in file <code>~/Foo_Tools.py</code>. The following interaction 1050 sets <code>Foo_Provider</code> as a synthetic children provider in LLDB:</p> 1051 1052 <table class="stats" width="620" cellspacing="0"> 1053 <td class="content"> 1054 <b>(lldb)</b> command script import ~/Foo_Tools.py<br/> 1055 <b>(lldb)</b> type synthetic add Foo --python-class Foo_Tools.Foo_Provider 1056 </td> 1057 <table> 1058 <code> <b>(lldb)</b> frame variable a_foo<br/> 1059 (Foo) a_foo = {<br/> 1060 x = 1<br/> 1061 y = "Hello world"<br/> 1062 } <br/> 1063 </code> </p> 1064 1065 <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> 1066 1067 <p>Synthetic children extend summary strings by enabling a new special variable: <code>${svar</code>.<br/> 1068 This symbol tells LLDB to refer expression paths to the 1069 synthetic children instead of the real ones. For instance,</p> 1070 1071 <table class="stats" width="620" cellspacing="0"> 1072 <td class="content"> 1073 <b>(lldb)</b> type summary add --expand -x "std::vector<" --summary-string "${svar%#} items" 1074 </td> 1075 </table> 1076 <code> <b>(lldb)</b> frame variable numbers<br/> 1077 (std::vector<int>) numbers = 4 items {<br/> 1078 (int) [0] = 1<br/> 1079 (int) [1] = 12<br/> 1080 (int) [2] = 123<br/> 1081 (int) [3] = 1234<br/> 1082 }<br/> 1083 </code> </p> 1084 <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 1085 synthetic children. While in summaries it is best to always use <code>${svar</code> to make your intentions clearer, interactive debugging 1086 can benefit from this behavior, as in: 1087 <code> <b>(lldb)</b> frame variable numbers[0] numbers[1]<br/> 1088 (int) numbers[0] = 1<br/> 1089 (int) numbers[1] = 12<br/> 1090 </code> </p> 1091 Unlike many other visualization features, however, the access to synthetic children only works when using <code>frame variable</code>, and is 1092 not supported in <code>expression</code>:<br/> 1093 <code> <b>(lldb)</b> expression numbers[0]<br/> 1094 Error [IRForTarget]: Call to a function '_ZNSt33vector<int, std::allocator<int> >ixEm' that is not present in the target<br/> 1095 error: Couldn't convert the expression to DWARF<br/> 1096 </code> </p> 1097 The reason for this is that classes might have an overloaded <code><font color="blue">operator</font> []</code>, or other special provisions 1098 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. 1099 </div> 1100 </div> 1101 1102 <div class="post"> 1103 <h1 class="postheader">Filters</h1> 1104 <div class="postcontent"> 1105 <p>Filters are a solution to the display of complex classes. 1106 At times, classes have many member variables but not all of these are actually 1107 necessary for the user to see.</p> 1108 <p>A filter will solve this issue by only letting the user see those member 1109 variables he cares about. Of course, the equivalent of a filter can be implemented easily 1110 using synthetic children, but a filter lets you get the job done without having to write 1111 Python code.</p> 1112 <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 1113 the ones named <code>B</code>, <code>H</code> and <code>Q</code>, you can define a filter: 1114 <table class="stats" width="620" cellspacing="0"> 1115 <td class="content"> 1116 <b>(lldb)</b> type filter add Foobar --child B --child H --child Q 1117 </td> 1118 </table> 1119 <code> <b>(lldb)</b> frame variable a_foobar<br/> 1120 (Foobar) a_foobar = {<br/> 1121 (int) B = 1<br/> 1122 (char) H = 'H'<br/> 1123 (std::string) Q = "Hello world"<br/> 1124 }<br/> 1125 </code> </p> 1126 </div> 1127 </div> 1128 1129 <div class="post"> 1130 <h1 class="postheader">Objective-C dynamic type discovery</h1> 1131 <div class="postcontent"> 1132 <p>When doing Objective-C development, you may notice that some of your variables 1133 come out as of type <code>id</code> (for instance, items extracted from <code>NSArray</code>). 1134 By default, LLDB will not show you the real type of the object. it can actually dynamically discover the type of an Objective-C 1135 variable, much like the runtime itself does when invoking a selector. In order 1136 to be shown the result of that discovery that, however, a special option to <code>frame variable</code> or <code>expression</code> is 1137 required: <br/><code>--dynamic-type</code>.</p> 1138 <p><code>--dynamic-type</code> can have one of three values: 1139 <ul> 1140 <li><code>no-dynamic-values</code>: the default, prevents dynamic type discovery</li> 1141 <li><code>no-run-target</code>: enables dynamic type discovery as long as running 1142 code on the target is not required</li> 1143 <li><code>run-target</code>: enables code execution on the target in order to perform 1144 dynamic type discovery</li> 1145 </ul> 1146 </p> 1147 <p> 1148 If you specify a value of either <code>no-run-target</code> or <code>run-target</code>, 1149 LLDB will detect the dynamic type of your variables and show the appropriate formatters 1150 for them. As an example: 1151 </p> 1152 <p><table class="stats" width="620" cellspacing="0"> 1153 <td class="content"> 1154 <b>(lldb)</b> expr @"Hello" 1155 </td> 1156 </table> 1157 <code>(NSString *) $0 = 0x00000001048000b0 @"Hello"<br/> 1158 </code> 1159 <p><table class="stats" width="620" cellspacing="0"> 1160 <td class="content"> 1161 <b>(lldb)</b> expr -d no-run @"Hello" 1162 </td> 1163 </table> 1164 <code>(__NSCFString *) $1 = 0x00000001048000b0 @"Hello"<br/> 1165 </code> 1166 <p> 1167 Because LLDB uses a detection algorithm that does not need to invoke any functions 1168 on the target process, <code>no-run-target</code> is enough for this to work.</p> 1169 As a side note, the summary for NSString shown in the example is built right into LLDB. 1170 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>). 1171 However, this is out of sync with the current implementation of the NSString formatter (which is a C++ function compiled into the LLDB core). 1172 </p> 1173 </div> 1174 </div> 1175 1176 <div class="post"> 1177 <h1 class="postheader">Categories</h1> 1178 <div class="postcontent"> 1179 <p>Categories are a way to group related formatters. For instance, LLDB itself groups 1180 the formatters for the libstdc++ types in a category named <code>gnu-libstdc++</code>. 1181 Basically, categories act like containers in which to store formatters for a same library 1182 or OS release.</p> 1183 <p>By default, several categories are created in LLDB: 1184 <ul> 1185 <li><code>default</code>: this is the category where every formatter ends up, unless another category is specified 1186 <li><code>objc</code>: formatters for basic and common Objective-C types that do not specifically depend on Mac OS X 1187 <li><code>gnu-libstdc++</code>: formatters for std::string, std::vector, std::list and std::map as implemented by libstdcpp 1188 <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> 1189 <li><code>system</code>: truly basic types for which a formatter is required 1190 <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 1191 <li><a href="https://developer.apple.com/corefoundation/"><code>CoreFoundation</code></a>: CF classes 1192 <li><a href="https://developer.apple.com/library/mac/#documentation/CoreGraphics/Reference/CoreGraphicsConstantsRef/Reference/reference.html"><code>CoreGraphics</code></a>: CG classes 1193 <li><a href="http://developer.apple.com/library/mac/#documentation/Carbon/reference/CoreServicesReferenceCollection/_index.html"><code>CoreServices</code></a>: CS classes 1194 <li><code>VectorTypes</code>: compact display for several vector types 1195 </ul> 1196 If you want to use a custom category for your formatters, all the <code>type ... add</code> (except for <code>type format add</code>), 1197 provide a <code>--category</code> (<code>-w</code>) option, that names the category to add the formatter to. 1198 To delete the formatter, you then have to specify the correct category.</p> 1199 <p>Categories can be in one of two states: enabled and disabled. A category is initially disabled, 1200 and can be enabled using the <code>type category enable</code> command. To disable an enabled category, 1201 the command to use is <code>type category disable</code>. 1202 <p>The order in which categories are enabled or disabled 1203 is significant, in that LLDB uses that order when looking for formatters. Therefore, when you enable a category, it becomes 1204 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: 1205 <ul> 1206 <li>default</li> 1207 <li>objc</li> 1208 <li>CoreFoundation</li> 1209 <li>AppKit</li> 1210 <li>CoreServices</li> 1211 <li>CoreGraphics</li> 1212 <li>gnu-libstdc++</li> 1213 <li>libcxx</li> 1214 <li>VectorTypes</li> 1215 <li>system</li> 1216 </ul> 1217 <p>As said, <code>gnu-libstdc++</code> and <code>libcxx</code> contain formatters for C++ STL 1218 data types. <code>system</code> contains formatters for <code>char*</code> and <code>char[]</code>, which reflect the behavior 1219 of older versions of LLDB which had built-in formatters for these types. Because now these are formatters, you can even 1220 replace them with your own if so you wish.</p> 1221 <p>There is no special command to create a category. When you place a formatter in a category, if that category does not 1222 exist, it is automatically created. For instance,</p> 1223 <p><table class="stats" width="620" cellspacing="0"> 1224 <td class="content"> 1225 <b>(lldb)</b> type summary add Foobar --summary-string "a foobar" --category newcategory 1226 </td> 1227 </table> 1228 automatically creates a (disabled) category named newcategory.</p> 1229 <p>Another way to create a new (empty) category, is to enable it, as in:</p> 1230 <p><table class="stats" width="620" cellspacing="0"> 1231 <td class="content"> 1232 <b>(lldb)</b> type category enable newcategory 1233 </td> 1234 </table> 1235 <p>However, in this case LLDB warns you that enabling an empty category has no effect. If you add formatters to the 1236 category after enabling it, they will be honored. But an empty category <i>per se</i> does not change the way any 1237 type is displayed. The reason the debugger warns you is that enabling an empty category might be a typo, and you 1238 effectively wanted to enable a similarly-named but not-empty category.</p> 1239 </div> 1240 </div> 1241 1242 <div class="post"> 1243 <h1 class="postheader">Finding formatters 101</h1> 1244 <div class="postcontent"> 1245 <p>While the rules for finding an appropriate format for a 1246 type are relatively simple (just go through typedef 1247 hierarchies), searching other formatters goes through 1248 a rather intricate set of rules. Namely, what happens is that LLDB 1249 starts looking in each enabled category, according to the order in which 1250 they were enabled (latest enabled first). In each category, LLDB does 1251 the following:</p> 1252 <ul> 1253 <li>If there is a formatter for the type of the variable, 1254 use it</li> 1255 <li>If this object is a pointer, and there is a formatter 1256 for the pointee type that does not skip pointers, use 1257 it</li> 1258 <li>If this object is a reference, and there is a 1259 formatter for the referred type that does not skip 1260 references, use it</li> 1261 <li>If this object is an Objective-C class and dynamic types are enabled, 1262 look for a formatter for the dynamic type of the object. If dynamic types are disabled, 1263 or the search failed, look for a formatter for the declared type of the object</li> 1264 <li>If this object's type is a typedef, go through 1265 typedef hierarchy (LLDB might not be able to do this if 1266 the compiler has not emitted enough information. If the 1267 required information to traverse typedef hierarchies is 1268 missing, type cascading will not work. The 1269 <a href="http://clang.llvm.org/">clang compiler</a>, 1270 part of the LLVM project, emits the correct debugging 1271 information for LLDB to cascade). If at any level of the hierarchy 1272 there is a valid formatter that can cascade, use it.</li> 1273 <li>If everything has failed, repeat the above search, 1274 looking for regular expressions instead of exact 1275 matches</li> 1276 </ul> 1277 <p>If any of those attempts returned a valid formatter to be used, 1278 that one is used, and the search is terminated (without going to look 1279 in other categories). If nothing was found in the current category, the next 1280 enabled category is scanned according to the same algorithm. If there are no 1281 more enabled categories, the search has failed.</p> 1282 <p><font color=red>Warning</font>: previous versions of LLDB defined cascading to mean 1283 not only going through typedef chains, but also through inheritance chains. 1284 This feature has been removed since it significantly degrades performance. 1285 You need to set up your formatters for every type in inheritance chains to which 1286 you want the formatter to apply.</p> 1287 </div> 1288 </div> 1289 </div> 1290 </div> 1291 </div> 1292 </body> 1293 </html> 1294
