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

Enrico Granata

86e7c3e

2011-07-12 22:56:10 +0000

[diff] [blame^]

100

This is done by typing

101

102

103

(lldb) type format add -f hex int

104

</td>

105

<table>

106

at the LLDB command line.

Enrico Granata

ff78238

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

[diff] [blame]

107

108

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

109

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

110

types to which you want the new format applied.

111

112

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

113

for a numeric type that you know represents something

114

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

115

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

116

format add</code> with the name alias.

117

118

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

119

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

128

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

129

untouched for other types.

130

131

If you simply type

Enrico Granata

86e7c3e

2011-07-12 22:56:10 +0000

[diff] [blame^]

132

133

134

(lldb) type format add -f hex A

135

(lldb) type format add -f pointer C

136

</td>

137

<table>

Enrico Granata

ff78238

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

[diff] [blame]

138

139

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

140

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

141

142

This is because by default LLDB cascades

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:

Enrico Granata

86e7c3e

2011-07-12 22:56:10 +0000

[diff] [blame^]

147

148

149

(lldb) type format add -C no -f hex A

150

(lldb) type format add -C no -f pointer C

151

</td>

152

<table>

Enrico Granata

ff78238

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

[diff] [blame]

153

154

Two additional options that you will want to look at

155

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

156

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

157

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

158

respectively.

159

160

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

161

int

162

(lldb) fr var pointer *pointer -T

163

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

164

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

165

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

166

(lldb) fr var pointer *pointer -T

167

(int *) pointer = 0x0000000100100180

168

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

169

</code>

170

171

As the previous example highlights, you will most

172

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

173

174

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

175

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

176

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

177

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

178

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

179

180

181

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

182

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

183

type untouched, you can simply type:

184

Enrico Granata

86e7c3e

2011-07-12 22:56:10 +0000

[diff] [blame^]

185

186

187

(lldb) frame variable counter -f hex

188

</td>

189

<table>

Enrico Granata

ff78238

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

[diff] [blame]

190

191

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

192

as an hexadecimal number, and will keep showing it this

193

way until you either pick a different format or till you

194

let your program run again.

195

196

Finally, this is a list of formatting options available

197

out of

198

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

<tbody>

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

203

<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

217

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

229

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

230

</tr>

231

232

<td>bytes with ASCII</td>

233

234

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

235

characters

236

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

237

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

</tr>

<td>character</td>

<td>show the bytes printed as ASCII characters

243

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

244

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

245

</tr>

246

247

<td>printable character</td>

248

249

<td>show the bytes printed as printable ASCII

250

characters

251

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

252

</tr>

253

254

<td>complex float</td>

255

256

<td>interpret this value as the real and imaginary

257

part of a complex floating-point number

258

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

259

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

</tr>

<td>c-string</td>

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

265

</tr>

266

267

<td>signed decimal</td>

268

269

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

270

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

277

value's name if available or the integer value

278

otherwise

279

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

</tr>

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

285

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

292

not perform a cast, it simply interprets the bytes

293

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

304

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

</tr>

<td>unicode16</td>

<td>show this as UTF-16 characters

310

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

</tr>

<td>unicode32</td>

<td>

</td>

<td>show this as UTF-32 characters

317

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

318

</tr>

319

320

<td>unsigned decimal</td>

321

322

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

323

does not perform a cast, it simply shows the bytes

324

as unsigned integer)</td>

</tr>

<td>pointer</td>

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

330

really a pointer, the resulting address will

331

probably be invalid)</td>

</tr>

<td>

</td>

<td>show this as an array of characters

338

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

339

</tr>

340

341

<td>int8_t[], uint8_t[]

342

int16_t[], uint16_t[]

343

int32_t[], uint32_t[]

344

int64_t[], uint64_t[]

uint128_t[]</td>

<td>

</td>

<td>show this as an array of the corresponding

349

integer type

350

e.g.

351

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

352

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

353

</tr>

354

355

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

356

<td>

357

</td>

358

<td>show this as an array of the corresponding

359

floating-point type

360

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

361

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

362

</tr>

363

364

<td>complex integer</td>

365

366

<td>interpret this value as the real and imaginary

367

part of a complex integer number

368

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

369

</tr>

370

371

<td>character array</td>

372

373

<td>show this as a character array

374

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

375

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

</tr>

