Blame - www/varformats.html - fp2-dev/platform/external/lldb

Enrico Granata

2011-07-08 02:51:01 +0000

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<head>

charset=ISO-8859-1">

<title>LLDB Homepage</title>

8

</head>

9

<body>

10

<div class="www_title"> The LLDB Debugger </div>

11

12

13

14

15

16

<h1 class="postheader">Variable display</h1>

17

18

19

LLDB was recently modified to allow users to define custom

20

formatting options for the variables display.

21

22

Usually, when you type <code>frame variable</code> or

23

run some <code>expression</code> LLDB will

24

automatically choose a format to display your results on

25

a per-type basis, as in the following example:

26

27

<code> (lldb) frame variable -T sp

28

(SimpleWithPointers) sp = {

29

(int *) x = 0x0000000100100120

    (float *) y =

0x0000000100100130

    (char *) z =

0x0000000100100140 "6"

}

</code>

However, in certain cases, you may want to associate a

38

different format to the display for certain datatypes.

39

To do so, you need to give hints to the debugger as to

40

how datatypes should be displayed.

41

A new type command has been introduced in LLDB

42

which allows to do just that.

43

44

45

Using it you can obtain a format like this one for <code>sp</code>,

46

instead of the default shown above:

47

48

<code> (lldb) frame variable sp

49

(SimpleWithPointers) sp =

50

(x=0x0000000100100120 -> -1, y=0x0000000100100130

-> -2, z="3")

</code>

There are two kinds of printing options: <span

55

style="font-style: italic;">summary and <span

56

style="font-style: italic;">format. While a

57

detailed description of both will be given below, one

58

can briefly say that a summary is mainly used for

59

aggregate types, while a format is attached to primitive

60

types.

61

62

To reflect this, the the type command has two

subcommands:

<code>type format</code>

67

<code>type summary</code>

68

69

These commands are meant to bind printing options to

70

types. When variables are printed, LLDB will first check

71

if custom printing options have been associated to a

72

variable's type and, if so, use them instead of picking

the default choices.

The two commands <code>type format</code> and <code>type

77

summary</code> each have four subcommands:

78

79

<code>add</code>: associates a new printing option to one

80

or more types

81

<code>delete</code>: deletes an existing association

82

<code>list</code>: provides a listing of all

83

associations

84

<code>clear</code>: deletes all associations

</div>

</div>

<h1 class="postheader">type format</h1>

90

91

92

Type formats enable you to quickly override the default

93

format for displaying primitive types (the usual basic

94

C/C++/ObjC types: int, float, char, ...).

95

96

If for some reason you want all <code>int</code>

97

variables in your program to print out as hex, you can add

98

a format to the <code>int</code> type.

99

100

This is done by typing <code>type format add -f hex

101

int</code> at the LLDB command line.

102

103

The <code>-f</code> option accepts a <a

104

href="#formatstable">format name</a>, and a list of

105

types to which you want the new format applied.

106

107

A frequent scenario is that your program has a <code>typedef</code>

108

for a numeric type that you know represents something

109

that must be printed in a certain way. Again, you can

110

add a format just to that typedef by using <code>type

111

format add</code> with the name alias.

112

113

But things can quickly get hierarchical. Let's say you

114

have a situation like the following:

<code>typedef int A;

typedef A B;

typedef B C;

typedef C D;

</code>

and you want to show all <code>A</code>'s as hex, all

123

<code>C'</code>s as pointers and leave the defaults

124

untouched for other types.

125

126

If you simply type

127

<code>type format add -f hex A

128

type format add -f pointer C</code>

129

130

values of type <code>B</code> will be shown as hex

131

and values of type <code>D</code> as pointers.

132

133

This is because by default LLDB cascades

134

formats through typedef chains. In order to avoid that

135

you can use the option <code>-C no</code> to prevent

136

cascading, thus making the two commands required to

137

achieve your goal:

138

