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

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

[diff] [blame]

100

<p>This is done by typing

101

102

103

<b>(lldb)</b> type format add -f hex int

104

</td>

105

<table>

106

at the LLDB command line.</p>

Enrico Granata

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

[diff] [blame]

107

108

<p>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.</p>

111

112

<p>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.</p>

117

118

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

119

have a situation like the following:</p>

120

121

<p><code>typedef int A;<br>

typedef A B;<br>

typedef B C;<br>

typedef C D;<br>

</code></p>

<p>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.</p>

130

131

<p>If you simply type <br>

Enrico Granata

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

[diff] [blame]

132

133

134

<b>(lldb)</b> type format add -f hex A<br>

135

<b>(lldb)</b> type format add -f pointer C

136

</td>

137

<table>

Enrico Granata

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

[diff] [blame]

138

<br>

139

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

140

and values of type <code>D</code> as pointers.</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>

Enrico Granata

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

[diff] [blame]

147

148

149

<b>(lldb)</b> type format add -C no -f hex A<br>

150

<b>(lldb)</b> type format add -C no -f pointer C

151

</td>

152

<table>

Enrico Granata

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

[diff] [blame]

153

154

<p>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.</p>

159

160

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

161

int<br>

162

<b>(lldb)</b> fr var pointer *pointer -T<br>

163

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

164

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

165

<b>(lldb)</b> type format add -f float32[] int -p<br>

166

<b>(lldb)</b> fr var pointer *pointer -T<br>

167

(int *) pointer = 0x0000000100100180<br>

168

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

169

</code> </p>

170

171

<p>As the previous example highlights, you will most

172

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

173

174

<p>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>.<br>

179

</p>

180

181

<p>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:<br>

184

<br>

Enrico Granata

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

[diff] [blame]

185

186

187

<b>(lldb)</b> frame variable counter -f hex

188

</td>

189

<table>

Enrico Granata

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

[diff] [blame]

190

191

<p>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.</p>

195

196

<p>Finally, this is a list of formatting options available

197

out of

198

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

<tbody>

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

203

<td><b>Abbreviation</b></td>

204

<td><b>Description</b></td>

205

</tr>

206

207

<td><b>default</b></td>

208

209

</td>

210

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

format</td>

</tr>

<td><b>boolean</b></td>

215

216

<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><b>binary</b></td>

222

223

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

224

</tr>

225

226

<td><b>bytes</b></td>

227

228

<td>show the bytes one after the other<br>

229

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

230

</tr>

231

232

<td><b>bytes with ASCII</b></td>

233

234

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

235

characters<br>

236

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

237

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

238

</tr>

239

240

<td><b>character</b></td>

241

242

<td>show the bytes printed as ASCII characters<br>

243

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

244

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

245

</tr>

246

247

<td><b>printable character</b></td>

248

249

<td>show the bytes printed as printable ASCII

250

characters<br>

251

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

252

</tr>

253

254

<td><b>complex float</b></td>

255

256

<td>interpret this value as the real and imaginary

257

part of a complex floating-point number<br>

258

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

259

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

260

</tr>

261

262

<td><b>c-string</b></td>

263

264

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

265

</tr>

266

267

<td><b>signed decimal</b></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><b>enumeration</b></td>

275

276

<td>show this as an enumeration, printing the

277

value's name if available or the integer value

278

otherwise<br>

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><b>float</b></td>

290

291

<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>

294

</tr>

295

296

<td><b>octal</b></td>

297

298

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

299

</tr>

300

301

<td><b>OSType</b></td>

302

303

<td>show this as a MacOS OSType<br>

304

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

305

</tr>

306

307

<td><b>unicode16</b></td>

308

309

<td>show this as UTF-16 characters<br>

310

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

311

</tr>

312

313

<td><b>unicode32</b></td>

314

315

</td>

316

<td>show this as UTF-32 characters<br>

317

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

318

</tr>

319

320

<td><b>unsigned decimal</b></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>

325

</tr>

326

327

<td><b>pointer</b></td>

328

329

<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>show this as an array of characters<br>

338

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

</tr>

int16_t[], uint16_t[]<br>

343

int32_t[], uint32_t[]<br>

344

int64_t[], uint64_t[]<br>

uint128_t[]</b></td>

</td>

<td>show this as an array of the corresponding

349

integer type<br>

350

e.g.<br>

351

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

352

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

353

</tr>

354

355

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

356

357

</td>

358

<td>show this as an array of the corresponding

359

floating-point type<br>

360

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

361

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

362

</tr>

363

364

<td><b>complex integer</b></td>

365

366

<td>interpret this value as the real and imaginary

367

part of a complex integer number<br>

368

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

369

</tr>

370

371

<td><b>character array</b></td>

372

373

<td>show this as a character array<br>

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

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

[diff] [blame]

