Blame - lldb/www/tutorial.html - toolchain/llvm-project

1.1: where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405, address = 0x0000000100010d5b, resolved, hit count = 0

269

</tt></pre>

270

271

<p>Note that setting a breakpoint creates a <i>logical</i> breakpoint, which could

272

resolve to one or more <i>locations</i>. For instance, break by selector would

273

set a breakpoint on all the methods that implement that selector in the classes in

274

your program. Similarly, a file and line breakpoint might result in multiple

275

locations if that file and line were inlined in different places in your code.</p>

276

277

<p>The logical breakpoint has an integer id, and it's locations have an

278

id within their parent breakpoint (the two are joined by a ".",

279

e.g. 1.1 in the example above.) </p>

280

281

<p>Also the logical breakpoints remain <i>live</i> so that if another shared library

282

were to be loaded that had another implementation of the

283

"<code>alignLeftEdges:</code>" selector, the new location would be added to

284

breakpoint 1 (e.g. a "1.2" breakpoint would be set on the newly loaded

285

selector).</p>

286

287

<p>The other piece of information in the breakpoint listing is whether the

288

breakpoint location was <i>resolved</i> or not. A location gets resolved when

289

the file address it corresponds to gets loaded into the program you are

290

debugging. For instance if you set a breakpoint in a shared library that

291

then gets unloaded, that breakpoint location will remain, but it will no

292

longer be <i>resolved</i>.</p>

293

294

<p>One other thing to note for gdb users is that lldb acts like gdb with:</p>

295

296

<code>

297

(gdb) set breakpoint pending on

298

</code>

299

300

<p>That is, lldb will always make a breakpoint from your specification, even

301

if it couldn't find any locations that match the specification. You can tell

302

whether the expression was resolved or not by checking the locations field

303

in "breakpoint list", and we report the breakpoint as "pending" when you

304

set it so you can tell you've made a typo more easily, if that was indeed

305

the reason no locations were found:</p>

306

307

<code>

308

(lldb) breakpoint set --file foo.c --line 12

309

<br>Breakpoint created: 2: file ='foo.c', line = 12, locations = 0 (pending)

310

<br>WARNING: Unable to resolve breakpoint to any actual locations.

311

</code>

312

313

<p>You can delete, disable, set conditions and ignore counts either on all the

314

locations generated by your logical breakpoint, or on any one of the particular locations

315

your specification resolved to. For instance if we wanted to add a command

316

to print a backtrace when we hit this breakpoint we could do:</p>

317

318

<code>

319

(lldb) breakpoint command add 1.1

320

<br>Enter your debugger command(s). Type 'DONE' to end.

<br>> bt

<br>> DONE

</code>

<p>By default, the <code> breakpoint command add</code> command takes lldb command line commands.

326

You can also specify this explicitly by passing the "<code>--command</code>" option.

327

Use "<code>--script</code>" if you want to implement your breakpoint command using the Python script instead.</p>

328

329

<p>This is an convenient point to bring up another feature of the lldb command help. Do:</p>

330

331

<code>

332

(lldb) help break command add

333

<br>Add a set of commands to a breakpoint, to be executed whenever the breakpoint is hit.

334

<br>

335

<br>Syntax: breakpoint command add <cmd-options> <breakpt-id>

<br> etc...

</code>

<p>When you see arguments to commands specified in the Syntax in angle

340

brackets like <code><breakpt-id></code>, that indicates that

341

that is some common argument type that you can get further help on from the command system.

342

So in this case you could do:</p>

343

344

<code>

345

(lldb) help <breakpt-id>

346

<br><breakpt-id> -- Breakpoint ID's consist major and minor numbers; the major

<br> etc...

</code>

</div>

<h1 class ="postheader">Setting watchpoints</h1>

355

356

357

<p>In addition to breakpoints, you can use <code>help watchpoint</code>

358

to see all the commands for watchpoint manipulations. For instance, we might do the following to watch

359

a variable called 'global' for write operation, but only stop if the condition '(global==5)' is true:</p>

