# Frame and thread formatting

LLDB lets you customize how frame and thread information is displayed
in the debugger.

## Stack frame and thread format

LLDB lets you define the format used for displaying information on
threads and stack frames.

Typically, when your program stops at a breakpoint, LLDB displays a
line explaining why your thread stopped:

* thread #1: tid = 0x2e03, 0x0000000100000e85 a.out`main + 4, stop reason = breakpoint 1.1
    Copy to clipboard

Stack backtrace frames display a similar line:

(lldb)* thread backtrace *thread #1: tid = 0x2e03, stop reason = breakpoint 1.1**
       frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19
       frame #1: 0x0000000100000e40 a.out`start + 52
    Copy to clipboard

Use the settings set command to change the display formats used in
these two lines:

(lldb) settings set frame-format STRING *
    (lldb) settings set thread-format STRING
    Copy to clipboard

## Format strings

Format strings can contain the following elements:

- Plain text

    Includes any text that does not contain a {, }, $, or \ character.
- Control characters
- Variables (which access the current program state)

    Specified in a format string with the `${` prefix and `}` suffix. For example: `${frame.pc}`.

### Variables

| Variable Name | Description |
| --- | --- |
| file.basename | Base name of the current compile unit file for the current frame. |
| file.fullpath | Full path of the current compile unit file for the current frame. |
| frame.index | Frame index (0, 1, 2, 3…). |
| frame.pc | Generic frame register for the program counter. |
| frame.sp | Generic frame register for the stack pointer. |
| frame.fp | Generic frame register for the frame pointer. |
| frame.flags | Generic frame register for the flags register. |
| frame.reg.NAME | Access to any platform-specific register by name (replace<br>NAME with the name of the intended register). |
| function.name | Name of the current function or symbol. |
| function.name-with-args | Name of the current function with arguments and values, or the<br>name of the symbol. |
| function.pc-offset | Program counter offset within the current function or symbol. |
| line.file.basename | Base name of the line table entry to the file for the current<br>line entry in the current frame. |
| line.file.fullpath | Full path of the line table entry to the file for the current<br>line entry in the current frame. |
| line.number | Line number of the line table entry for the current line entry<br>in the current frame. |
| line.start-addr | Starting address of the line table entry for the current line<br>entry in the current frame. |
| line.end-addr | Ending address of the line table entry for the current line<br>entry in the current frame. |
| module.file.basename | Base name of the current module (shared library or executable). |
| module.file.fullpath | Base name of the current module (shared library or executable). |
| process.file.basename | Base name of the file for the process. |
| process.file.fullpath | Full name of the file for the process. |
| process.id | Process ID native to the system on which the inferior runs. |
| process.name | Name of the process at runtime. |
| thread.id | Thread identifier for the current thread. |
| thread.index | Unique ID of the one-based thread index that is guaranteed to be<br>unique as threads come and go. |
| thread.name | Name of the thread if the target operating system supports<br>naming threads. |
| thread.queue | Queue name of the thread if the target operating system supports<br>dispatch queues. |
| thread.stop-reason | Text explanation of why each thread stopped. |
| thread.return-value | Return value of the latest step operation (currently only for step-out). |
| thread.completed-expression | Expression result for a thread that just finished an interrupted<br>expression evaluation. |
| target.arch | Architecture of the current target. |
| target.script:/python\_func/ | Use a Python function to generate a piece of text output. |
| process.script:/python\_func/ | Use a Python function to generate a piece of text output. |
| thread.script:/python\_func/ | Use a Python function to generate a piece of text output. |
| frame.script:/python\_func/ | Use a Python function to generate a piece of text output. |
|  |  |
|  |  |
|  |  |

### Control characters

