572 lines · plain
1llvm-symbolizer - convert addresses into source code locations2==============================================================3 4.. program:: llvm-symbolizer5 6SYNOPSIS7--------8 9:program:`llvm-symbolizer` [*options*] [*addresses...*]10 11DESCRIPTION12-----------13 14:program:`llvm-symbolizer` reads input names and addresses from the command-line15and prints corresponding source code locations to standard output. It can also16symbolize logs containing :doc:`Symbolizer Markup </SymbolizerMarkupFormat>` via17:option:`--filter-markup`. Addresses may be specified as numbers or symbol names.18 19If no address is specified on the command-line, it reads the addresses from20standard input. If no input name is specified on the command-line, but addresses21are, the first address value is treated as an input name. If an input value is not22recognized, it reports that source information is not found.23 24Input names can be specified together with the addresses either on standard25input or as positional arguments on the command-line. By default, input names26are interpreted as object file paths. However, prefixing a name with27``BUILDID:`` states that it is a hex build ID rather than a path. This will look28up the corresponding debug binary. For consistency, prefixing a name with29``FILE:`` explicitly states that it is an object file path (the default).30 31A positional argument or standard input value can be preceded by "DATA" or32"CODE" to indicate that the address should be symbolized as data or executable33code respectively. If neither is specified, "CODE" is assumed. DATA is34symbolized as address and symbol size rather than line number.35 36:program:`llvm-symbolizer` parses options from the environment variable37``LLVM_SYMBOLIZER_OPTS`` after parsing options from the command line.38``LLVM_SYMBOLIZER_OPTS`` is primarily useful for supplementing the command-line39options when :program:`llvm-symbolizer` is invoked by another program or40runtime.41 42EXAMPLES43--------44 45All of the following examples use the following two source files as input. They46use a mixture of C-style and C++-style linkage to illustrate how these names are47printed differently (see :option:`--demangle`).48 49.. code-block:: c50 51 // test.h52 extern "C" inline int foz() {53 return 1234;54 }55 56.. code-block:: c57 58 // test.cpp59 #include "test.h"60 int bar=42;61 62 int foo() {63 return bar;64 }65 66 int baz() {67 volatile int k = 42;68 return foz() + k;69 }70 71 int main() {72 return foo() + baz();73 }74 75These files are built as follows:76 77.. code-block:: console78 79 $ clang -g test.cpp -o test.elf80 $ clang -g -O2 test.cpp -o inlined.elf81 82Example 1 - addresses and object on command-line:83 84.. code-block:: console85 86 $ llvm-symbolizer --obj=test.elf 0x4004d0 0x40049087 foz88 /tmp/test.h:1:089 90 baz()91 /tmp/test.cpp:11:092 93Example 2 - addresses on standard input:94 95.. code-block:: console96 97 $ cat addr.txt98 0x4004a099 0x400490100 0x4004d0101 $ llvm-symbolizer --obj=test.elf < addr.txt102 main103 /tmp/test.cpp:15:0104 105 baz()106 /tmp/test.cpp:11:0107 108 foz109 /tmp/./test.h:1:0110 111Example 3 - object specified with address:112 113.. code-block:: console114 115 $ llvm-symbolizer "test.elf 0x400490" "FILE:inlined.elf 0x400480"116 baz()117 /tmp/test.cpp:11:0118 119 foo()120 /tmp/test.cpp:8:10121 122 $ cat addr2.txt123 FILE:test.elf 0x4004a0124 inlined.elf 0x400480125 126 $ llvm-symbolizer < addr2.txt127 main128 /tmp/test.cpp:15:0129 130 foo()131 /tmp/test.cpp:8:10132 133Example 4 - BUILDID and FILE prefixes:134 135.. code-block:: console136 137 $ llvm-symbolizer "FILE:test.elf 0x400490" "DATA BUILDID:123456789abcdef 0x601028"138 baz()139 /tmp/test.cpp:11:0140 141 bar142 6295592 4143 144 $ cat addr3.txt145 FILE:test.elf 0x400490146 DATA BUILDID:123456789abcdef 0x601028147 148 $ llvm-symbolizer < addr3.txt149 baz()150 /tmp/test.cpp:11:0151 152 bar153 6295592 4154 155Example 5 - CODE and DATA prefixes:156 157.. code-block:: console158 159 $ llvm-symbolizer --obj=test.elf "CODE 0x400490" "DATA 0x601028"160 baz()161 /tmp/test.cpp:11:0162 163 bar164 6295592 4165 166 $ cat addr4.txt167 CODE test.elf 0x4004a0168 DATA inlined.elf 0x601028169 170 $ llvm-symbolizer < addr4.txt171 main172 /tmp/test.cpp:15:0173 174 bar175 6295592 4176 177Example 6 - path-style options:178 179This example uses the same source file as above, but the source file's180full path is /tmp/foo/test.cpp and is compiled as follows. The first case181shows the default absolute path, the second --basenames, and the third182shows --relativenames.183 184.. code-block:: console185 186 $ pwd187 /tmp188 $ clang -g foo/test.cpp -o test.elf189 $ llvm-symbolizer --obj=test.elf 0x4004a0190 main191 /tmp/foo/test.cpp:15:0192 $ llvm-symbolizer --obj=test.elf 0x4004a0 --basenames193 main194 test.cpp:15:0195 $ llvm-symbolizer --obj=test.elf 0x4004a0 --relativenames196 main197 foo/test.cpp:15:0198 199Example 7 - Addresses as symbol names:200 201.. code-block:: console202 203 $ llvm-symbolizer --obj=test.elf main204 main205 /tmp/test.cpp:14:0206 $ llvm-symbolizer --obj=test.elf "CODE foz"207 foz208 /tmp/test.h:1:0209 210Example 8 - :option:`--skip-line-zero` output for an address with no line correspondence (an address associated with line zero):211 212.. code-block:: c213 214 // test.c215 int foo = 0;216 int x = 1234;217 int main() {218 if (x)219 return foo;220 else221 return x;222 }223 224These files are built as follows:225 226.. code-block:: console227 228 $ clang -g -O2 -S test.c -o test.s229 $ llvm-mc -filetype=obj -triple=x86_64-unknown-linux test.s -o test.o230 231.. code-block:: console232 233 $ llvm-symbolizer --obj=test.o --skip-line-zero 0xa234 main235 /tmp/test.c:5:7 (approximate)236 237OPTIONS238-------239 240.. option:: --adjust-vma <offset>241 242 Add the specified offset to object file addresses when performing lookups.243 This can be used to perform lookups as if the object were relocated by the244 offset.245 246.. option:: --skip-line-zero247 248 If an address does not have an associated line number, use the last line249 number from the current sequence in the line-table. Such lines are labeled250 as "approximate" in the output as they may be misleading.251 252.. option:: --basenames, -s253 254 Print just the file's name without any directories, instead of the255 absolute path.256 257.. option:: --build-id258 259 Look up the object using the given build ID, specified as a hexadecimal260 string. Mutually exclusive with :option:`--obj`.261 262.. option:: --color [=<always|auto|never>]263 264 Specify whether to use color in :option:`--filter-markup` mode. Defaults to265 ``auto``, which detects whether standard output supports color. Specifying266 ``--color`` alone is equivalent to ``--color=always``.267 268.. option:: --debug-file-directory <path>269 270 Provide a path to a directory with a `.build-id` subdirectory to search for271 debug information for stripped binaries. Multiple instances of this argument272 are searched in the order given.273 274.. option:: --debuginfod, --no-debuginfod275 276 Whether or not to try debuginfod lookups for debug binaries. Unless specified,277 debuginfod is only enabled if libcurl was compiled in (``LLVM_ENABLE_CURL``)278 and at least one server URL was provided by the environment variable279 ``DEBUGINFOD_URLS``.280 281.. _llvm-symbolizer-opt-C:282 283.. option:: --demangle, -C284 285 Print demangled function names, if the names are mangled (e.g. the mangled286 name `_Z3bazv` becomes `baz()`, whilst the non-mangled name `foz` is printed287 as is). Defaults to true.288 289.. option:: --dwp <path>290 291 Use the specified DWP file at ``<path>`` for any CUs that have split DWARF292 debug data.293 294.. option:: --fallback-debug-path <path>295 296 When a separate file contains debug data, and is referenced by a GNU debug297 link section, use the specified path as a basis for locating the debug data if298 it cannot be found relative to the object.299 300.. option:: --filter-markup301 302 Reads from standard input, converts contained303 :doc:`Symbolizer Markup </SymbolizerMarkupFormat>` into human-readable form,304 and prints the results to standard output. The following markup elements are305 not yet supported:306 307 * ``{{{hexdict}}}``308 * ``{{{dumpfile}}}``309 310 The ``{{{bt}}}`` backtrace element reports frames using the following syntax:311 312 ``#<number>[.<inline>] <address> <function> <file>:<line>:<col> (<module>+<relative address>)``313 314 ``<inline>`` provides frame numbers for calls inlined into the caller315 corresponding to ``<number>``. The inlined call numbers start at 1 and increase316 from callee to caller.317 318 ``<address>`` is an address inside the call instruction to the function. The319 address may not be the start of the instruction. ``<relative address>`` is320 the corresponding virtual offset in the ``<module>`` loaded at that address.321 322 323.. _llvm-symbolizer-opt-f:324 325.. option:: --functions [=<none|short|linkage>], -f326 327 Specify the way function names are printed (omit function name, print short328 function name, or print full linkage name, respectively). Defaults to329 ``linkage``.330 331.. option:: --help, -h332 333 Show help and usage for this command.334 335.. _llvm-symbolizer-opt-i:336 337.. option:: --inlining, --inlines, -i338 339 If a source code location is in an inlined function, prints all the inlined340 frames. This is the default.341 342.. option:: --no-inlines343 344 Don't print inlined frames.345 346.. option:: --no-demangle347 348 Don't print demangled function names.349 350.. option:: --obj <path>, --exe, -e351 352 Path to object file to be symbolized. If ``-`` is specified, read the object353 directly from the standard input stream. Mutually exclusive with354 :option:`--build-id`.355 356.. _llvm-symbolizer-opt-output-style:357 358.. option:: --output-style <LLVM|GNU|JSON>359 360 Specify the preferred output style. Defaults to ``LLVM``. When the output361 style is set to ``GNU``, the tool follows the style of GNU's **addr2line**.362 The differences from the ``LLVM`` style are:363 364 * Does not print the column of a source code location.365 366 * Does not add an empty line after the report for an address.367 368 * Does not replace the name of an inlined function with the name of the369 topmost caller when inlined frames are not shown.370 371 * Prints an address's debug-data discriminator when it is non-zero. One way to372 produce discriminators is to compile with clang's -fdebug-info-for-profiling.373 374 ``JSON`` style provides a machine-readable output in JSON. If addresses are375 supplied via stdin, the output JSON will be a series of individual objects.376 Otherwise, all results will be contained in a single array.377 378 .. code-block:: console379 380 $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p381 baz() at /tmp/test.cpp:11:18382 (inlined by) main at /tmp/test.cpp:15:0383 384 foo() at /tmp/test.cpp:6:3385 386 $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines387 main at /tmp/test.cpp:11:18388 389 foo() at /tmp/test.cpp:6:3390 391 $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines392 baz() at /tmp/test.cpp:11393 foo() at /tmp/test.cpp:6394 395 $ clang -g -fdebug-info-for-profiling test.cpp -o profiling.elf396 $ llvm-symbolizer --output-style=GNU --obj=profiling.elf 0x401167 -p --no-inlines397 main at /tmp/test.cpp:15 (discriminator 2)398 399 $ llvm-symbolizer --output-style=JSON --obj=inlined.elf 0x4004be 0x400486 -p400 [401 {402 "Address": "0x4004be",403 "ModuleName": "inlined.elf",404 "Symbol": [405 {406 "Column": 18,407 "Discriminator": 0,408 "FileName": "/tmp/test.cpp",409 "FunctionName": "baz()",410 "Line": 11,411 "StartAddress": "0x4004be",412 "StartFileName": "/tmp/test.cpp",413 "StartLine": 9414 },415 {416 "Column": 0,417 "Discriminator": 0,418 "FileName": "/tmp/test.cpp",419 "FunctionName": "main",420 "Line": 15,421 "StartAddress": "0x4004be",422 "StartFileName": "/tmp/test.cpp",423 "StartLine": 14424 }425 ]426 },427 {428 "Address": "0x400486",429 "ModuleName": "inlined.elf",430 "Symbol": [431 {432 "Column": 3,433 "Discriminator": 0,434 "FileName": "/tmp/test.cpp",435 "FunctionName": "foo()",436 "Line": 6,437 "StartAddress": "0x400486",438 "StartFileName": "/tmp/test.cpp",439 "StartLine": 5440 }441 ]442 }443 ]444 445.. option:: --pretty-print, -p446 447 Print human-readable output. If :option:`--inlining` is specified, the448 enclosing scope is prefixed by (inlined by).449 For JSON output, the option will cause JSON to be indented and split over450 new lines. Otherwise, the JSON output will be printed in a compact form.451 452 .. code-block:: console453 454 $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print455 baz() at /tmp/test.cpp:11:18456 (inlined by) main at /tmp/test.cpp:15:0457 458.. option:: --print-address, --addresses, -a459 460 Print address before the source code location. Defaults to false.461 462 .. code-block:: console463 464 $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be465 0x4004be466 baz()467 /tmp/test.cpp:11:18468 main469 /tmp/test.cpp:15:0470 471 $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address472 0x4004be: baz() at /tmp/test.cpp:11:18473 (inlined by) main at /tmp/test.cpp:15:0474 475.. option:: --print-source-context-lines <N>476 477 Print ``N`` lines of source context for each symbolized address.478 479 .. code-block:: console480 481 $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=3482 baz()483 /tmp/test.cpp:11:0484 10 : volatile int k = 42;485 11 >: return foz() + k;486 12 : }487 488.. option:: --relativenames489 490 Print the file's path relative to the compilation directory, instead491 of the absolute path. If the command-line to the compiler included492 the full path, this will be the same as the default.493 494.. option:: --verbose495 496 Print verbose address, line and column information.497 498 .. code-block:: console499 500 $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be501 baz()502 Filename: /tmp/test.cpp503 Function start filename: /tmp/test.cpp504 Function start line: 9505 Function start address: 0x4004b6506 Line: 11507 Column: 18508 main509 Filename: /tmp/test.cpp510 Function start filename: /tmp/test.cpp511 Function start line: 14512 Function start address: 0x4004b0513 Line: 15514 Column: 18515 516.. option:: --version, -v517 518 Print version information for the tool.519 520.. option:: @<FILE>521 522 Read command-line options from response file `<FILE>`.523 524WINDOWS/PDB SPECIFIC OPTIONS525-----------------------------526 527.. option:: --dia528 529 Use the Windows DIA SDK for symbolization. If the DIA SDK is not found,530 llvm-symbolizer will fall back to the native implementation.531 532MACH-O SPECIFIC OPTIONS533-----------------------534 535.. option:: --default-arch <arch>536 537 If a binary contains object files for multiple architectures (e.g. it is a538 Mach-O universal binary), symbolize the object file for a given architecture.539 You can also specify the architecture by writing ``binary_name:arch_name`` in540 the input (see example below). If the architecture is not specified in either541 way, the address will not be symbolized. Defaults to empty string.542 543 .. code-block:: console544 545 $ cat addr.txt546 /tmp/mach_universal_binary:i386 0x1f84547 /tmp/mach_universal_binary:x86_64 0x100000f24548 549 $ llvm-symbolizer < addr.txt550 _main551 /tmp/source_i386.cc:8552 553 _main554 /tmp/source_x86_64.cc:8555 556.. option:: --dsym-hint <path/to/file.dSYM>557 558 If the debug info for a binary isn't present in the default location, look for559 the debug info at the .dSYM path provided via this option. This flag can be560 used multiple times.561 562EXIT STATUS563-----------564 565:program:`llvm-symbolizer` returns 0. Other exit codes imply an internal program566error.567 568SEE ALSO569--------570 571:manpage:`llvm-addr2line(1)`572