</tbody>

</table>

</div>

</div>

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

384

Enrico Granata

86e7c3e

2011-07-12 22:56:10 +0000

[diff] [blame^]

385

Type formats work by showing a different kind of display for

386

the value of a variable. However, they only work for basic types.

387

When you want to display a class or struct in a custom format, you

388

cannot do that using formats.

389

A different feature, type summaries, works by extracting

390

information from classes, structures, ... (aggregate types)

391

and arranging it in a user-defined format, as in the following example:

Enrico Granata

ff78238

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

[diff] [blame]

392

before adding a summary...

393

<code> (lldb) fr var -T one

394

(i_am_cool) one = {

Enrico Granata

86e7c3e

2011-07-12 22:56:10 +0000

[diff] [blame^]

395

(int) integer = 3

396

(float) floating = 3.14159

397

(char) character = 'E'

Enrico Granata

ff78238

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

[diff] [blame]

398

}

399

</code>

400

after adding a summary...

401

<code> (lldb) fr var one

402

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

403

</code>

Enrico Granata

86e7c3e

2011-07-12 22:56:10 +0000

[diff] [blame^]

404

The way to obtain this effect is to bind a summary string to

Enrico Granata

ff78238

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

[diff] [blame]

405

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

406

command.

Enrico Granata

86e7c3e

2011-07-12 22:56:10 +0000

[diff] [blame^]

407

In the example, the command we type was:

408

409

410

(lldb) frame variable counter -f hex

411

</td>

412

<table>

Enrico Granata

ff78238

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

[diff] [blame]

</div>

</div>

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

417

418

So what is the format of the summary strings? Summary

419

strings can contain plain text, control characters and

420

special symbols that have access to information about

421

the current object and the overall program state.

422

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

423

424

character.

425

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

426

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

427

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

428

Basically, all the variables described in <a

429

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

430

are accepted. Also acceptable are the control characters

431

and scoping features described in that page.

432

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

433

become acceptable symbols in this scenario.

434

The simplest thing you can do is grab a member variable

435

of a class or structure by typing its expression

436

path. In the previous example, the expression path

437

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

438

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

439

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

440

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

441

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

442

is a placeholder token replaced with whatever variable

443

is being displayed).

444

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>

455

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

456

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

457

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

458

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

459

As you could be using a summary string for both

460

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

461

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

462

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

463

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

464

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

465

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>

474

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

475

hinted above, the rationale for this choice is that

476

waiving this distinction enables one to write a summary

477

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

478

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

479

summary string is mostly about extracting nested

480

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

481

good as the object itself for the purpose.

482

Of course, you can have multiple entries in one summary

483

string. For instance, the command used to produce the

484

above summary string for i_am_cool was:

485

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

486

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

487

</code>

488

As you can see, the last expression path also contains

489

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

490

in the actual member variable name. The symbol is

491

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

492

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

493

followed by any one format name or abbreviation from the

494

above table after an expression path, the resulting

495

object will be displyed using exactly that format

496

instead of the LLDB default one.

497

There are two more special format symbols that you can

498

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

499

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

500

summary strings for the type of the object referred by

501

the expression path and instead print the object's

502

value. The second is only applicable to Objective-C

503

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

504

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

505

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

506

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

507

obtained, nothing will be displayed.

508

As previously said, pointers and values are treated the

509

same way when getting to their members in an expression

510

path. However, if your expression path leads to a

511

pointer, LLDB will not automatically dereference it. In

512

order to obtain The deferenced value for a pointer, your

513

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

514

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

515

to dereference pointers along your way, the

516

dereferencing symbol only applies to the result of the

517

whole expression path traversing.

e.g. <code>

(lldb) fr var -T c

(Couple) c = {

(SimpleWithPointers) sp = {

522

(int *) x = 0x00000001001000b0

523

(float *) y = 0x00000001001000c0

524

(char *) z = 0x00000001001000d0 "X"

525

}

526

(Simple *) s = 0x00000001001000e0

527

}

528

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

529

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

530

${*var.s}" Couple

531

(lldb) type summary add -c -p Simple

532

(lldb) fr var c

533

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

534

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

535

</code>

536

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

537

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

538

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

539

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

540

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

541

be dereferenced as well as primitive ones. The above

542

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

543

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

544

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

545

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

546

for type <code>Simple</code>.