Control characters include `{`, `}`, and `\`.

The `{` and `}` characters are used for scoping blocks, while `\` is used
to desensitize control characters and emit non-printable characters.

### Desensitizing characters

The backslash control character, `\`, lets you enter the typical `\a`,
`\b`, `\f`, `\n`, `\r`, `\t`, `\v`, and `\\` characters. It also allows you
to specify characters in octal representation (`\0123`) and
hexadecimal representation (`\xAB`).

The `\` character enables you to enter escape characters into your
format strings, and it allows colorized output for terminals that
support color.

### Scoping

In many cases, the information that you might have configured to
appear in your prompt might not be available, and you do not want the
prompt to print out the information if it is not valid. To handle
this situation, you can enclose everything that must be resolved into
a *scope*.

A scope is defined to begin with { and end with }. For example, the
following scope displays the base name and line number for the
current frame line table entry, but only when this information is
available for the current frame:

{ at {$line.file.basename}:${line.number}}
    Copy to clipboard

The scope in this example consists of the following parts:

- The start of the scope:

{
        Copy to clipboard
- The format whose content is displayed only if all information is
available:

at {$line.file.basename}:${line.number}
        Copy to clipboard
- The end of the scope:

}
        Copy to clipboard

## Format example

The following information line is an example of what can be displayed
when your program is stopped in a frame:

frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19
    Copy to clipboard

You can specify this information line with the following format
specifier:

settings set frame-format #${frame.index}:${frame.pc}
    {${module.file.basename} \`{${function.name}{${function.pc-offset}}
    {at ${line.file.basename}:${line.number}}\\n
    Copy to clipboard

The format specifier in this example consists of the following parts:

- Always print the frame index and frame PC:

#${frame.index}: ${frame.pc}
        Copy to clipboard
- Only print the module followed by a tick if a valid module exists for
current frame:

{${module.file.basename}\`}
        Copy to clipboard
- Print the function name with an optional offset:

{${function.name}{${function.pc-offset}}}
        Copy to clipboard
- Print the line information, if available:

{ at ${line.file.basename}:${line.number}}
        Copy to clipboard
- End the information line with a newline character:

\n
        Copy to clipboard

## User-defined formats

When modifying your own format strings, it is useful to start with
the default values for the frame and thread format strings. To access
the default settings, use the settings show command. For example:

(lldb) settings show thread-format
    thread-format (string) = 'thread #${thread.index}: tid = ${thread.id}{, ${frame.pc}}{
       ${module.file.basename}`${function.name}{${function.pc-offset}}}{,
       stop reason = ${thread.stop-reason}}{, name = ${thread.name}}{, queue = ${thread.queue}}\\n'
    (lldb) settings show frame-format frame-format (string) = 'frame #${frame.index}: ${frame.pc}{ ${module.file.basename}
    `${function.name} {${function.pc-offset}}}{at ${line.file.basename}:${line.number}}\\n'
    Copy to clipboard

When defining a thread format, you must use scopes ([scoping](https://docs.qualcomm.com/doc/80-N3040-23/topic/frame-and-thread-formatting.html#frame-and-thread-scoping)) to contain any
information that comes from a stack frame, because the thread format does not always show frame information.

When displaying the backtrace for a thread, you are not required to
duplicate the information for frame zero in the thread information.
For example:

(lldb)* thread backtrace
    thread #1: tid = 0x2e03, stop reason = breakpoint 1.1 2.1
       frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19
       frame #1: 0x0000000100000e40 a.out`start + 52 |
    Copy to clipboard

The frame-related variables are:

${file.*}
    ${frame.*}
    ${function.*}
    ${line.*}
    ${module.*}
    Copy to clipboard

In the default thread format definition, all frame-related
information is in scopes, so you can omit it when the thread
information is displayed in contexts where frame information is not
applicable. For example:

|'thread #${thread.index}: tid = ${thread.id}{, ${frame.pc}}{
    ${module.file.basename}`${function.name}{${function.pc-offset}}}{,
    stop reason = ${thread.stop-reason}}{, name = ${thread.name}}{, queue = ${thread.queue}}\n'
    Copy to clipboard

In both thread and frame format definitions, use the `${X.script:/python_func/}`
variables to specify Python functions that generate the display text
([variables](https://docs.qualcomm.com/doc/80-N3040-23/topic/frame-and-thread-formatting.html#frame-and-thread-variables)). In all cases, the signature of
python\_func is expected to be:

def /python_func/(/object/,unused):
        ...
        return /string/
    Copy to clipboard

Where object is an instance of the SB class associated with the
keyword you are using.

For example, assuming your function looks like the following:

def thread_printer_func (thread,unused):
        return "Thread %s has %d frames\\n" % (thread.name, thread.num_frames)
    Copy to clipboard

And you set it up with the following command:

(lldb) settings set thread-format "${thread.script:thread_printer_func}"
    Copy to clipboard

You will see the following output:

Thread main has 21 frames
    Copy to clipboard

Last Published: Oct 06, 2026

[Previous Topic
Miscellaneous commands](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/use-the-debugger.md) [Next Topic
Frame symbolication](https://docs.qualcomm.com/bundle/publicresource/80-N3040-23/topics/frame-symbolication.md)

Source: [https://docs.qualcomm.com/doc/80-N3040-23/topic/frame-and-thread-formatting.html](https://docs.qualcomm.com/doc/80-N3040-23/topic/frame-and-thread-formatting.html)