<code> type format add -f hex -C no A

139

type format add -f pointer -C no C </code>

140

141

Two additional options that you will want to look at

142

are <code>-p</code> and <code>-r</code>. These two

143

options prevent LLDB from applying a format for type <code>T</code>

144

to values of type <code>T*</code> and <code>T&</code>

145

respectively.

146

147

<code> (lldb) type format add -f float32[]

148

int

149

(lldb) fr var pointer *pointer -T

150

(int *) pointer = {1.46991e-39 1.4013e-45}

151

(int) *pointer = {1.53302e-42}

152

(lldb) type format add -f float32[] int -p

153

(lldb) fr var pointer *pointer -T

154

(int *) pointer = 0x0000000100100180

155

(int) *pointer = {1.53302e-42}

156

</code>

157

158

As the previous example highlights, you will most

159

probably want to use <code>-p</code> for your formats.

160

161

If you need to delete a custom format simply type <code>type

162

format delete</code> followed by the name of the type

163

to which the format applies. To delete ALL formats, use

164

<code>type format clear</code>. To see all the formats

165

defined, type <code>type format list</code>.

166

167

168

If all you need to do, however, is display one variable

169

in a custom format, while leaving the others of the same

170

type untouched, you can simply type:

171

172

<code>frame variable counter -f hex</code>

173

174

This has the effect of displaying the value of <code>counter</code>

175

as an hexadecimal number, and will keep showing it this

176

way until you either pick a different format or till you

177

let your program run again.

178

179

Finally, this is a list of formatting options available

180

out of

181

which you can pick:<a name="formatstable"></a>

<tbody>

<td width="23%">Format name</td>

186

<td>Abbreviation</td>

<td>Description</td>

</tr>

<td>default</td>

<td>

</td>

<td>the default LLDB algorithm is used to pick a

format</td>

</tr>

<td>boolean</td>

<td>show this as a true/false boolean, using the

200

customary rule that 0 is false and everything else

is true</td>

</tr>

<td>binary</td>

<td>show this as a sequence of bits</td>

</tr>

<td>bytes</td>

<td>show the bytes one after the other

212

e.g. <code>(int) s.x = 07 00 00 00</code></td>

213

</tr>

214

215

<td>bytes with ASCII</td>

216

217

<td>show the bytes, but try to print them as ASCII

218

characters

219

e.g. <code>(int *) c.sp.x = 50 f8 bf 5f ff 7f 00

220

00 P.._....</code></td>

</tr>

<td>character</td>

<td>show the bytes printed as ASCII characters

226

e.g. <code>(int *) c.sp.x =

227

P\xf8\xbf_\xff\x7f\0\0</code></td>

228

</tr>

229

230

<td>printable character</td>

231

232

<td>show the bytes printed as printable ASCII

233

characters

234

e.g. <code>(int *) c.sp.x = P.._....</code></td>

235

</tr>

236

237

<td>complex float</td>

238

239

<td>interpret this value as the real and imaginary

240

part of a complex floating-point number

241

e.g. <code>(int *) c.sp.x = 2.76658e+19 +

242

4.59163e-41i</code></td>

</tr>

<td>c-string</td>

<td>show this as a 0-terminated C string</td>

248

</tr>

249

250

<td>signed decimal</td>

251

252

<td>show this as a signed integer number (this does

253

not perform a cast, it simply shows the bytes as

signed integer)</td>

</tr>

<td>enumeration</td>

<td>show this as an enumeration, printing the

260

value's name if available or the integer value

261

otherwise

262

e.g. <code>(enum enumType) val_type = eValue2</code></td>

</tr>

<td>show this as in hexadecimal notation (this does

268

not perform a cast, it simply shows the bytes as

hex)</td>

</tr>

<td>float</td>

<td>show this as a floating-point number (this does

275

not perform a cast, it simply interprets the bytes

276

as an IEEE754 floating-point value)</td>

</tr>

<td>octal</td>

