LLDB Quick Start Guide

Using LLDB as a Standalone Debugger

This chapter describes the workflow and operations in a basic Terminal debugging session. Where appropriate, LLDB operations are compared to similar GDB operations.

Most of the time, you use the LLDB debugger indirectly through the Xcode debugging features, and you issue LLDB commands using the Xcode console pane. But for development of open source and other non-GUI based application debugging, LLDB is used from a Terminal window as a conventional command line debugger. To use LLDB as a command-line debugger, you should understand how to:

Load a process for debugging

Attach a running process to LLDB

Set breakpoints and watchpoints

Control the process execution

Navigate in the process being debugged

Inspect variables for state and value

Execute alternative code

The Xcode IDE automates many of these operations with its full integration of LLDB into the source editing, build, and “run for debugging” cycle with graphical controls. Knowing how these operations work from the command line also helps you understand and use the full power of the LLDB debugger in the Xcode console pane.

Specifying the Program to Debug

First, you need to set the program to debug. As with GDB, you can start LLDB and specify the file you want to debug using the command line. Type:

$ lldb /Projects/Sketch/build/Debug/Sketch.app

Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64).

Or you can specify the executable file to debug after it is already running using the file command:

$ lldb

(lldb) file /Projects/Sketch/build/Debug/Sketch.app

Current executable set to '/Projects/Sketch/build/Debug/Sketch.app' (x86_64).

Setting Breakpoints

Next, you might want to set up breakpoints to begin your debugging after the process has been launched. Setting breakpoints was discussed briefly in LLDB Command Structure. To see all the options for breakpoint setting, use help breakpoint set. For instance, type the following to set a breakpoint on any use of a method named alignLeftEdges::

In LLDB there are two parts to a breakpoint: the logical specification of the breakpoint, which is what the user provides to the breakpoint set command, and the locations in the code that match that specification. For example, a break by selector sets a breakpoint on all the methods that implement that selector in the classes in your program. Similarly, a file and line breakpoint might result in multiple locations if that file and line are included inline in different places in your code.

One piece of information provided by the breakpoint list command output is that the logical breakpoint has an integer identifier, and its locations have identifiers within the logical breakpoint. The two are joined by a period (.)—for example, 1.1 in the example above.

Because the logical breakpoints remain live, if another shared library is loaded that includes another implementation of the alignLeftEdges: selector, the new location is added to breakpoint 1 (that is, a 1.2 breakpoint is set on the newly loaded selector).

The other piece of information in the breakpoint listing is whether the breakpoint location was resolved or not. A location is resolved when the file address it corresponds to gets loaded into the program being debugged. For instance, if you set a breakpoint in a shared library that later is unloaded, that breakpoint location remains but it is no longer resolved.

LLDB acts like GDB with the command:

(gdb) set breakpoint pending on

Like GDB, LLDB always makes a breakpoint from your specification, even if it didn’t find any locations that match the specification. To determine whether the expression has been resolved, check the locations field using breakpoint list. LLDB reports the breakpoint as pending when you set it. By looking at the breakpoints with pending status, you can determine whether you’ve made a typo in defining the breakpoint when no locations are found by examining the breakpoint set output. For example:

Either on all the locations generated by your logical breakpoint, or on any one of the particular locations that logical breakpoint resolved to, you can delete, disable, set conditions, and ignore counts using breakpoint-triggered commands. For instance, if you want to add a command to print a backtrace when LLDB hit the breakpoint numbered 1.1, you execute the following command:

Setting Watchpoints

In addition to breakpoints, LLDB supports watchpoints to monitor variables without stopping the running process. Use help watchpoint to see all the commands for watchpoint manipulations. For instance, enter the following commands to watch a variable named global for a write operation, and to stop only if the condition ‘(global==5)’ is true:

Launching the Program with LLDB

Once you’ve specified what program you are going to debug and set a breakpoint to halt it at some interesting location, you need to start (or launch) it into a running process. To launch a program with LLDB, use the process launch command or one of its built-in aliases:

(lldb) process launch

(lldb) run

(lldb) r

You can also attach LLDB to a process that is already running—the process running the executable program file you specified earlier—by using either the process ID or the process name. When attaching to a process by name, LLDB supports the --waitfor option. This option tells LLDB to wait for the next process that has that name to appear and then attach to it. For example, here are three commands to attach to the Sketch process, assuming that the process ID is 123:

(lldb) process attach --pid 123

(lldb) process attach --name Sketch

(lldb) process attach --name Sketch --waitfor

After you launch or attach LLDB to a process, the process might stop for some reason. For example:

Note the line that says “1 of 3 threads stopped with reasons:” and the lines that follow it. In a multithreaded environment, it is very common for more than one thread to hit your breakpoint(s) before the kernel actually returns control to the debugger. In that case, you will see all the threads that stopped for the reason listed in the stop message.

