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. _______________________________________________ lldb-commits mailing list lldb-commits@lists.llvm.org https://lists.llvm.org/cgi-bin/mailman/listinfo/lldb-commits