<td>show this in octal notation</td>

</tr>

<td>OSType</td>

<td>show this as a MacOS OSType

287

e.g. <code>(float) *c.sp.y = '\n\x1f\xd7\n'</code></td>

</tr>

<td>unicode16</td>

<td>show this as UTF-16 characters

293

e.g. <code>(float) *c.sp.y = 0xd70a 0x411f</code></td>

</tr>

<td>unicode32</td>

<td>

</td>

<td>show this as UTF-32 characters

300

e.g. <code>(float) *c.sp.y = 0x411fd70a</code></td>

301

</tr>

302

303

<td>unsigned decimal</td>

304

305

<td>show this as an unsigned integer number (this

306

does not perform a cast, it simply shows the bytes

307

as unsigned integer)</td>

</tr>

<td>pointer</td>

<td>show this as a native pointer (unless this is

313

really a pointer, the resulting address will

314

probably be invalid)</td>

</tr>

<td>

</td>

<td>show this as an array of characters

321

e.g. <code>(char) *c.sp.z = {X}</code></td>

322

</tr>

323

324

<td>int8_t[], uint8_t[]

325

int16_t[], uint16_t[]

326

int32_t[], uint32_t[]

327

int64_t[], uint64_t[]

uint128_t[]</td>

<td>

</td>

<td>show this as an array of the corresponding

332

integer type

333

e.g.

334

<code>(int) sarray[0].x = {1 0 0 0}</code>

335

<code>(int) sarray[0].x = {0x00000001}</code></td>

336

</tr>

337

338

<td>float32[], float64[]</td>

339

<td>

340

</td>

341

<td>show this as an array of the corresponding

342

floating-point type

343

e.g. <code>(int *) pointer = {1.46991e-39

344

1.4013e-45}</code></td>

345

</tr>

346

347

<td>complex integer</td>

348

349

<td>interpret this value as the real and imaginary

350

part of a complex integer number

351

e.g. <code>(int *) pointer = 1048960 + 1i</code></td>

352

</tr>

353

354

<td>character array</td>

355

356

<td>show this as a character array

357

e.g. <code>(int *) pointer =

358

\x80\x01\x10\0\x01\0\0\0</code></td>

</tr>

</tbody>

</table>

</div>

</div>

<h1 class="postheader">type summary</h1>

367

368

Type summaries enable you to add more information to

369

the default viewing format for a type, or to completely

370

replace it with your own display option. Unlike formats

371

which only apply to basic types, summaries can be used

372

on every type (basic types, classes (C++ and

373

Objective-C), arrays, ...).

374

The basic idea beneath type summaries is extracting

375

information from variables and arranging it in a format

376

that is suitable for display:

377

before adding a summary...

378

<code> (lldb) fr var -T one

379

(i_am_cool) one = {

380

(int) integer = 3

381

(float) floating = 3.14159

382

(char) character = 'E'

383

}

384

</code>

385

after adding a summary...

386

<code> (lldb) fr var one

387

(i_am_cool) one = int = 3, float = 3.14159, char = 69

388

</code>

389

Evidently, somehow we managed to tell LLDB to grab the

390

three member variables of the <code>i_am_cool</code>

391

datatype, mix their values with some text, and even ask

392

it to display the <code>character</code> member using a

393

custom format.

394

The way to do this is add a summary string to

395

the datatype using the <code>type summary add</code>

396

command.

397

Its syntax is similar to <code>type format add</code>,

398

but some more options are supported that will be

399

described in the follow-up.

400

The main option to <code>type summary add</code> is <code>-f</code>

401

which accepts as parameter a summary string. After that,

402

you can type as many type names as you want to associate

403

the given summary string to them.

</div>

</div>

<h1 class="postheader">Summary Strings</h1>

408

409

So what is the format of the summary strings? Summary

410

strings can contain plain text, control characters and

411

special symbols that have access to information about

412

the current object and the overall program state.