Controlling Your Program

After launching, LLDB allows the program to continue until you hit a breakpoint. The primitive commands for process control all exist under the thread command hierarchy. Here’s one example:

(lldb) thread continue

Resuming thread 0x2c03 in process 46915

Resuming process 46915

(lldb)

Note: In its present version (lldb-300.2.24), LLDB can operate on only one thread at a time, but it is designed to support saying “step over the function in Thread 1, and step into the function in Thread 2, and continue Thread 3”, and so on in a future revision.

For convenience, all the stepping commands have easy aliases. For example, thread continue is invoked with just c, and the same goes for the other stepping program commands—which are much the same as in GDB. For example:

(lldb) thread step-in // The same as "step" or "s" in GDB.

(lldb) thread step-over // The same as "next" or "n" in GDB.

(lldb) thread step-out // The same as "finish" or "f" in GDB.

By default, LLDB has defined aliases to all common GDB process control commands (for instance, s, step, n, next, finish). If you find that GDB process control commands you are accustomed to using don’t exist, you can add them to the ~/.lldbinit file using command alias.

LLDB also supports the step by instruction versions:

(lldb) thread step-inst // The same as "stepi" / "si" in GDB.

(lldb) thread step-over-inst // The same as "nexti" / "ni" in GDB.

LLDB has a run until line or frame exit stepping mode:

(lldb) thread until 100

This command runs the thread until the current frame reaches line 100. If the code skips around line 100 in the course of running, execution stops when the frame is popped off the stack. This command is a close equivalent to the GDB until command.

LLDB, by default, shares the terminal with the process being debugged. In this mode, much like debugging with GDB, when the process is running anything you type goes to the STDIN of the process being debugged. To interrupt that process, type CTRL+C.

However, if you attach to a process—or launch a process—with the --no-stdin option, the command interpreter is always available to enter commands. Always having an (lldb) prompt might be a little disconcerting to GDB users at first, but it is useful. Using the --no-stdin option allows you to set a breakpoint, watchpoint, and so forth, without having to explicitly interrupt the program you are debugging:

(lldb) process continue

(lldb) breakpoint set --name stop_here

There are many LLDB commands that won’t work while the process being debugged is running: The command interpreter lets you know when a command is inappropriate most of the time. (If you find any instances where the command interpreter isn’t flagging a problem case, please file a bug: bugreport.apple.com.)

The commands that work while a process is running include interrupting the process to halt execution (process interrupt), getting the process status (process status), breakpoint setting and clearing (breakpoint [set|clear|enable|disable|list] ...), and memory reading and writing (memory [read|write] ...).

The subject of disabling STDIN for a process running in LLDB presents a good opportunity to show how to set debugger properties in general. For example, if you always want to run in --no-stdin mode, set it as a generic process property using the LLDB settings command. The LLDB settings command is equivalent to the GDB set command. To do this, type:

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

In LLDB, settings are organized hierarchically, enabling you to discover them easily. In addition, almost anywhere that you can specify a setting on a generic entity (threads, for example), you can also apply the option to a particular instance. View the current LLDB settings with the settings list command. You can explore how the settings command works in detail using the help settings command.

Examining Thread State

After a process has stopped, LLDB chooses a current thread and a current frame in that thread (on stop, this is always the bottommost frame). Many of the commands for inspecting state work on this current thread or frame.

To inspect the current state of the process, start with these threads:

Provide a list of threads to backtrace, or use the keyword all to see all threads.

(lldb) thread backtrace all

Set the selected thread, the one which will be used by default in all the commands in the next section, with the thread select command, where the thread index is the one shown in the thread list listing, using

(lldb) thread select 2

Examining the Stack Frame State

The most convenient way to inspect a frame’s arguments and local variables is to use the frame variable command.

(lldb) frame variable

self = (SKTGraphicView *) 0x0000000100208b40

_cmd = (struct objc_selector *) 0x000000010001bae1

sender = (id) 0x00000001001264e0

selection = (NSArray *) 0x00000001001264e0

i = (NSUInteger) 0x00000001001264e0

c = (NSUInteger) 0x00000001001253b0

If you don’t specify any variable names, all arguments and local variables are shown. If you call frame variable, passing in the name or names of particular local variables, only those variables are printed. For instance:

(lldb) frame variable self

(SKTGraphicView *) self = 0x0000000100208b40

You can pass in a path to some subelement of one of the available locals, and that subelement is printed. For instance:

(lldb) frame variable self.isa

(struct objc_class *) self.isa = 0x0000000100023730

The frame variable command is not a full expression parser, but it does support a few simple operations such as &, *, ->, [] (no overloaded operators). The array brackets can be used on pointers to treat pointers as arrays. For example: