Chapter 3. lldb

lldb is a command line tool you can use to debug programs written in various programming languages. It allows you to inspect memory within the code being debugged, control the execution state of the code, detect the execution of particular sections of code, and much more.

Clang and LLVM Toolset is distributed with lldb 5.0.1.

Important

Clang and LLVM Toolset and lldb are available as a Technology Preview. See the Technology Preview Features Support Scope for more details.

Customers deploying Clang and LLVM Toolset are encouraged to provide feedback to Red Hat.

3.1. Installing lldb

The lldb tool is provided by the llvm-toolset-7-lldb package and is automatically installed with the llvm-toolset-7 package. See Section 1.4, “Installing Clang and LLVM Toolset”.

3.2. Preparing a Program for Debugging

To compile a C or C++ program with debugging information that lldb can read, make sure the compiler you use is instructed to create debug information.

  • For instructions on suitably configuring GCC, see TODO link to DTS User Guide.
  • For instructions on suitably configuring clang, see the section Controlling Debug Information in Clang Compiler User’s Manual.

3.3. Running lldb

To run lldb on a program you want to debug:

$ scl enable llvm-toolset-7 'lldb program_file_name'

This command starts lldb in an interactive mode and displays the default prompt, (lldb).

To quit the debugging session and return to the shell prompt, run the following command at any time:

(lldb) quit

Note that you can execute any command using the scl utility, causing it to be run with the Clang and LLVM Toolset binaries available. This allows you to run a shell session with Clang and LLVM Toolset lldb directly available:

$ scl enable llvm-toolset-7 'bash'

Example 3.1. Running the lldb Utility on the fibonacci Binary File

This example assumes that you have successfully compiled the fibonacci binary file as shown in TODO add example and link it.

Start debugging the program with lldb:

$ scl enable llvm-toolset-7 'lldb fibonacci'
(lldb) target create "fibonacci"
Current executable set to 'fibonacci' (x86_64).
(lldb)

The output indicates that the program fibonacci is ready for debugging.

3.4. Listing Source Code

To view the source code of the program you are debugging:

(lldb) list

As a result, the first ten lines of the source code are displayed.

To display the code surrounding a particular line:

(lldb) list file_name:line_number

Additionally, lldb displays source code listing automatically in the following situations:

  • Before you start the execution of the program you are debugging, lldb displays the first ten lines of the source code.
  • Each time the execution of the program is stopped, lldb displays the lines that surround the line on which the execution stops.

3.5. Using Breakpoints

Setting a New Breakpoint

To set a new breakpoint at a certain line:

(lldb) breakpoint file_name:line_number

To set a breakpoint on a certain function:

(lldb) breakpoint file_name:function_name

Example 3.2. Setting a New Breakpoint

This example assumes that you have successfully compiled the fibonacci.c file listed in TODO add example and link it with debugging information.

Set a new breakpoint at line 10 by running either of the following commands:

(lldb) b 10
Breakpoint 1: where = fibonacci`main + 33 at fibonacci.c:10, address = 0x000000000040054e
(lldb)  breakpoint set -f fibonacci.c --line 10
Breakpoint 2: where = fibonacci`main + 33 at fibonacci.c:10, address = 0x000000000040054e
Note

In lldb, the command b is not an alias to breakpoint. You can use both commands to set breakpoints, but b uses a subset of the syntax supported by gdb’s break command, and breakpoint uses lldb's syntax for setting breakpoints.

Listing Breakpoints

To display a list of currently set breakpoints:

(lldb) breakpoint list

Example 3.3. Listing Breakpoints

This example assumes that you have successfully followed the instructions in Example 3.2, “Setting a New Breakpoint”.

Display the list of currently set breakpoints:

(lldb) breakpoint list
Current breakpoints:
1: file = 'fibonacci.c', line = 10, exact_match = 0, locations = 1
  1.1: where = fibonacci`main + 33 at fibonacci.c:10, address = fibonacci[0x000000000040054e], unresolved, hit count = 0

2: file = 'fibonacci.c', line = 10, exact_match = 0, locations = 1
  2.1: where = fibonacci`main + 33 at fibonacci.c:10, address = fibonacci[0x000000000040054e], unresolved, hit count = 0

Deleting Existing Breakpoints

To delete a breakpoint that is set at a certain line:

(lldb) breakpoint clear -f file_name -l 10

Example 3.4. Deleting an Existing Breakpoint

This example assumes that you have successfully compiled the fibonacci.c file listed in TODO add example and link it with debugging information.

Set a new breakpoint at line 7:

(lldb) b 7
Breakpoint 3: where = fibonacci`main + 31 at fibonacci.c:9, address = 0x000000000040054c

Remove this breakpoint:

(lldb) breakpoint clear -l 7 -f fibonacci.c
1 breakpoints cleared:
3: file = 'fibonacci.c', line = 7, exact_match = 0, locations = 1

3.6. Starting Execution

To start an execution of the program you are debugging:

(lldb) run

If the program accepts command-line arguments, you can provide them as arguments to the run command:

(lldb) run argument

The execution stops when the first breakpoint is reached, when an error occurs, or when the program terminates.

Example 3.5. Executing the fibonacci Binary File

This example assumes that you have successfully followed the instructions in Example 3.2, “Setting a New Breakpoint”.

Execute the fibonacci binary file:

(lldb) run
Process 21054 launched: 'fibonacci' (x86_64)
Process 21054 stopped
* thread #1, name = 'fibonacci', stop reason = breakpoint 1.1
    frame #0: fibonacci`main(argc=1, argv=0x00007fffffffdeb8) at fibonacci.c:10
   7      unsigned long int sum;
   8
   9      while (b < LONG_MAX) {
-> 10       printf("%ld ", b);
   11       sum = a + b;
   12       a = b;
   13       b = sum;

Execution of the program stops at the breakpoint set in Example 3.2, “Setting a New Breakpoint”.

3.7. Displaying Current Values

The lldb tool enables you to display many values relevant to the program state, including:

  • Variables of any complexity
  • Any valid expressions
  • Function call return values

The most common task is to display the value of a variable. To display the current value of a certain variable:

(lldb) print variable_name

Example 3.6. Displaying the Current Values of Variables

This example assumes that you have successfully followed the instructions in Example 3.5, “Executing the fibonacci Binary File”. Execution of the fibonacci binary stopped after reaching the breakpoint at line 10.

Display the current values of variables a and b:

(lldb) print a
$0 = 0
(lldb) print b
$1 = 1

3.8. Continuing Execution

To resume the execution of the program you are debugging after it reached a breakpoint:

(lldb) continue

The execution stops again when it reaches another breakpoint.

To skip a certain number of breakpoints, typically when you are debugging a loop, run the continue command in the following form:

(lldb) continue -i number_of_breakpoints_to_skip

The lldb tool also enables you to stop the execution after executing a single line of code:

(lldb) step

To execute a certain number of lines:

(lldb) step -c number

Example 3.7. Continuing the Execution of the fibonacci Binary File

This example assumes that you have successfully followed the instructions in Example 3.5, “Executing the fibonacci Binary File”. The execution of the fibonacci binary stopped after reaching the breakpoint at line 10.

Resume the execution:

(lldb) continue
Process 21580 resuming
Process 21580 stopped
* thread #1, name = 'fibonacci', stop reason = breakpoint 1.1
    frame #0: fibonacci`main(argc=1, argv=0x00007fffffffdeb8) at fibonacci.c:10
   7      unsigned long int sum;
   8
   9      while (b < LONG_MAX) {
-> 10       printf("%ld ", b);
   11       sum = a + b;
   12       a = b;
   13       b = sum;

The execution stops the next time it reaches a breakpoint. (In this case it is the same breakpoint). Execute the next three lines of code:

(lldb) step -c 3
Process 21580 stopped
* thread #1, name = 'fibonacci', stop reason = step in
    frame #0: fibonacci`main(argc=1, argv=0x00007fffffffdeb8) at fibonacci.c:11
   8
   9      while (b < LONG_MAX) {
   10       printf("%ld ", b);
-> 11       sum = a + b;
   12       a = b;
   13       b = sum;
   14     }

Verify the current value of the sum variable before it is assigned to the b variable:

(lldb) print sum
$2 = 2

3.9. Additional Resources

A detailed description of the lldb debugger and all its features is beyond the scope of this book. For more information, see the resources listed below.

Online Documentation

See Also