413

Normal characters are any text that doesn't contain a <code>'{'</code>,

414

415

character.

416

Variable names are found in between a <code>"${"</code>

417

prefix, and end with a <code>"}"</code> suffix.

418

In other words, a variable looks like <code>"${frame.pc}"</code>.

419

Basically, all the variables described in <a

420

href="formats.html">Frame and Thread Formatting</a>

421

are accepted. Also acceptable are the control characters

422

and scoping features described in that page.

423

Additionally, <code>${var</code> and <code>${*var</code>

424

become acceptable symbols in this scenario.

425

The simplest thing you can do is grab a member variable

426

of a class or structure by typing its expression

427

path. In the previous example, the expression path

428

for the floating member is simply <code>.floating</code>,

429

because all you have to do to get at it given an object

430

of type <code>i_am_cool</code> is access it straight

431

away. Thus, to ask the summary string to display <code>floating</code>

432

you would type <code>${var.floating}</code> (<code>${var</code>

433

is a placeholder token replaced with whatever variable

434

is being displayed).

435

If you have code like the following:

<code> struct A {

int x;

int y;

};

struct B {

A x;

A y;

int z;

};

</code> the expression path for the <code>y</code>

446

member of the <code>x</code> member of an object of

447

type <code>B</code> would be <code>.x.y</code> and you

448

would type <code>${var.x.y}</code> to display it in a

449

summary string for type <code>B</code>.

450

As you could be using a summary string for both

451

displaying objects of type <code>T</code> or <code>T*</code>

452

(unless <code>-p</code> is used to prevent this), the

453

expression paths do not differentiate between <code>.</code>

454

and <code>-></code>, and the above expression path <code>.x.y</code>

455

would be just as good if you were displaying a <code>B*</code>,

456

or even if the actual definition of <code>B</code>

were: <code>

struct B {

A *x;

A y;

int z;

};

</code>

This is unlike the behaviour of <code>frame variable</code>

465

which, on the contrary, will enforce the distinction. As

466

hinted above, the rationale for this choice is that

467

waiving this distinction enables one to write a summary

468

string once for type <code>T</code> and use it for both

469

<code>T</code> and <code>T*</code> instances. As a

470

summary string is mostly about extracting nested

471

members' information, a pointer to an object is just as

472

good as the object itself for the purpose.

473

Of course, you can have multiple entries in one summary

474

string. For instance, the command used to produce the

475

above summary string for i_am_cool was:

476

<code>type summary add -f "int = ${var.integer}, float =

477

${var.floating}, char = ${var.character%u}" i_am_cool

478

</code>

479

As you can see, the last expression path also contains

480

a <code>%u</code> symbol which is nowhere to be found

481

in the actual member variable name. The symbol is

482

reminding of a <code>printf()</code> format symbol, and

483

in fact it has a similar effect. If you add a % sign

484

followed by any one format name or abbreviation from the

485

above table after an expression path, the resulting

486

object will be displyed using exactly that format

487

instead of the LLDB default one.

488

There are two more special format symbols that you can

489

use only as part of a summary string: <code>%V</code>

490

and <code>%@</code>. The first one tells LLDB to ignore

491

summary strings for the type of the object referred by

492

the expression path and instead print the object's

493

value. The second is only applicable to Objective-C

494

classes, and tells LLDB to get the object's description

495

from the Objective-C runtime. By default, if no format

496

is provided, LLDB will try to get the object's summary,

497

and if empty the object's value. If neither can be

498

obtained, nothing will be displayed.

499

As previously said, pointers and values are treated the

500

same way when getting to their members in an expression

501

path. However, if your expression path leads to a

502

pointer, LLDB will not automatically dereference it. In

503

order to obtain The deferenced value for a pointer, your

504

expression path must start with <code>${*var</code>

505

instead of <code>${var</code>. Because there is no need

506

to dereference pointers along your way, the

507

dereferencing symbol only applies to the result of the

508

whole expression path traversing.

e.g. <code>

(lldb) fr var -T c

(Couple) c = {

(SimpleWithPointers) sp = {

513

(int *) x = 0x00000001001000b0

514

(float *) y = 0x00000001001000c0

515

(char *) z = 0x00000001001000d0 "X"

516

}

517

(Simple *) s = 0x00000001001000e0

518

}

519

(lldb) type summary add -f "int = ${*var.sp.x},

520

float = ${*var.sp.y}, char = ${*var.sp.z%u}, Simple =

521

${*var.s}" Couple

522

(lldb) type summary add -c -p Simple

523

(lldb) fr var c

524

(Couple) c = int = 9, float = 9.99, char = 88, Simple

525

= (x=9, y=9.99, z='X')

526

</code>

527

Option <code>-c</code> to <code>type summary add</code>

528

tells LLDB not to look for a summary string, but instead

529

to just print a listing of all the object's children on

530

one line, lay out as in the previous example. The <code>-p</code>

531

flag is used as a trick to show that aggregate types can

532

be dereferenced as well as primitive ones. The above

533

output would be shown even by typing <code>type summary

534

add -f "int = ${*var.sp.x}, float = ${*var.sp.y}, char

535

= ${*var.sp.z%u}, Simple = ${var.s}" Couple</code> if

536

one took away the <code>-p</code> flag from the summary

537

for type <code>Simple</code>.

</div>

</div>

<h1 class="postheader">More on summary strings</h1>

542

543

What was described above are the main features that you

544

can use in summary strings. However, there are three

545

more features to them.

546

Sometimes, a basic type's value actually represents

547

several different values packed together in a bitfield.

548

With the classical view, there is no way to look at

549

them. Hexadecimal display can help, but if the bits

550

actually span byte boundaries, the help is limited.

551

Binary view would show it all without ambiguity, but is

552

often too detailed and hard to read for real-life

553

scenarios. To cope with the issue, LLDB supports native

554

bitfield formatting in summary strings. If your

555

expression paths leads to a so-called scalar type

556

(the usual int, float, char, double, short, long, long

557

long, double, long double and unsigned variants), you

558

can ask LLDB to only grab some bits out of the value and

559

display them in any format you like. The syntax is

560

similar to that used for arrays, just you can also give

561

a pair of indices separated by a <code>-</code>.

562

e.g.

563

<code> (lldb) fr var float_point

564

(float) float_point = -3.14159

565

(lldb) type summary add -f "Sign: ${var[31]%B}

566

Exponent: ${var[30-23]%x} Mantissa: ${var[0-22]%u}"

567

float

568

(lldb) fr var float_point

569

(float) float_point = -3.14159 Sign: true Exponent:

570

0x00000080 Mantissa: 4788184

571

</code> In this example, LLDB shows the internal

572

representation of a <code>float</code> variable by

573

extracting bitfields out of a float object. If you give

574

a single index, only that one bit will be extracted. If

575

you give a pair of indices, all the bits in the range

576

(extremes included) will be extracted. Ranges can be

577

specified either by giving the lower index first, or

578

higher index first (as is often customary in describing

579

packed data-type formats).

580

The second additional feature allows you to display

581

array members inside a summary string. For instance, you

582

may want to display all arrays of a given type using a

583

more compact notation than the default, and then just

584

delve into individual array members that prove

585

interesting to your debugging task. You can use a

586

similar syntax to the one used for bitfields to tell

587

LLDB to format arrays in special ways.

588

e.g.

589

<code> (lldb) fr var sarray

590

(Simple [3]) sarray = {

[0] = {

x = 1

y = 2

z = '\x03'

}

[1] = {

x = 4

y = 5

z = '\x06'

}

[2] = {

x = 7

y = 8

z = '\t'

}

}

(lldb) type summary add -f "${var[].x}" "Simple

608

[3]"

609

(lldb) fr var sarray

610

(Simple [3]) sarray = [1,4,7]

611

</code> The <code>[]</code> symbol amounts to: if <code>var</code>

612

is an array and I knows its size, apply this summary

613

string to every element of the array. Here, we are

614

asking LLDB to display <code>.x</code> for every

615

element of the array, and in fact this is what happens.

616

If you find some of those integers anomalous, you can

617

then inspect that one item in greater detail, without

618

the array format getting in the way:

619

<code> (lldb) fr var sarray[1]

620

(Simple) sarray[1] = {

x = 4

y = 5

z = '\x06'

}

</code>

You can also ask LLDB to only print a subset of the

627

array range by using the same syntax used to extract bit

628

for bitfields.

629

The same logic works if you are printing a pointer

630

instead of an array, however in this latter case, <code>[]</code>

631

cannot be used and you need to give exact range limits.

632

The third, and last, additional feature does not

633

directly apply to the summary strings themselves, but is

634

an additional option to the <code>type summary add</code>

635

command: <code>-x</code>

636

As you noticed, in order to associate the custom

637

summary string to the array types, one must give the

638

array size as part of the typename. This can long become

639

tiresome when using arrays of different sizes, <code>Simple

640

641

[3]</code>, <code>Simple [9]</code>, <code>Simple

642

[12]</code>, ...

643

If you use the <code>-x</code> option, type names are

644

treated as regular expressions instead of type names.

645

This would let you rephrase the above example as:

646

<code> (lldb) type summary add -f "${var[].x}"

647

-x "Simple \[[0-9]+\]"

648

(lldb) fr var sarray

649

(Simple [3]) sarray = [1,4,7]

650

</code> The above scenario works for <code>Simple [3]</code>

651

as well as for any other array of <code>Simple</code>

652

objects.

653

While this feature is mostly useful for arrays, you

654

could also use regular expressions to catch other type

655

sets grouped by name. However, as regular expression

656

matching is slower than normal name matching, LLDB will

657

first try to match by name in any way it can, and only

658

when this fails, will it resort to regular expression

659

matching. Thus, if your type has a base class with a

660

cascading summary, this will be preferred over any

661

regular expression match for your type itself.

</div>

</div>

<h1 class="postheader">Finding summaries 101</h1>

666

667

While the rules for finding an appropriate format for a

668

type are relatively simple (just go through typedef

669

hierarchies), summaries follow a more complicated

670

process in finding the right summary string for a

671

variable. Namely, what happens is:

672

<ul>

673

<li>If there is a summary for the type of the variable,

674

use it</li>

675

<li>If this object is a pointer, and there is a summary

676

for the pointee type that does not skip pointers, use

677

it</li>

678

<li>If this object is a reference, and there is a

679

summary for the pointee type that does not skip

680

references, use it</li>

681

<li>If this object is an Objective-C class with a parent

682

class, look at the parent class (and parent of parent,

683

...)</li>

684

<li>If this object is a C++ class with base classes,

685

look at base classes (and bases of bases, ...)</li>

686

<li>If this object is a C++ class with virtual base

687

classes, look at the virtual base classes (and bases

688

of bases, ...)</li>

689

<li>If this object's type is a typedef, go through

690

typedef hierarchy</li>

691

<li>If everything has failed, repeat the above search,

692

looking for regular expressions instead of exact

matches</li>

</ul>

</div>

</div>

<h1 class="postheader">TODOs</h1>

699

700

<ul>

701

<li>There's no way to do multiple dereferencing, and you

702

need to be careful what the dereferencing operation is

703

binding to in complicated scenarios</li>

704

<li>There is no way to call functions inside summary

705

strings, not even <code>const</code> ones</li>

706

<li><code>type format add</code> does not support the <code>-x</code>

707

option</li>

708

<li>Object location cannot be printed in the summary

string</li>

</ul>

</div>

</div>

</div>

</div>

</div>

</body>

</html>