366 lines · plain
1Frame and Thread Format2=======================3 4LLDB has a facility to allow users to define the format of the information that5generates the descriptions for threads and stack frames. Typically when your6program stops at a breakpoint you will get two lines that describe why your7thread stopped and where:8 9::10 11 * thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.112 frame #0: test`main at test.c:513 14Stack backtraces frames also have a similar information line:15 16::17 18 (lldb) thread backtrace19 * thread #1, queue = 'com.apple.main-thread', stop reason = breakpoint 1.120 frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:1921 frame #1: 0x0000000100000e40 a.out`start + 5222 23The two format strings that govern the printing in these output forms can24currently be set using the settings set command:25 26::27 28 (lldb) settings set thread-stop-format STRING29 (lldb) settings set frame-format STRING30 31The first of these is an abbreviated thread output, that just contains data32about the thread, and not the stop frame. It will always get used in situations33where the frame output follows immediately, so that information would be34redundant. The second is the frame printing.35 36There is another thread format used for commands like thread list where the37thread information isn't followed by frame info. In that case, it is convenient38to have frame zero information in the thread output. That format is set by:39 40::41 42 (lldb) settings set thread-format STRING43 44 45Format Strings46--------------47 48So what is the format of the format strings? Format strings can contain plain49text, control characters and variables that have access to the current program50state.51 52Normal characters are any text that doesn't contain a ``{``, ``}``, ``$``, or53``\`` character.54 55Variable names are found in between a ``${`` prefix, and end with a ``}``56suffix. In other words, a variable looks like ``${frame.pc}``.57 58Variables59---------60 61A 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. The name will be displayed according to the current frame's language if possible. |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.name-qualifiers`` | Any qualifiers added after the name of a function and before its arguments or template arguments. E.g., for Swift the name qualifier for ``closure #1 in A.foo<Int>()`` is `` in A.foo``. |93+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+94| ``function.basename`` | The basename of the current function depending on the frame's language. E.g., for C++ the basename for ``void ns::foo<float>::bar<int>(int) const`` is ``bar``. |95+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+96| ``function.prefix`` | Any prefix added to the demangled function name of the current function. This depends on the frame's language. E.g., for C++ the prefix will always be empty. |97+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+98| ``function.scope`` | The scope qualifiers of the current function depending on the frame's language. E.g., for C++ the scope for ``void ns::foo<float>::bar<int>(int) const`` is ``ns::foo<float>``. |99+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+100| ``function.template-arguments`` | The template arguments of the current function depending on the frame's language. E.g., for C++ the template arguments for ``void ns::foo<float>::bar<int>(int) const`` are ``<float>``. |101+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+102| ``function.formatted-arguments`` | Arguments of the current function, formatted according to the frame's language. When debug-info is available, will apply data-formatters to each argument and include it's name if available. Otherwise prints the type of each argument according to the mangling. E.g., for C++ the |103| | pretty-printed arguments for ``func(int x, const char *str)`` are ``(x=10, str="Hello")``. Without debug-info it would be ``(int, const char*)``. |104+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+105| ``function.qualifiers`` | The function CV and reference qualifiers of the current function depending on the frame's language. E.g., for C++ the qualifiers for ``void ns::foo<float>::bar<int>(int) const &`` are ``const &``. |106+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+107| ``function.return-left`` | The return type to the left of the demangled function name of the current function. This depends on the frame's language. E.g., for C++ the ``function.return-left`` is in most-cases the entirety of the return type. In ``void ns::foo(int)`` that would be ``void``. However, in some |108| | cases, particularly for functions returning function pointers, part of the return type is to the right of the function name. E.g., for ``void (*ns::func(float))(int)`` the ``function.return-left`` would be ``void (*`` and the ``function.return-right`` would be ``)(int)``. |109+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+110| ``function.return-right`` | The return type to the right of the demangled function name of the current function. This depends on the frame's language. In ``void ns::foo(int)`` there is no ``function.return-right`` so this would correspond to an empty string. However, in some cases, particularly for functions |111| | returning function pointers, part of the return type is to the right of the function name. E.g., for ``void (*ns::func(float))(int)`` the ``function.return-left`` would be ``void (*`` and the ``function.return-right`` would be ``)(int)``. |112+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+113| ``function.suffix`` | Any suffix added to the demangled function name of the current function. This depends on the frame's language. E.g., for C++ the suffix for ``void ns::foo(int) (.cold)`` is '(.cold). |114+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+115| ``function.mangled-name`` | The mangled name of the current function or symbol. |116+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+117| ``function.pc-offset`` | The program counter offset within the current function or symbol |118+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+119| ``function.addr-offset`` | The offset in bytes of the current function, formatted as " + dddd" |120+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+121| ``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 |122+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+123| ``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 |124+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+125| ``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) |126+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+127| ``function.is-inlined`` | Will evaluate to true if this function was inlined |128+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+129| ``line.file.basename`` | The line table entry basename to the file for the current line entry in the current frame. |130+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+131| ``line.file.fullpath`` | The line table entry fullpath to the file for the current line entry in the current frame. |132+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+133| ``line.number`` | The line table entry line number for the current line entry in the current frame. |134+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+135| ``line.start-addr`` | The line table entry start address for the current line entry in the current frame. |136+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+137| ``line.end-addr`` | The line table entry end address for the current line entry in the current frame. |138+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+139| ``module.file.basename`` | The basename of the current module (shared library or executable) |140+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+141| ``module.file.fullpath`` | The path of the current module (shared library or executable) |142+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+143| ``process.file.basename`` | The basename of the file for the process |144+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+145| ``process.file.fullpath`` | The path of the file for the process |146+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+147| ``process.id`` | The process ID native to the system on which the inferior runs. |148+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+149| ``process.name`` | The name of the process at runtime |150+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+151| ``thread.id`` | The thread identifier for the current thread |152+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+153| ``thread.index`` | The unique one based thread index ID which is guaranteed to be unique as threads come and go. |154+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+155| ``thread.name`` | The name of the thread if the target OS supports naming threads |156+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+157| ``thread.queue`` | The queue name of the thread if the target OS supports dispatch queues |158+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+159| ``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. |160+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+161| ``thread.stop-reason-raw`` | A textual reason why the thread stopped. Always returns stop info description. |162+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+163| ``thread.return-value`` | The return value of the latest step operation (currently only for step-out.) |164+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+165| ``thread.completed-expression`` | The expression result for a thread that just finished an interrupted expression evaluation. |166+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+167| ``target.arch`` | The architecture of the current target |168+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+169| ``target.file.basename`` | The basename of the current target |170+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+171| ``target.file.fullpath`` | The path of the current target |172+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+173| ``script.target:python_func`` | Use a Python function to generate a piece of textual output |174+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+175| ``script.process:python_func`` | Use a Python function to generate a piece of textual output |176+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+177| ``script.thread:python_func`` | Use a Python function to generate a piece of textual output |178+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+179| ``script.frame:python_func`` | Use a Python function to generate a piece of textual output |180+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+181| ``current-pc-arrow`` | Prints either ``->`` or `` `` if the current pc value is matched (used in ``disassembly-format``) |182+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+183| ``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``) |184+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+185 186Control Characters187------------------188 189Control characters include ``{``, ``}``, and ``\``.190 191The ``{`` and ``}`` are used for scoping blocks, and the ``\`` character allows192you to desensitize control characters and also emit non-printable characters.193 194Desensitizing Characters in the Format String195---------------------------------------------196 197The backslash control character allows you to enter the typical ``\a``,198``\b``, ``\f``, ``\n``, ``\r``, ``\t``, ``\v``, ``\\``, characters and along199with the standard octal representation ``\0123`` and hex ``\xAB`` characters.200This allows you to enter escape characters into your format strings and will201allow colorized output for terminals that support color.202 203Scoping204-------205 206Many times the information that you might have in your prompt might not be207available and you won't want it to print out if it isn't valid. To take care208of this you can enclose everything that must resolve into a scope. A scope209starts with ``{`` and ends with ``}``. For example in order to only display the210current frame line table entry basename and line number when the information is211available for the current frame:212 213::214 215 "{ at {$line.file.basename}:${line.number}}"216 217 218Broken down this is:219 220- The start the scope: ``{`` ,221- format whose content will only be displayed if all information is available: ``at {$line.file.basename}:${line.number}``222- end the scope: ``}``223 224Making the Frame Format225-----------------------226 227The information that we see when stopped in a frame:228 229::230 231 frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19232 233can be displayed with the following format:234 235::236 237 "frame #${frame.index}: ${frame.pc}{ ${module.file.basename}`${function.name}{${function.pc-offset}}}{ at ${line.file.basename}:${line.number}}\n"238 239This breaks down to:240 241- Always print the frame index and frame PC: ``frame #${frame.index}: ${frame.pc}``,242- only print the module followed by a tick if there is a valid module for the current frame: ``{ ${module.file.basename}`}``,243- print the function name with optional offset: ``{${function.name}{${function.pc-offset}}}``,244- print the line info if it is available: ``{ at ${line.file.basename}:${line.number}}``,245- then finish off with a newline: ``\n``.246 247Making Your own Formats248-----------------------249 250When modifying your own format strings, it is useful to start with the default251values for the frame and thread format strings. These can be accessed with the252``settings show`` command:253 254::255 256 (lldb) settings show thread-format257 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"258 (lldb) settings show frame-format259 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"260 261When making thread formats, you will need surround any of the information that262comes from a stack frame with scopes ({ frame-content }) as the thread format263doesn't always want to show frame information. When displaying the backtrace264for a thread, we don't need to duplicate the information for frame zero in the265thread information:266 267::268 269 (lldb) thread backtrace270 thread #1: tid = 0x2e03, stop reason = breakpoint 1.1 2.1271 frame #0: 0x0000000100000e85 a.out`main + 4 at test.c:19272 frame #1: 0x0000000100000e40 a.out`start + 52273 274The frame-related variables are:275 276- ``${file.*}``277- ``${frame.*}``278- ``${function.*}``279- ``${line.*}``280- ``${module.*}``281 282 283Looking at the default format for the thread, and underlining the frame284information:285 286::287 288 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}}\n289 290 291We can see that all frame information is contained in scopes so that when the292thread information is displayed in a context where we only want to show thread293information, we can do so.294 295For both thread and frame formats, you can use ${script.target:python_func},296${script.process:python_func} and ${script.thread:python_func} (and of course297${script.frame:python_func} for frame formats) In all cases, the signature of298python_func is expected to be:299 300::301 302 def python_func(object,unused):303 ...304 return string305 306Where object is an instance of the SB class associated to the keyword you are307using.308 309e.g. Assuming your function looks like:310 311::312 313 def thread_printer_func (thread,unused):314 return "Thread %s has %d frames\n" % (thread.name, thread.num_frames)315 316And you set it up with:317 318::319 320 (lldb) settings set thread-format "${script.thread:thread_printer_func}"321 322you would see output like:323 324::325 326 * Thread main has 21 frames327 328Function Name Formats329_____________________330 331The function names displayed in backtraces/``frame info``/``thread info`` are the demangled names of functions. On some platforms (like ones using Itanium the mangling scheme), LLDB supports decomposing these names into fine-grained components. These are currently:332 333- ``${function.return-left}``334- ``${function.prefix}``335- ``${function.scope}``336- ``${function.basename}``337- ``${function.name-qualifiers}``338- ``${function.template-arguments}``339- ``${function.formatted-arguments}``340- ``${function.qualifiers}``341- ``${function.return-right}``342- ``${function.suffix}``343 344Each language plugin decides how to handle these variables. For C++, LLDB uses these variables to dictate how function names are formatted. This can be customized using the ``plugin.cplusplus.display.function-name-format`` LLDB setting.345 346E.g., the following setting would reconstruct the entire function name (and is LLDB's default):347 348::349 350 (lldb) settings set plugin.cplusplus.display.function-name-format "${function.return-left}${function.scope}${function.basename}${function.template-arguments}${function.formatted-arguments}${function.qualifiers}${function.return-right}${function.suffix}"351 352If a user wanted to only print the name and arguments of a C++ function one could do:353 354::355 356 (lldb) settings set plugin.cplusplus.display.function-name-format "${function.scope}${function.basename}${function.formatted-arguments}"357 358 359Then the following would highlight just the basename in green:360 361::362 363 (lldb) settings set plugin.cplusplus.display.function-name-format "${function.scope}${ansi.fg.yellow}${function.basename}${ansi.normal}${function.formatted-arguments}"364 365The ``${function.name-with-args}`` by default asks the language plugin whether it supports a language-specific ``function-name-format`` (e.g., the ``plugin.cplusplus.display.function-name-format`` for C++), and if it does, uses it. Otherwise it will display the demangled function name.366