385

<p>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.</p>

389

<p>A different feature, type summaries, works by extracting

390

information from classes, structures, ... (<i>aggregate types</i>)

391

and arranging it in a user-defined format, as in the following example:</p>

Enrico Granata

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

[diff] [blame]

392

<p> <i>before adding a summary...</i><br>

393

394

(i_am_cool) one = {<br>

Enrico Granata

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

[diff] [blame]

395

    (int) integer = 3<br>

396

    (float) floating = 3.14159<br>

397

    (char) character = 'E'<br>

Enrico Granata

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

[diff] [blame]

398

}<br>

399

</code> <br>

400

<i>after adding a summary...</i><br>

401

402

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

403

</code> </p>

Enrico Granata

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

[diff] [blame]

404

<p>The way to obtain this effect is to bind a <i>summary string</i> to

Enrico Granata

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

[diff] [blame]

405

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

406

command.</p>

Enrico Granata

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

[diff] [blame]

407

<p>In the example, the command we type was:</p>

408

409

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

410

<b>(lldb)</b> type summary add -f "int = ${var.integer}, float = ${var.floating}, char = ${var.character%u}" i_am_cool

Enrico Granata

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

[diff] [blame]

411

</td>

412

<table>

Enrico Granata

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

[diff] [blame]

</div>

</div>

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

417

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

418

<p>While you may already have guessed a lot about the format of

419

summary strings from the above example, a detailed description

420

of their format follows.</p>

421

422

<p>Summary strings can contain plain text, control characters and

Enrico Granata

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

[diff] [blame]

423

special symbols that have access to information about

424

the current object and the overall program state.</p>

425

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

426

427

character.</p>

428

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

429

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

430

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

431

<p>Basically, all the variables described in <a

432

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

433

are accepted. Also acceptable are the control characters

434

and scoping features described in that page.

435

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

436

become acceptable symbols in this scenario.</p>

437

<p>The simplest thing you can do is grab a member variable

438

of a class or structure by typing its <i>expression

439

path</i>. In the previous example, the expression path

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

440

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

441

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

Enrico Granata

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

[diff] [blame]

442

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

443

is a placeholder token replaced with whatever variable

444

is being displayed).</p>

445

<p>If you have code like the following: <br>

446

<code> struct A {<br>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

447

    int x;<br>

448

    int y;<br>

Enrico Granata

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

[diff] [blame]

449

};<br>

450

struct B {<br>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

451

    A x;<br>

452

    A y;<br>

453

    int z;<br>

Enrico Granata

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

[diff] [blame]

454

};<br>

455

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

456

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

457

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

458

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

459

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

460

<p>As you could be using a summary string for both

461

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

462

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

463

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

464

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

465

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

466

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

467

were: <code><br>

468

struct B {<br>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

469

    A *x;<br>

470

    A y;<br>

471

    int z;<br>

Enrico Granata

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

[diff] [blame]

472

};<br>

473

</code> </p>

474

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

475

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

476

hinted above, the rationale for this choice is that

477

waiving this distinction enables one to write a summary

478

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

479

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

480

summary string is mostly about extracting nested

481

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

482

good as the object itself for the purpose.</p>

483

<p>Of course, you can have multiple entries in one summary

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

484

string, as shown in the previous example.</p>

Enrico Granata

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

[diff] [blame]

485

<p>As you can see, the last expression path also contains

486

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

487

in the actual member variable name. The symbol is

488

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

489

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

490

followed by any one format name or abbreviation from the

491

above table after an expression path, the resulting

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

492

object will be displyed using the chosen format (this is

493

applicable to non-aggregate types only, with a few

494

special exceptions discussed below). </p>

Enrico Granata

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

[diff] [blame]

495

<p>There are two more special format symbols that you can

496

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

497

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

498

summary strings for the type of the object referred by

499

the expression path and instead print the object's

500

value. The second is only applicable to Objective-C

501

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

502

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

503

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

504

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

505

obtained, nothing will be displayed.</p>

506

<p>As previously said, pointers and values are treated the

507

same way when getting to their members in an expression

508

path. However, if your expression path leads to a

509

pointer, LLDB will not automatically dereference it. In

510

order to obtain The deferenced value for a pointer, your

511

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

512

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

513

to dereference pointers along your way, the

514

dereferencing symbol only applies to the result of the

515

whole expression path traversing. <br>

516

e.g. <code> <br>

517

518

(Couple) c = {<br>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

519

    (SimpleWithPointers) sp = {<br>

520

        (int *) x = 0x00000001001000b0<br>

521

        (float *) y = 0x00000001001000c0<br>

522

        (char *) z = 0x00000001001000d0 "X"<br>

523

    }<br>

524

    (Simple *) s = 0x00000001001000e0<br>

Enrico Granata

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

[diff] [blame]

525

}<br>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