360

361

<pre><tt>(lldb) watch set var global

362

Watchpoint created: Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w

363

declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12'

364

(lldb) watch modify -c '(global==5)'

365

(lldb) watch list

366

Current watchpoints:

367

Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w

368

declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12'

369

condition = '(global==5)'

370

(lldb) c

371

Process 15562 resuming

372

(lldb) about to write to 'global'...

373

Process 15562 stopped and was programmatically restarted.

374

Process 15562 stopped and was programmatically restarted.

375

Process 15562 stopped and was programmatically restarted.

376

Process 15562 stopped and was programmatically restarted.

377

Process 15562 stopped

378

* thread #1: tid = 0x1c03, 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16, stop reason = watchpoint 1

379

frame #0: 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16

380

13

381

14 static void modify(int32_t &var) {

15 ++var;

-> 16 }

17

18 int main(int argc, char** argv) {

386

19 int local = 0;

387

(lldb) bt

388

* thread #1: tid = 0x1c03, 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16, stop reason = watchpoint 1

389

frame #0: 0x0000000100000ef5 a.out`modify + 21 at main.cpp:16

390

frame #1: 0x0000000100000eac a.out`main + 108 at main.cpp:25

391

frame #2: 0x00007fff8ac9c7e1 libdyld.dylib`start + 1

392

(lldb) frame var global

(int32_t) global = 5

(lldb) watch list -v

Current watchpoints:

Watchpoint 1: addr = 0x100001018 size = 4 state = enabled type = w

397

declare @ '/Volumes/data/lldb/svn/ToT/test/functionalities/watchpoint/watchpoint_commands/condition/main.cpp:12'

398

condition = '(global==5)'

399

hw_index = 0 hit_count = 5 ignore_count = 0

(lldb) </tt></pre>

</div>

<h1 class ="postheader">Starting or attaching to your Program</h1>

406

407

408

<p>To launch a program in lldb we use the "<code>process launch</code>" command or

409

one of its built in aliases:</p>

410

411

<code>

412

(lldb) process launch

<br>(lldb) run

<br>(lldb) r

</code>

<p>You can also attach to a process by process ID or process name.

418

When attaching to a process by name, lldb also supports the "<code>--waitfor</code>" option which waits for the

419

next process that has that name to show up, and attaches to it</p>

420

421

<code>

422

(lldb) process attach --pid 123

423

<br>(lldb) process attach --name Sketch

424

<br>(lldb) process attach --name Sketch --waitfor

425

</code>

426

427

<p>After you launch or attach to a process, your process might stop

428

somewhere:</p>

429

<code>

430

(lldb) process attach -p 12345

431

<br>Process 46915 Attaching

432

<br>Process 46915 Stopped

433

<br>1 of 3 threads stopped with reasons:

434

<br>* thread #1: tid = 0x2c03, 0x00007fff85cac76a, where = libSystem.B.dylib`__getdirentries64 + 10, stop reason = signal = SIGSTOP, queue = com.apple.main-thread

</code>

<p>Note the line that says "<code>1 of 3 threads stopped with reasons:</code>" and the

439

lines that follow it. In a multi-threaded environment it is very

440

common for more than one thread to hit your breakpoint(s) before the

441

kernel actually returns control to the debugger. In that case, you

442

will see all the threads that stopped for some interesting reason

443

listed in the stop message.</p>

</div>

<h1 class ="postheader">Controlling your Program</h1>

<p>After launching, we can continue until we hit our breakpoint. The primitive

454

commands for process control all exist under the "thread" command:</p>

455

456

<code>

457

(lldb) thread continue

458

<br>Resuming thread 0x2c03 in process 46915

459

<br>Resuming process 46915

<br>(lldb)

</code>

<p>At present you can only operate on one thread at a time, but the

464

design will ultimately support saying "step over the function in

465

Thread 1, and step into the function in Thread 2, and continue Thread

466

3" etc. When we eventually support keeping some threads running while

467

others are stopped this will be particularly important. For

468

convenience, however, all the stepping commands have easy aliases.

469

So "thread continue" is just "c", etc.</p>

470

471

<p>The other program stepping commands are pretty much the same as in gdb.

472

You've got:</p>

473

474

<pre><tt>(lldb) thread step-in // The same as gdb's "step" or "s"

475

(lldb) thread step-over // The same as gdb's "next" or "n"

476

(lldb) thread step-out // The same as gdb's "finish" or "f"

477

</tt></pre>

478

479

<p>By default, lldb does defined aliases to all common gdb process control

480

commands ("<code>s</code>", "<code>step</code>", "<code>n</code>", "<code>next</code>", "<code>finish</code>").

481

If we have missed any, please add them to your <code>~/.lldbinit</code> file

482

using the "<code>command alias</code>" command.

483

484

<p>lldb also supported the <i>step by instruction</i> versions:</p>

485

<pre><tt>(lldb) thread step-inst // The same as gdb's "stepi" / "si"

486

(lldb) thread step-over-inst // The same as gdb's "nexti" / "ni"

487

</tt></pre>

488

489

<p>Finally, lldb has a <i>run until line or frame exit</i> stepping mode:</p>

490

491

<code>

492

(lldb) thread until 100

493

</code>

494

495

<p>This command will run the thread in the current frame till it reaches line 100 in

496

this frame or stops if it leaves the current frame. This is a pretty

497

close equivalent to gdb's "<code>until</code>" command.</p>

498

Ed Maste

279ebe2

2014-09-14 00:56:13 +0000

[diff] [blame]

499

<p>A process, by default, will share the lldb terminal with the inferior

Joerg Sonnenberger

340a175

2013-09-25 10:37:32 +0000

[diff] [blame]

500

process. When in this mode, much like when debugging with gdb, when

501

the process is running anything you type will go to the STDIN of the

502

inferior process. To interrupt your inferior program, type CTRL+C.</p>

503

504

<p>If you attach to a process, or launch a process with the "<code>--no-stdin</code>"

505

option, the command interpreter is always available to enter commands. This

506

might be a little disconcerting to gdb users when always have an <code>(lldb)</code>

507

prompt. This allows you to set a breakpoint, etc without having to explicitly interrupt

508

the program you are debugging:</p>

509

510

<code>

511

(lldb) process continue

512

<br>(lldb) breakpoint set --name stop_here

513

</code>

514

515

<p>There are many commands that won't work while running, and the command

516

interpreter should do a good job of letting you know when this is the

517

case. If you find any instances where the command interpreter isn't

518

doing its job, please file a bug. This way of operation will set us

519

up for a future debugging mode called <i>thread centric debugging</i>.

520

This mode will allow us to run all threads and only stop the threads

521

that are at breakpoints or have exceptions or signals.</p>

522

523

<p>The commands that currently work while running include

524

interrupting the process to halt execution ("<code>process interrupt</code>"),

525

getting the process status ("<code>process status</code>"),

526

breakpoint setting and clearing ("<code> breakpoint [set|clear|enable|disable|list] ...</code>"),

527

and memory reading and writing ("<code> memory [read|write] ...</code>").

528

</p>

529

530

<p>The question of disabling stdio when running brings up a good opportunity to

531

show how to set debugger properties in general.

532

If you always want to run in the <code>--no-stdin</code> mode, you can set this

Adrian McCarthy

c7fd5ff

2015-03-26 16:53:34 +0000

[diff] [blame]

533

as a generic process property using the lldb "<code>settings</code>" command,

Joerg Sonnenberger

340a175

2013-09-25 10:37:32 +0000

[diff] [blame]

534

which is equivalent to gdb's "<code>set</code>" command. For instance,

535

in this case you would say:</p>

536

537

<code>

538

(lldb) settings set target.process.disable-stdio true

539

</code>

540

541

<p>Over time, gdb's "<code>set</code> command became a wilderness of disordered options,

542

so that there were useful options that even experienced gdb users didn't know about

543

because they were too hard to find. We tried to organize the settings hierarchically

544

using the structure of the basic entities in the debugger. For the most part anywhere

545

you can specify a setting on a generic entity (threads, for example) you can also apply

546

the option to a particular instance, which can also be convenient at times.

547

You can view the available settings with "<code>settings list</code>" and

548

there is help on the settings command explaining how it works more generally.</p>

</div>

<h1 class ="postheader">Examining Thread State</h1>

555

556

557

<p>Once you've stopped, lldb will choose a current thread, usually the

558

one that stopped "for a reason", and a current frame in that thread (on stop this is always the bottom-most frame).

559

Many the commands for inspecting state work on this current

560

thread/frame.</p>

561

562

<p>To inspect the current state of your process, you can start with the

563

threads:</p>

564

565

<pre><tt>(lldb) thread list

566

Process 46915 state is Stopped

567

* thread #1: tid = 0x2c03, 0x00007fff85cac76a, where = libSystem.B.dylib`__getdirentries64 + 10, stop reason = signal = SIGSTOP, queue = com.apple.main-thread

568

thread #2: tid = 0x2e03, 0x00007fff85cbb08a, where = libSystem.B.dylib`kevent + 10, queue = com.apple.libdispatch-manager

569

thread #3: tid = 0x2f03, 0x00007fff85cbbeaa, where = libSystem.B.dylib`__workq_kernreturn + 10

570

</tt></pre>

571

572

<p>The * indicates that Thread 1 is the current thread. To get a

573

backtrace for that thread, do:</p>

574

575

<pre><tt>(lldb) thread backtrace

576

thread #1: tid = 0x2c03, stop reason = breakpoint 1.1, queue = com.apple.main-thread

577

frame #0: 0x0000000100010d5b, where = Sketch`-[SKTGraphicView alignLeftEdges:] + 33 at /Projects/Sketch/SKTGraphicView.m:1405

578

frame #1: 0x00007fff8602d152, where = AppKit`-[NSApplication sendAction:to:from:] + 95

579

frame #2: 0x00007fff860516be, where = AppKit`-[NSMenuItem _corePerformAction] + 365

580

frame #3: 0x00007fff86051428, where = AppKit`-[NSCarbonMenuImpl performActionWithHighlightingForItemAtIndex:] + 121

581

frame #4: 0x00007fff860370c1, where = AppKit`-[NSMenu performKeyEquivalent:] + 272

582

frame #5: 0x00007fff86035e69, where = AppKit`-[NSApplication _handleKeyEquivalent:] + 559

583

frame #6: 0x00007fff85f06aa1, where = AppKit`-[NSApplication sendEvent:] + 3630

584

frame #7: 0x00007fff85e9d922, where = AppKit`-[NSApplication run] + 474

585

frame #8: 0x00007fff85e965f8, where = AppKit`NSApplicationMain + 364

586

frame #9: 0x0000000100015ae3, where = Sketch`main + 33 at /Projects/Sketch/SKTMain.m:11

587

frame #10: 0x0000000100000f20, where = Sketch`start + 52

588

</tt></pre>

589

590

<p>You can also provide a list of threads to backtrace, or the keyword

591

"all" to see all threads:</p>

592

593

<code>

594

(lldb) thread backtrace all

595

</code>

596

597

<p>You can select the current thread, which will be used by default in all the commands in

598

the next section, with the "thread select" command:</p>

599

600

<code>

601

(lldb) thread select 2

602

</code>

603

604

<p>where the thread index is just the one shown in the "<code>thread list</code>&quot listing.

</div>

<h1 class ="postheader">Examining Stack Frame State</h1>

<p>The most convenient way to inspect a frame's arguments and local variables is to use the "<code>frame variable</code>" command:</p>

615

616

<code>

617

(lldb) frame variable

618

<br>self = (SKTGraphicView *) 0x0000000100208b40

619

<br>_cmd = (struct objc_selector *) 0x000000010001bae1

620

<br>sender = (id) 0x00000001001264e0

621

<br>selection = (NSArray *) 0x00000001001264e0

622

<br>i = (NSUInteger) 0x00000001001264e0

623

<br>c = (NSUInteger) 0x00000001001253b0

624

</code>

625

626

<p>As you see above, if you don't specify any variable names, all arguments

627

and locals will be shown. If you call "<code>frame variable</code>"

628

passing in the names of a particular local(s), only those variables

629

will be printed. For instance:

</p>

<code>

(lldb) frame variable self

634

<br>(SKTGraphicView *) self = 0x0000000100208b40

635

</code>

636

637

<p>You can also pass in a path to some subelement of one of the available locals,

638

and that sub-element will be printed. For instance:

</p>

<code>

<br>(lldb) frame variable self.isa

643

<br>(struct objc_class *) self.isa = 0x0000000100023730

644

</code>

645

646

<p>The "<code>frame variable</code>" command is not a full expression

647

parser but it does support a few simple operations like &, *, ->, [] (no overloaded

648

operators). The array brackets can be used on pointers to treat pointers

as arrays:</p>

<code>

(lldb) frame variable *self

653

<br>(SKTGraphicView *) self = 0x0000000100208b40

654

<br>(NSView) NSView = {

655

<br>(NSResponder) NSResponder = {

656

<br>...

657

<br>

658

<br>(lldb) frame variable &self

659

<br>(SKTGraphicView **) &self = 0x0000000100304ab

660

<br>

661

<br>(lldb) frame variable argv[0]

662

<br>(char const *) argv[0] = 0x00007fff5fbffaf8 "/Projects/Sketch/build/Debug/Sketch.app/Contents/MacOS/Sketch"

663

</code>

664

665

<p>The frame variable command will also perform "object printing" operations on

666

variables (currently we only support ObjC printing, using the object's "description" method.

667

Turn this on by passing the -o flag to frame variable:</p>

668

669

<code>

670

(lldb) frame variable -o self

671

(SKTGraphicView *) self = 0x0000000100208b40 <SKTGraphicView: 0x100208b40>

672

</code>

673

674

<p>You can select another frame to view with the "<code>frame select</code>" command</p>

675

676

<code>

677

(lldb) frame select 9

678

<br>frame #9: 0x0000000100015ae3, where = Sketch`function1 + 33 at /Projects/Sketch/SKTFunctions.m:11

679

</code>

680

681

<p>You can also move up and down the stack by passing the "<code>--relative</code>" ("<code>-r</code>")

682

option. And we have built-in aliases "<code>u</code>" and "<code>d</code>" which

683

behave like their gdb equivalents.

684

685

<p>If you need to view more complex data or change program data, you can

686

use the general "expression" command. It takes an expression and

687

evaluates it in the scope of the currently selected frame. For instance:</p>

<code>

(lldb) expr self

<br>$0 = (SKTGraphicView *) 0x0000000100135430

692

<br>(lldb) expr self = 0x00

693

<br>$1 = (SKTGraphicView *) 0x0000000000000000

694

<br>(lldb) frame var self

695

<br>(SKTGraphicView *) self = 0x0000000000000000

696

</code>

697

698

<p>You can also call functions:</p>

699

700

<code>

701

(lldb) expr (int) printf ("I have a pointer 0x%llx.\n", self)

702

<br>$2 = (int) 22

703

<br>I have a pointer 0x0.

704

</code>

705

706

<p>As I said above, "expression" is one of the "raw" commands. So

707

you don't have to quote your whole expression, nor backslash protect quotes,

708

etc...</p>

709

710

<p>Finally, the results of the expressions are stored in persistent variables

711

(of the form $[0-9]+) that you can use in further expressions, like:</p>

712

713

<code>

714

(lldb) expr self = $0

715

<br>$4 = (SKTGraphicView *) 0x0000000100135430

</code>

<p>

</div>

</div>

</div>

</div>

</div>

</body>

</html>