llvm/docs/CommandGuide/llvm-symbolizer.rst

   1 llvm-symbolizer - convert addresses into source code locations
   2 ==============================================================
   3
   4 .. program:: llvm-symbolizer
   5
   6 SYNOPSIS
   7 --------
   8
   9 :program:`llvm-symbolizer` [*options*] [*addresses...*]
  10
  11 DESCRIPTION
  12 -----------
  13
  14 :program:`llvm-symbolizer` reads input names and addresses from the command-line
  15 and prints corresponding source code locations to standard output. It can also
  16 symbolize logs containing :doc:`Symbolizer Markup </SymbolizerMarkupFormat>` via
  17 :option:`--filter-markup`. Addresses may be specified as numbers or symbol names.
  18
  19 If no address is specified on the command-line, it reads the addresses from
  20 standard input. If no input name is specified on the command-line, but addresses
  21 are, the first address value is treated as an input name. If an input value is not
  22 recognized, it reports that source information is not found.
  23
  24 Input names can be specified together with the addresses either on standard
  25 input or as positional arguments on the command-line. By default, input names
  26 are interpreted as object file paths. However, prefixing a name with
  27 ``BUILDID:`` states that it is a hex build ID rather than a path. This will look
  28 up the corresponding debug binary. For consistency, prefixing a name with
  29 ``FILE:`` explicitly states that it is an object file path (the default).
  30
  31 A positional argument or standard input value can be preceded by "DATA" or
  32 "CODE" to indicate that the address should be symbolized as data or executable
  33 code respectively. If neither is specified, "CODE" is assumed. DATA is
  34 symbolized as address and symbol size rather than line number.
  35
  36 :program:`llvm-symbolizer` parses options from the environment variable
  37 ``LLVM_SYMBOLIZER_OPTS`` after parsing options from the command line.
  38 ``LLVM_SYMBOLIZER_OPTS`` is primarily useful for supplementing the command-line
  39 options when :program:`llvm-symbolizer` is invoked by another program or
  40 runtime.
  41
  42 EXAMPLES
  43 --------
  44
  45 All of the following examples use the following two source files as input. They
  46 use a mixture of C-style and C++-style linkage to illustrate how these names are
  47 printed differently (see :option:`--demangle`).
  48
  49 .. code-block:: c
  50
  51   // test.h
  52   extern "C" inline int foz() {
  53     return 1234;
  54   }
  55
  56 .. code-block:: c
  57
  58   // test.cpp
  59   #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
  75 These files are built as follows:
  76
  77 .. code-block:: console
  78
  79   $ clang -g test.cpp -o test.elf
  80   $ clang -g -O2 test.cpp -o inlined.elf
  81
  82 Example 1 - addresses and object on command-line:
  83
  84 .. code-block:: console
  85
  86   $ llvm-symbolizer --obj=test.elf 0x4004d0 0x400490
  87   foz
  88   /tmp/test.h:1:0
  89
  90   baz()
  91   /tmp/test.cpp:11:0
  92
  93 Example 2 - addresses on standard input:
  94
  95 .. code-block:: console
  96
  97   $ cat addr.txt
  98   0x4004a0
  99   0x400490
 100   0x4004d0
 101   $ llvm-symbolizer --obj=test.elf < addr.txt
 102   main
 103   /tmp/test.cpp:15:0
 104
 105   baz()
 106   /tmp/test.cpp:11:0
 107
 108   foz
 109   /tmp/./test.h:1:0
 110
 111 Example 3 - object specified with address:
 112
 113 .. code-block:: console
 114
 115   $ llvm-symbolizer "test.elf 0x400490" "FILE:inlined.elf 0x400480"
 116   baz()
 117   /tmp/test.cpp:11:0
 118
 119   foo()
 120   /tmp/test.cpp:8:10
 121
 122   $ cat addr2.txt
 123   FILE:test.elf 0x4004a0
 124   inlined.elf 0x400480
 125
 126   $ llvm-symbolizer < addr2.txt
 127   main
 128   /tmp/test.cpp:15:0
 129
 130   foo()
 131   /tmp/test.cpp:8:10
 132
 133 Example 4 - BUILDID and FILE prefixes:
 134
 135 .. code-block:: console
 136
 137   $ llvm-symbolizer "FILE:test.elf 0x400490" "DATA BUILDID:123456789abcdef 0x601028"
 138   baz()
 139   /tmp/test.cpp:11:0
 140
 141   bar
 142   6295592 4
 143
 144   $ cat addr3.txt
 145   FILE:test.elf 0x400490
 146   DATA BUILDID:123456789abcdef 0x601028
 147
 148   $ llvm-symbolizer < addr3.txt
 149   baz()
 150   /tmp/test.cpp:11:0
 151
 152   bar
 153   6295592 4
 154
 155 Example 5 - CODE and DATA prefixes:
 156
 157 .. code-block:: console
 158
 159   $ llvm-symbolizer --obj=test.elf "CODE 0x400490" "DATA 0x601028"
 160   baz()
 161   /tmp/test.cpp:11:0
 162
 163   bar
 164   6295592 4
 165
 166   $ cat addr4.txt
 167   CODE test.elf 0x4004a0
 168   DATA inlined.elf 0x601028
 169
 170   $ llvm-symbolizer < addr4.txt
 171   main
 172   /tmp/test.cpp:15:0
 173
 174   bar
 175   6295592 4
 176
 177 Example 6 - path-style options:
 178
 179 This example uses the same source file as above, but the source file's
 180 full path is /tmp/foo/test.cpp and is compiled as follows. The first case
 181 shows the default absolute path, the second --basenames, and the third
 182 shows --relativenames.
 183
 184 .. code-block:: console
 185
 186   $ pwd
 187   /tmp
 188   $ clang -g foo/test.cpp -o test.elf
 189   $ llvm-symbolizer --obj=test.elf 0x4004a0
 190   main
 191   /tmp/foo/test.cpp:15:0
 192   $ llvm-symbolizer --obj=test.elf 0x4004a0 --basenames
 193   main
 194   test.cpp:15:0
 195   $ llvm-symbolizer --obj=test.elf 0x4004a0 --relativenames
 196   main
 197   foo/test.cpp:15:0
 198
 199 Example 7 - Addresses as symbol names:
 200
 201 .. code-block:: console
 202
 203   $ llvm-symbolizer --obj=test.elf main
 204   main
 205   /tmp/test.cpp:14:0
 206   $ llvm-symbolizer --obj=test.elf "CODE foz"
 207   foz
 208   /tmp/test.h:1:0
 209
 210 Example 8 - :option:`--skip-line-zero` output for an address with no line correspondence (an address associated with line zero):
 211
 212 .. code-block:: c
 213
 214   // test.c
 215   int foo = 0;
 216   int x = 1234;
 217   int main() {
 218     if (x)
 219       return foo;
 220     else
 221       return x;
 222   }
 223
 224 These files are built as follows:
 225
 226 .. code-block:: console
 227
 228   $ clang -g -O2 -S test.c -o test.s
 229   $ llvm-mc -filetype=obj -triple=x86_64-unknown-linux  test.s -o test.o
 230
 231 .. code-block:: console
 232
 233   $ llvm-symbolizer --obj=test.o --skip-line-zero 0xa
 234   main
 235   /tmp/test.c:5:7 (approximate)
 236
 237 OPTIONS
 238 -------
 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 the
 244   offset.
 245
 246 .. option:: --skip-line-zero
 247
 248   If an address does not have an associated line number, use the last line
 249   number from the current sequence in the line-table. Such lines are labeled
 250   as "approximate" in the output as they may be misleading.
 251
 252 .. option:: --basenames, -s
 253
 254   Print just the file's name without any directories, instead of the
 255   absolute path.
 256
 257 .. option:: --build-id
 258
 259   Look up the object using the given build ID, specified as a hexadecimal
 260   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 to
 265   ``auto``, which detects whether standard output supports color. Specifying
 266   ``--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 for
 271   debug information for stripped binaries. Multiple instances of this argument
 272   are searched in the order given.
 273
 274 .. option:: --debuginfod, --no-debuginfod
 275
 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 variable
 279   ``DEBUGINFOD_URLS``.
 280
 281 .. _llvm-symbolizer-opt-C:
 282
 283 .. option:: --demangle, -C
 284
 285   Print demangled function names, if the names are mangled (e.g. the mangled
 286   name `_Z3bazv` becomes `baz()`, whilst the non-mangled name `foz` is printed
 287   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 DWARF
 292   debug data.
 293
 294 .. option:: --fallback-debug-path <path>
 295
 296   When a separate file contains debug data, and is referenced by a GNU debug
 297   link section, use the specified path as a basis for locating the debug data if
 298   it cannot be found relative to the object.
 299
 300 .. option:: --filter-markup
 301
 302   Reads from standard input, converts contained
 303   :doc:`Symbolizer Markup </SymbolizerMarkupFormat>` into human-readable form,
 304   and prints the results to standard output. The following markup elements are
 305   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 caller
 315   corresponding to ``<number>``. The inlined call numbers start at 1 and increase
 316   from callee to caller.
 317
 318   ``<address>`` is an address inside the call instruction to the function.  The
 319   address may not be the start of the instruction.  ``<relative address>`` is
 320   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>], -f
 326
 327   Specify the way function names are printed (omit function name, print short
 328   function name, or print full linkage name, respectively). Defaults to
 329   ``linkage``.
 330
 331 .. option:: --help, -h
 332
 333   Show help and usage for this command.
 334
 335 .. _llvm-symbolizer-opt-i:
 336
 337 .. option:: --inlining, --inlines, -i
 338
 339   If a source code location is in an inlined function, prints all the inlined
 340   frames. This is the default.
 341
 342 .. option:: --no-inlines
 343
 344   Don't print inlined frames.
 345
 346 .. option:: --no-demangle
 347
 348   Don't print demangled function names.
 349
 350 .. option:: --obj <path>, --exe, -e
 351
 352   Path to object file to be symbolized. If ``-`` is specified, read the object
 353   directly from the standard input stream. Mutually exclusive with
 354   :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 output
 361   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 the
 369     topmost caller when inlined frames are not shown.
 370
 371   * Prints an address's debug-data discriminator when it is non-zero. One way to
 372     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 are
 375     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:: console
 379
 380     $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
 381     baz() at /tmp/test.cpp:11:18
 382      (inlined by) main at /tmp/test.cpp:15:0
 383
 384     foo() at /tmp/test.cpp:6:3
 385
 386     $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
 387     main at /tmp/test.cpp:11:18
 388
 389     foo() at /tmp/test.cpp:6:3
 390
 391     $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
 392     baz() at /tmp/test.cpp:11
 393     foo() at /tmp/test.cpp:6
 394
 395     $ clang -g -fdebug-info-for-profiling test.cpp -o profiling.elf
 396     $ llvm-symbolizer --output-style=GNU --obj=profiling.elf 0x401167 -p --no-inlines
 397     main at /tmp/test.cpp:15 (discriminator 2)
 398
 399     $ llvm-symbolizer --output-style=JSON --obj=inlined.elf 0x4004be 0x400486 -p
 400     [
 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": 9
 414           },
 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": 14
 424           }
 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": 5
 440           }
 441         ]
 442       }
 443     ]
 444
 445 .. option:: --pretty-print, -p
 446
 447   Print human readable output. If :option:`--inlining` is specified, the
 448   enclosing scope is prefixed by (inlined by).
 449   For JSON output, the option will cause JSON to be indented and split over
 450   new lines. Otherwise, the JSON output will be printed in a compact form.
 451
 452   .. code-block:: console
 453
 454     $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
 455     baz() at /tmp/test.cpp:11:18
 456      (inlined by) main at /tmp/test.cpp:15:0
 457
 458 .. option:: --print-address, --addresses, -a
 459
 460   Print address before the source code location. Defaults to false.
 461
 462   .. code-block:: console
 463
 464     $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
 465     0x4004be
 466     baz()
 467     /tmp/test.cpp:11:18
 468     main
 469     /tmp/test.cpp:15:0
 470
 471     $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
 472     0x4004be: baz() at /tmp/test.cpp:11:18
 473      (inlined by) main at /tmp/test.cpp:15:0
 474
 475 .. option:: --print-source-context-lines <N>
 476
 477   Print ``N`` lines of source context for each symbolized address.
 478
 479   .. code-block:: console
 480
 481     $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=3
 482     baz()
 483     /tmp/test.cpp:11:0
 484     10  :   volatile int k = 42;
 485     11 >:   return foz() + k;
 486     12  : }
 487
 488 .. option:: --relativenames
 489
 490   Print the file's path relative to the compilation directory, instead
 491   of the absolute path. If the command-line to the compiler included
 492   the full path, this will be the same as the default.
 493
 494 .. option:: --verbose
 495
 496   Print verbose address, line and column information.
 497
 498   .. code-block:: console
 499
 500     $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
 501     baz()
 502       Filename: /tmp/test.cpp
 503       Function start filename: /tmp/test.cpp
 504       Function start line: 9
 505       Function start address: 0x4004b6
 506       Line: 11
 507       Column: 18
 508     main
 509       Filename: /tmp/test.cpp
 510       Function start filename: /tmp/test.cpp
 511       Function start line: 14
 512       Function start address: 0x4004b0
 513       Line: 15
 514       Column: 18
 515
 516 .. option:: --version, -v
 517
 518   Print version information for the tool.
 519
 520 .. option:: @<FILE>
 521
 522   Read command-line options from response file `<FILE>`.
 523
 524 WINDOWS/PDB SPECIFIC OPTIONS
 525 -----------------------------
 526
 527 .. option:: --dia
 528
 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
 532 MACH-O SPECIFIC OPTIONS
 533 -----------------------
 534
 535 .. option:: --default-arch <arch>
 536
 537   If a binary contains object files for multiple architectures (e.g. it is a
 538   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`` in
 540   the input (see example below). If the architecture is not specified in either
 541   way, the address will not be symbolized. Defaults to empty string.
 542
 543   .. code-block:: console
 544
 545     $ cat addr.txt
 546     /tmp/mach_universal_binary:i386 0x1f84
 547     /tmp/mach_universal_binary:x86_64 0x100000f24
 548
 549     $ llvm-symbolizer < addr.txt
 550     _main
 551     /tmp/source_i386.cc:8
 552
 553     _main
 554     /tmp/source_x86_64.cc:8
 555
 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 for
 559   the debug info at the .dSYM path provided via this option. This flag can be
 560   used multiple times.
 561
 562 EXIT STATUS
 563 -----------
 564
 565 :program:`llvm-symbolizer` returns 0. Other exit codes imply an internal program
 566 error.
 567
 568 SEE ALSO
 569 --------
 570
 571 :manpage:`llvm-addr2line(1)`