526

</code><br>

527

528

If one types the following commands:

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

Enrico Granata

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

[diff] [blame]

533

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

534

${*var.s}" Couple<br>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

535

<b>(lldb)</b> type summary add -c -p Simple<br>

</td>

the output becomes: <br><code>

540

Enrico Granata

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

[diff] [blame]

541

542

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

543

= (x=9, y=9.99, z='X')<br>

544

</code> </p>

545

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

546

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

547

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

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

548

one line, as shown in the summary for object Simple.</p>

549

<p> We are using the <code>-p</code> flag here to show that

550

aggregate types can be dereferenced as well as basic types.

551

The following command sequence would work just as well and

552

produce the same output:

553

554

555

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

556

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

557

${var.s}" Couple<br>

558

<b>(lldb)</b> type summary add -c Simple<br>

559

</td>

560

Enrico Granata

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

[diff] [blame]

</div>

</div>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

564

<h1 class="postheader">Bitfields and array syntax</h1>

Enrico Granata

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

[diff] [blame]

565

Enrico Granata

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

[diff] [blame]

566

<p>Sometimes, a basic type's value actually represents

567

several different values packed together in a bitfield.

568

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

569

them. Hexadecimal display can help, but if the bits

570

actually span byte boundaries, the help is limited.

571

Binary view would show it all without ambiguity, but is

572

often too detailed and hard to read for real-life

573

scenarios. To cope with the issue, LLDB supports native

574

bitfield formatting in summary strings. If your

575

expression paths leads to a so-called <i>scalar type</i>

576

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

577

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

578

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

579

display them in any format you like. The syntax is

580

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

581

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

582

e.g. <br>

583

<code> <b>(lldb)</b> fr var float_point<br>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

584

(float) float_point = -3.14159<br> </code>

585

586

587

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

Enrico Granata

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

[diff] [blame]

588

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

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

float

</td>

<code>

Enrico Granata

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

[diff] [blame]

594

<b>(lldb)</b> fr var float_point<br>

595

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

596

0x00000080 Mantissa: 4788184<br>

597

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

598

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

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

599

extracting bitfields out of a float object.</p>

600

601

<p> As far as the syntax is concerned, it looks

602

much like the normal C array syntax, but also allows you

603

to specify 2 indices, separated by a - symbol (a range).

604

Ranges can be given either with the lower or the higher index

605

first, and range extremes are always included in the bits extracted. </p>

606

607

<p>LLDB also allows to use a similar syntax to display

Enrico Granata

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

[diff] [blame]

608

array members inside a summary string. For instance, you

609

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

610

more compact notation than the default, and then just

611

delve into individual array members that prove

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

612

interesting to your debugging task. You can tell

613

LLDB to format arrays in special ways, possibly

614

independent of the way the array members' datatype is formatted. <br>

Enrico Granata

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

[diff] [blame]

615

e.g. <br>

616

<code> <b>(lldb)</b> fr var sarray<br>

617

(Simple [3]) sarray = {<br>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

    [0] = {<br>

        x = 1<br>

        y = 2<br>

        z = '\x03'<br>

    }<br>

    [1] = {<br>

        x = 4<br>

        y = 5<br>

        z = '\x06'<br>

    }<br>

    [2] = {<br>

        x = 7<br>

        y = 8<br>

        z = '\t'<br>

    }<br>

}<br></code>

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

[3]"

</td>

<code>

Enrico Granata

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

[diff] [blame]

643

<b>(lldb)</b> fr var sarray<br>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

644

(Simple [3]) sarray = [1,4,7]<br></code></p>

645

646

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

Enrico Granata

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

[diff] [blame]

647

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

648

string to every element of the array</i>. Here, we are

649

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

650

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

651

If you find some of those integers anomalous, you can

652

then inspect that one item in greater detail, without

653

the array format getting in the way: <br>

654

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

655

(Simple) sarray[1] = {<br>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

656

    x = 4<br>

657

    y = 5<br>

658

    z = '\x06'<br>

Enrico Granata

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

[diff] [blame]

659

}<br>

660

</code> </p>

661

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

662

array range by using the same syntax used to extract bit

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

for bitfields:

<b>(lldb)</b> type summary add -f "${var[1-2].x}" "Simple

[3]"

</td>

<code>

<b>(lldb)</b> fr var sarray<br>

672

(Simple [3]) sarray = [4,7]<br></code></p>

673

Enrico Granata

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

[diff] [blame]

674

<p>The same logic works if you are printing a pointer

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

675

instead of an array, however in this latter case, the empty

676

square brackets operator <code>[]</code>

Enrico Granata

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

[diff] [blame]

677

cannot be used and you need to give exact range limits.</p>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

678

679

<p>In general, LLDB needs the square brackets operator <code>[]</code> in

680

order to handle arrays and pointers correctly, and for pointers it also