</div>

</div>

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

551

552

What was described above are the main features that you

553

can use in summary strings. However, there are three

554

more features to them.

555

Sometimes, a basic type's value actually represents

556

several different values packed together in a bitfield.

557

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

558

them. Hexadecimal display can help, but if the bits

559

actually span byte boundaries, the help is limited.

560

Binary view would show it all without ambiguity, but is

561

often too detailed and hard to read for real-life

562

scenarios. To cope with the issue, LLDB supports native

563

bitfield formatting in summary strings. If your

564

expression paths leads to a so-called scalar type

565

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

566

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

567

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

568

display them in any format you like. The syntax is

569

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

570

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

571

e.g.

572

<code> (lldb) fr var float_point

573

(float) float_point = -3.14159

574

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

575

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

576

float

577

(lldb) fr var float_point

578

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

579

0x00000080 Mantissa: 4788184

580

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

581

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

582

extracting bitfields out of a float object. If you give

583

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

584

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

585

(extremes included) will be extracted. Ranges can be

586

specified either by giving the lower index first, or

587

higher index first (as is often customary in describing

588

packed data-type formats).

589

The second additional feature allows you to display

590

array members inside a summary string. For instance, you

591

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

592

more compact notation than the default, and then just

593

delve into individual array members that prove

594

interesting to your debugging task. You can use a

595

similar syntax to the one used for bitfields to tell

596

LLDB to format arrays in special ways.

597

e.g.

598

<code> (lldb) fr var sarray

599

(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

617

[3]"

618

(lldb) fr var sarray

619

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

620

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

621

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

622

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

623

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

624

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

625

If you find some of those integers anomalous, you can

626

then inspect that one item in greater detail, without

627

the array format getting in the way:

628

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

629

(Simple) sarray[1] = {

x = 4

y = 5

z = '\x06'

}

</code>

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

636

array range by using the same syntax used to extract bit

637

for bitfields.

638

The same logic works if you are printing a pointer

639

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

640

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

641

The third, and last, additional feature does not

642

directly apply to the summary strings themselves, but is

643

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

644

command: <code>-x</code>

645

As you noticed, in order to associate the custom

646

summary string to the array types, one must give the

647

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

648

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

649

650

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

651

[12]</code>, ...

652

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

653

treated as regular expressions instead of type names.

654

This would let you rephrase the above example as:

655

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

656

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

657

(lldb) fr var sarray

658

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

659

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

660

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

661

objects.

662

While this feature is mostly useful for arrays, you

663

could also use regular expressions to catch other type

664

sets grouped by name. However, as regular expression

665

matching is slower than normal name matching, LLDB will

666

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

667

when this fails, will it resort to regular expression

668

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

669

cascading summary, this will be preferred over any

670

regular expression match for your type itself.

</div>

</div>

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

675

676

While the rules for finding an appropriate format for a

677

type are relatively simple (just go through typedef

678

hierarchies), summaries follow a more complicated

679

process in finding the right summary string for a

680

variable. Namely, what happens is:

681

<ul>

682

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

683

use it</li>

684

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

685

for the pointee type that does not skip pointers, use

686

it</li>

687

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

688

summary for the pointee type that does not skip

689

references, use it</li>

690

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

691

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

692

...)</li>

693

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

694

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

695

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

696

classes, look at the virtual base classes (and bases

697

of bases, ...)</li>

698

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

Enrico Granata

86e7c3e

2011-07-12 22:56:10 +0000

[diff] [blame^]

699

typedef hierarchy (LLDB might not be able to do this if

700

the compiler has not emitted enough information. If the

701

required information to traverse typedef hierarchies is

702

missing, type cascading will not work. The

703

<a href="http://clang.llvm.org/">clang compiler</a>,

704

part of the LLVM project, emits the correct debugging

705

information for LLDB to cascade)</li>

Enrico Granata

ff78238

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

[diff] [blame]

706

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

707

looking for regular expressions instead of exact

matches</li>

</ul>

</div>

</div>

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

714

715

<ul>

716

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

717

need to be careful what the dereferencing operation is

718

binding to in complicated scenarios</li>

719

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

720

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

721

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

722

option</li>

723

<li>Object location cannot be printed in the summary

string</li>

</ul>

</div>

</div>

</div>

</div>

</div>

</body>

</html>