lldb/docs/use/formatting.rst

   1 Frame and Thread Format
   2 =======================
   3
   4 LLDB has a facility to allow users to define the format of the information that
   5 generates the descriptions for threads and stack frames. Typically when your
   6 program stops at a breakpoint you will get two lines that describes why your
   7 thread stopped and where:
   8
   9 ::
  10
  11    * thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1
  12        frame #0: test`main at test.c:5
  13
  14 Stack backtraces frames also have a similar information line:
  15
  16 ::
  17
  18    (lldb) thread backtrace
  19    * thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.1
  20        frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19
  21        frame #1: 0x0000000100000e40 a.out`start + 52
  22
  23 The two format strings that govern the printing in these output forms can
  24 currently be set using the settings set command:
  25
  26 ::
  27
  28    (lldb) settings set thread-stop-format STRING
  29    (lldb) settings set frame-format STRING
  30
  31 The first of these is an abbreviated thread output, that just contains data
  32 about the thread, and not the stop frame. It will always get used in situations
  33 where the frame output follows immediately, so that information would be
  34 redundant. The second is the frame printing.
  35
  36 There is another thread format used for commands like thread list where the
  37 thread information isn't followed by frame info. In that case, it is convenient
  38 to have frame zero information in the thread output. That format is set by:
  39
  40 ::
  41
  42    (lldb) settings set thread-format STRING
  43
  44
  45 Format Strings
  46 --------------
  47
  48 So what is the format of the format strings? Format strings can contain plain
  49 text, control characters and variables that have access to the current program
  50 state.
  51
  52 Normal characters are any text that doesn't contain a ``{``, ``}``, ``$``, or
  53 ``\`` character.
  54
  55 Variable names are found in between a ``${`` prefix, and end with a ``}``
  56 suffix. In other words, a variable looks like ``${frame.pc}``.
  57
  58 Variables
  59 ---------
  60
  61 A complete list of currently supported format string variables is listed below:
  62
  63 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  64 | **Variable Name**                                 | **Description**                                                                                                                                                                                                                                                                             |
  65 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  66 | ``file.basename``                                 | The current compile unit file basename for the current frame.                                                                                                                                                                                                                               |
  67 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  68 | ``file.fullpath``                                 | The current compile unit file fullpath for the current frame.                                                                                                                                                                                                                               |
  69 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  70 | ``language``                                      | The current compile unit language for the current frame.                                                                                                                                                                                                                                    |
  71 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  72 | ``frame.index``                                   | The frame index (0, 1, 2, 3...)                                                                                                                                                                                                                                                             |
  73 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  74 | ``frame.no-debug``                                | Evaluates to true if the frame has no debug info.                                                                                                                                                                                                                                           |
  75 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  76 | ``frame.pc``                                      | The generic frame register for the program counter.                                                                                                                                                                                                                                         |
  77 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  78 | ``frame.sp``                                      | The generic frame register for the stack pointer.                                                                                                                                                                                                                                           |
  79 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  80 | ``frame.fp``                                      | The generic frame register for the frame pointer.                                                                                                                                                                                                                                           |
  81 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  82 | ``frame.flags``                                   | The generic frame register for the flags register.                                                                                                                                                                                                                                          |
  83 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  84 | ``frame.reg.NAME``                                | Access to any platform specific register by name (replace ``NAME`` with the name of the desired register).                                                                                                                                                                                  |
  85 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  86 | ``function.name``                                 | The name of the current function or symbol.                                                                                                                                                                                                                                                 |
  87 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  88 | ``function.name-with-args``                       | The name of the current function with arguments and values or the symbol name.                                                                                                                                                                                                              |
  89 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  90 | ``function.name-without-args``                    | The name of the current function without arguments and values (used to include a function name in-line in the ``disassembly-format``)                                                                                                                                                       |
  91 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  92 | ``function.mangled-name``                         | The mangled name of the current function or symbol.                                                                                                                                                                                                                                         |
  93 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  94 | ``function.pc-offset``                            | The program counter offset within the current function or symbol                                                                                                                                                                                                                            |
  95 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  96 | ``function.addr-offset``                          | The offset in bytes of the current function, formatted as " + dddd"                                                                                                                                                                                                                         |
  97 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
  98 | ``function.concrete-only-addr-offset-no-padding`` | Similar to ``function.addr-offset`` except that there are no spaces in the output (e.g. "+dddd") and the offset is computed from the nearest concrete function -- inlined functions are not included                                                                                        |
  99 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 100 | ``function.changed``                              | Will evaluate to true when the line being formatted is a different symbol context from the previous line (may be used in ``disassembly-format`` to print the new function name on a line by itself at the start of a new function).  Inlined functions are not considered for this variable |
 101 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 102 | ``function.initial-function``                     | Will evaluate to true if this is the start of the first function, as opposed to a change of functions (may be used in ``disassembly-format`` to print the function name for the first function being disassembled)                                                                          |
 103 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 104 | ``line.file.basename``                            | The line table entry basename to the file for the current line entry in the current frame.                                                                                                                                                                                                  |
 105 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 106 | ``line.file.fullpath``                            | The line table entry fullpath to the file for the current line entry in the current frame.                                                                                                                                                                                                  |
 107 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 108 | ``line.number``                                   | The line table entry line number for the current line entry in the current frame.                                                                                                                                                                                                           |
 109 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 110 | ``line.start-addr``                               | The line table entry start address for the current line entry in the current frame.                                                                                                                                                                                                         |
 111 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 112 | ``line.end-addr``                                 | The line table entry end address for the current line entry in the current frame.                                                                                                                                                                                                           |
 113 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 114 | ``module.file.basename``                          | The basename of the current module (shared library or executable)                                                                                                                                                                                                                           |
 115 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 116 | ``module.file.fullpath``                          | The basename of the current module (shared library or executable)                                                                                                                                                                                                                           |
 117 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 118 | ``process.file.basename``                         | The basename of the file for the process                                                                                                                                                                                                                                                    |
 119 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 120 | ``process.file.fullpath``                         | The fullname of the file for the process                                                                                                                                                                                                                                                    |
 121 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 122 | ``process.id``                                    | The process ID native to the system on which the inferior runs.                                                                                                                                                                                                                             |
 123 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 124 | ``process.name``                                  | The name of the process at runtime                                                                                                                                                                                                                                                          |
 125 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 126 | ``thread.id``                                     | The thread identifier for the current thread                                                                                                                                                                                                                                                |
 127 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 128 | ``thread.index``                                  | The unique one based thread index ID which is guaranteed to be unique as threads come and go.                                                                                                                                                                                               |
 129 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 130 | ``thread.name``                                   | The name of the thread if the target OS supports naming threads                                                                                                                                                                                                                             |
 131 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 132 | ``thread.queue``                                  | The queue name of the thread if the target OS supports dispatch queues                                                                                                                                                                                                                      |
 133 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 134 | ``thread.stop-reason``                            | A textual reason why the thread stopped. If the thread have a recognized frame, this displays its recognized stop reason. Otherwise, gets the stop info description.                                                                                                                        |
 135 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 136 | ``thread.stop-reason-raw``                        | A textual reason why the thread stopped. Always returns stop info description.                                                                                                                                                                                                              |
 137 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 138 | ``thread.return-value``                           | The return value of the latest step operation (currently only for step-out.)                                                                                                                                                                                                                |
 139 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 140 | ``thread.completed-expression``                   | The expression result for a thread that just finished an interrupted expression evaluation.                                                                                                                                                                                                 |
 141 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 142 | ``target.arch``                                   | The architecture of the current target                                                                                                                                                                                                                                                      |
 143 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 144 | ``script.target:python_func``                     | Use a Python function to generate a piece of textual output                                                                                                                                                                                                                                 |
 145 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 146 | ``script.process:python_func``                    | Use a Python function to generate a piece of textual output                                                                                                                                                                                                                                 |
 147 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 148 | ``script.thread:python_func``                     | Use a Python function to generate a piece of textual output                                                                                                                                                                                                                                 |
 149 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 150 | ``script.frame:python_func``                      | Use a Python function to generate a piece of textual output                                                                                                                                                                                                                                 |
 151 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 152 | ``current-pc-arrow``                              | Prints either ``->`` or `` `` if the current pc value is matched (used in ``disassembly-format``)                                                                                                                                                                                           |
 153 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 154 | ``addr-file-or-load``                             | Formats an address either as a load address, or if process has not yet been launched, as a load address (used in ``disassembly-format``)                                                                                                                                                    |
 155 +---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 156
 157 Control Characters
 158 ------------------
 159
 160 Control characters include ``{``, ``}``, and ``\``.
 161
 162 The ``{`` and ``}`` are used for scoping blocks, and the ``\`` character allows
 163 you to desensitize control characters and also emit non-printable characters.
 164
 165 Desensitizing Characters in the Format String
 166 ---------------------------------------------
 167
 168 The backslash control character allows your to enter the typical ``\a``,
 169 ``\b``, ``\f``, ``\n``, ``\r``, ``\t``, ``\v``, ``\\``, characters and along
 170 with the standard octal representation ``\0123`` and hex ``\xAB`` characters.
 171 This allows you to enter escape characters into your format strings and will
 172 allow colorized output for terminals that support color.
 173
 174 Scoping
 175 -------
 176
 177 Many times the information that you might have in your prompt might not be
 178 available and you won``t want it to print out if it isn``t valid. To take care
 179 of this you can enclose everything that must resolve into a scope. A scope is
 180 starts with ``{`` and ends with ``}``. For example in order to only display the
 181 current frame line table entry basename and line number when the information is
 182 available for the current frame:
 183
 184 ::
 185
 186    "{ at {$line.file.basename}:${line.number}}"
 187
 188
 189 Broken down this is:
 190
 191 - The start the scope: ``{`` ,
 192 - format whose content will only be displayed if all information is available: ``at {$line.file.basename}:${line.number}``
 193 - end the scope: ``}``
 194
 195 Making the Frame Format
 196 -----------------------
 197
 198 The information that we see when stopped in a frame:
 199
 200 ::
 201
 202    frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19
 203
 204 can be displayed with the following format:
 205
 206 ::
 207
 208    "frame #${frame.index}: ${frame.pc}{ ${module.file.basename}`${function.name}{${function.pc-offset}}}{ at ${line.file.basename}:${line.number}}\n"
 209
 210 This breaks down to:
 211
 212 - Always print the frame index and frame PC: ``frame #${frame.index}: ${frame.pc}``,
 213 - only print the module followed by a tick if there is a valid module for the current frame: ``{ ${module.file.basename}`}``,
 214 - print the function name with optional offset: ``{${function.name}{${function.pc-offset}}}``,
 215 - print the line info if it is available: ``{ at ${line.file.basename}:${line.number}}``,
 216 - then finish off with a newline: ``\n``.
 217
 218 Making Your own Formats
 219 -----------------------
 220
 221 When modifying your own format strings, it is useful to start with the default
 222 values for the frame and thread format strings. These can be accessed with the
 223 ``settings show`` command:
 224
 225 ::
 226
 227    (lldb) settings show thread-format
 228    thread-format (format-string) = "thread #${thread.index}: tid = ${thread.id%tid}{, ${frame.pc}}{ ${module.file.basename}{`${function.name-with-args}{${frame.no-debug}${function.pc-offset}}}}{ at ${line.file.basename}:${line.number}}{, name = '${thread.name}'}{, queue = '${thread.queue}'}{, activity = '${thread.info.activity.name}'}{, ${thread.info.trace_messages} messages}{, stop reason = ${thread.stop-reason}}{\nReturn value: ${thread.return-value}}{\nCompleted expression: ${thread.completed-expression}}\n"
 229    (lldb) settings show frame-format
 230    frame-format (format-string) = "frame #${frame.index}:{ ${frame.no-debug}${frame.pc}}{ ${module.file.basename}{`${function.name-with-args}{${frame.no-debug}${function.pc-offset}}}}{ at ${line.file.basename}:${line.number}}{${function.is-optimized} [opt]}\n"
 231
 232 When making thread formats, you will need surround any of the information that
 233 comes from a stack frame with scopes ({ frame-content }) as the thread format
 234 doesn't always want to show frame information. When displaying the backtrace
 235 for a thread, we don't need to duplicate the information for frame zero in the
 236 thread information:
 237
 238 ::
 239
 240   (lldb) thread backtrace
 241   thread #1: tid = 0x2e03, stop reason = breakpoint 1.1 2.1
 242     frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19
 243     frame #1: 0x0000000100000e40 a.out`start + 52
 244
 245 The frame related variables are:
 246
 247 - ``${file.*}``
 248 - ``${frame.*}``
 249 - ``${function.*}``
 250 - ``${line.*}``
 251 - ``${module.*}``
 252
 253
 254 Looking at the default format for the thread, and underlining the frame
 255 information:
 256
 257 ::
 258
 259    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
 260
 261
 262 We can see that all frame information is contained in scopes so that when the
 263 thread information is displayed in a context where we only want to show thread
 264 information, we can do so.
 265
 266 For both thread and frame formats, you can use ${script.target:python_func},
 267 ${script.process:python_func} and ${script.thread:python_func} (and of course
 268 ${script.frame:python_func} for frame formats) In all cases, the signature of
 269 python_func is expected to be:
 270
 271 ::
 272
 273    def python_func(object,unused):
 274      ...
 275      return string
 276
 277 Where object is an instance of the SB class associated to the keyword you are
 278 using.
 279
 280 e.g. Assuming your function looks like:
 281
 282 ::
 283
 284    def thread_printer_func (thread,unused):
 285      return "Thread %s has %d frames\n" % (thread.name, thread.num_frames)
 286
 287 And you set it up with:
 288
 289 ::
 290
 291    (lldb) settings set thread-format "${script.thread:thread_printer_func}"
 292
 293 you would see output like:
 294
 295 ::
 296
 297    * Thread main has 21 frames
 298