[Lldb-commits] [lldb] fcb1a48 - [lldb][docs] Document new frame-format variables (#137522)
via lldb-commits
lldb-commits at lists.llvm.org
Mon Apr 28 00:29:03 PDT 2025
Author: Michael Buch
Date: 2025-04-28T08:28:54+01:00
New Revision: fcb1a481cec002f4e505d165cfba85d8b5986a57
URL: https://github.com/llvm/llvm-project/commit/fcb1a481cec002f4e505d165cfba85d8b5986a57
DIFF: https://github.com/llvm/llvm-project/commit/fcb1a481cec002f4e505d165cfba85d8b5986a57.diff
LOG: [lldb][docs] Document new frame-format variables (#137522)
Documents https://github.com/llvm/llvm-project/pull/131836
Added:
Modified:
lldb/docs/use/formatting.rst
Removed:
################################################################################
diff --git a/lldb/docs/use/formatting.rst b/lldb/docs/use/formatting.rst
index 7b3f01eebc891..a21165a3ecae3 100644
--- a/lldb/docs/use/formatting.rst
+++ b/lldb/docs/use/formatting.rst
@@ -85,10 +85,27 @@ A complete list of currently supported format string variables is listed below:
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``function.name`` | The name of the current function or symbol. |
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
-| ``function.name-with-args`` | The name of the current function with arguments and values or the symbol name. |
+| ``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. |
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``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``) |
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``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``. |
++---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``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>``. |
++---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``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>``. |
++---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``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 |
+| | pretty-printed arguments for ``func(int x, const char *str)`` are ``(x=10, str="Hello")``. Without debug-info it would be ``(int, const char*)``. |
++---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``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 &``. |
++---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``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 |
+| | 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)``. |
++---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| ``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 |
+| | 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)``. |
++---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``function.mangled-name`` | The mangled name of the current function or symbol. |
+---------------------------------------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| ``function.pc-offset`` | The program counter offset within the current function or symbol |
@@ -300,3 +317,38 @@ you would see output like:
* Thread main has 21 frames
+Function Name Formats
+_____________________
+
+The 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:
+
+- ``${function.return-left}``
+- ``${function.scope}``
+- ``${function.basename}``
+- ``${function.template-arguments}``
+- ``${function.formatted-arguments}``
+- ``${function.qualifiers}``
+- ``${function.return-right}``
+
+Each 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.
+
+E.g., the following setting would reconstruct the entire function name (and is LLDB's default):
+
+::
+
+ (lldb) settings set plugin.cplusplus.dislpay.function-name-format "${function.return-left}${function.scope}${function.basename}${function.template-arguments}${function.formatted-arguments}${function.qualifiers}${function.return-right}"
+
+If a user wanted to omit the return type and template arguments of C++ function names one could do:
+
+::
+
+ (lldb) settings set plugin.cplusplus.dislpay.function-name-format "${function.scope}${function.basename}${function.formatted-arguments}${function.qualifiers}"
+
+
+Then the following would highlight just the basename in green:
+
+::
+
+ (lldb) settings set plugin.cplusplus.dislpay.function-name-format "${function.scope}${ansi.fg.yellow}${function.basename}${ansi.normal}${function.formatted-arguments}${function.qualifiers}"
+
+The ``${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.
More information about the lldb-commits
mailing list