681

needs a range. However, a few special cases are defined to make your life easier:

682

<ul>

683

<li>you can print a 0-terminated string (<i>C-string</i>) using the %s format,

684

omitting square brackets, as in:

685

686

687

<b>(lldb)</b> type summary add -f "${var%s}" "char *"

</td>

<table>

This works for <code>char*</code> and <code>char[]</code> objects, and uses the

692

<code>\0</code> terminator

693

when possible to terminate the string, instead of relying on array length.

</li> </ul>

<ul>

<li>anyone of the array formats (<code>int8_t[]</code>,

699

<code>float32{}</code>, ...), and the <code>y</code>, <code>Y</code>

700

and <code>a</code> formats

701

work to print an array of a non-aggregate

702

type, even if square brackets are omitted.

703

704

705

<b>(lldb)</b> type summary add -f "${var%int32_t[]}" "int [10]"

</td>

<table>

</ul>

This feature, however, is not enabled for pointers because there is no

711

way for LLDB to detect the end of the pointed data.

712

<br>

713

This also does not work for other formats (e.g. <code>boolean</code>), and you must

714

specify the square brackets operator to get the expected output.

</p>

</div>

</div>

<h1 class="postheader">Regular expression typenames</h1>

</div>

</div>

Enrico Granata

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

[diff] [blame]

725

<p>As you noticed, in order to associate the custom

726

summary string to the array types, one must give the

727

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

728

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

729

730

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

731

[12]</code>, ...</p>

732

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

733

treated as regular expressions instead of type names.

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

734

This would let you rephrase the above example

735

for arrays of type <code>Simple [3]</code> as: <br>

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

740

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

</td>

<table>

<code>

Enrico Granata

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

[diff] [blame]

745

<b>(lldb)</b> fr var sarray<br>

746

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

747

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

748

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

749

objects. </p>

750

<p>While this feature is mostly useful for arrays, you

751

could also use regular expressions to catch other type

752

sets grouped by name. However, as regular expression

753

matching is slower than normal name matching, LLDB will

754

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

755

when this fails, will it resort to regular expression

756

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

757

cascading summary, this will be preferred over any

758

regular expression match for your type itself.</p>

759

</div>

760

</div>

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

761

762

763

<h1 class="postheader">Named summaries</h1>

764

765

<p>For a given datatype, there may be different meaningful summary

766

representations. However, currently, only one summary can be associated

767

to a given datatype. If you need to temporarily override the association

768

for a variable, without changing the summary string bound to the datatype,

769

you can use named summaries.</p>

770

771

<p>Named summaries work by attaching a name to a summary string when creating

772

it. Then, when there is a need to attach the summary string to a variable, the

773

<code>frame variable</code> command, supports a <code>--summary</code> option

774

that tells LLDB to use the named summary given instead of the default one.</p>

<b>(lldb)</b> type summary add -f "x=${var.integer}" --name NamedSummary

</td>

<table>

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

783

<b>(lldb)</b> fr var one --summary NamedSummary<br>

784

(i_am_cool) one = x=3<br>

785

</code> </p>

786

Enrico Granata

f7a9b14

2011-07-15 02:26:42 +0000

[diff] [blame^]

787

<p>When defining a named summmary, binding it to one or more types becomes optional.

788

Even if you bind the named summary to a type, and later change the summary string

789

for that type, the named summary will not be changed by that. You can delete

790

named summaries by using the <code>type summary delete</code> command, as if the

791

summary name was the datatype that the summary is applied to</p>

792

793

<p>A summary attached to a variable using the </code>--summary</code> option,

794

has the same semantics that a custom format attached using the <code>-f</code>

795

option has: it stays attached till you attach a new one, or till you let

796

your program run again.</p>

797

Enrico Granata

2011-07-13 00:00:57 +0000

[diff] [blame]

</div>

</div>

Enrico Granata

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

[diff] [blame]

802

803

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

804

805

<p>While the rules for finding an appropriate format for a

806

type are relatively simple (just go through typedef

807

hierarchies), summaries follow a more complicated

808

process in finding the right summary string for a

809

variable. Namely, what happens is:</p>

810

<ul>

811

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

812

use it</li>

813

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

814

for the pointee type that does not skip pointers, use

815

it</li>

816

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

817

summary for the pointee type that does not skip

818

references, use it</li>

819

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

820

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

821

...)</li>

822

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

823

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

824

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

825

classes, look at the virtual base classes (and bases

826

of bases, ...)</li>

827

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

Enrico Granata

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

[diff] [blame]

828

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

829

the compiler has not emitted enough information. If the

830

required information to traverse typedef hierarchies is

831

missing, type cascading will not work. The

832

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

833

part of the LLVM project, emits the correct debugging

834

information for LLDB to cascade)</li>

Enrico Granata