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 OPTIONS
 211 -------
 212
 213 .. option:: --adjust-vma <offset>
 214
 215   Add the specified offset to object file addresses when performing lookups.
 216   This can be used to perform lookups as if the object were relocated by the
 217   offset.
 218
 219 .. option:: --basenames, -s
 220
 221   Print just the file's name without any directories, instead of the
 222   absolute path.
 223
 224 .. option:: --build-id
 225
 226   Look up the object using the given build ID, specified as a hexadecimal
 227   string. Mutually exclusive with :option:`--obj`.
 228
 229 .. option:: --color [=<always|auto|never>]
 230
 231   Specify whether to use color in :option:`--filter-markup` mode. Defaults to
 232   ``auto``, which detects whether standard output supports color. Specifying
 233   ``--color`` alone is equivalent to ``--color=always``.
 234
 235 .. option:: --debug-file-directory <path>
 236
 237   Provide a path to a directory with a `.build-id` subdirectory to search for
 238   debug information for stripped binaries. Multiple instances of this argument
 239   are searched in the order given.
 240
 241 .. option:: --debuginfod, --no-debuginfod
 242
 243   Whether or not to try debuginfod lookups for debug binaries. Unless specified,
 244   debuginfod is only enabled if libcurl was compiled in (``LLVM_ENABLE_CURL``)
 245   and at least one server URL was provided by the environment variable
 246   ``DEBUGINFOD_URLS``.
 247
 248 .. _llvm-symbolizer-opt-C:
 249
 250 .. option:: --demangle, -C
 251
 252   Print demangled function names, if the names are mangled (e.g. the mangled
 253   name `_Z3bazv` becomes `baz()`, whilst the non-mangled name `foz` is printed
 254   as is). Defaults to true.
 255
 256 .. option:: --dwp <path>
 257
 258   Use the specified DWP file at ``<path>`` for any CUs that have split DWARF
 259   debug data.
 260
 261 .. option:: --fallback-debug-path <path>
 262
 263   When a separate file contains debug data, and is referenced by a GNU debug
 264   link section, use the specified path as a basis for locating the debug data if
 265   it cannot be found relative to the object.
 266
 267 .. option:: --filter-markup
 268
 269   Reads from standard input, converts contained
 270   :doc:`Symbolizer Markup </SymbolizerMarkupFormat>` into human-readable form,
 271   and prints the results to standard output. The following markup elements are
 272   not yet supported:
 273
 274   * ``{{{hexdict}}}``
 275   * ``{{{dumpfile}}}``
 276
 277   The ``{{{bt}}}`` backtrace element reports frames using the following syntax:
 278
 279   ``#<number>[.<inline>] <address> <function> <file>:<line>:<col> (<module>+<relative address>)``
 280
 281   ``<inline>`` provides frame numbers for calls inlined into the caller
 282   corresponding to ``<number>``. The inlined call numbers start at 1 and increase
 283   from callee to caller.
 284
 285   ``<address>`` is an address inside the call instruction to the function.  The
 286   address may not be the start of the instruction.  ``<relative address>`` is
 287   the corresponding virtual offset in the ``<module>`` loaded at that address.
 288
 289
 290 .. _llvm-symbolizer-opt-f:
 291
 292 .. option:: --functions [=<none|short|linkage>], -f
 293
 294   Specify the way function names are printed (omit function name, print short
 295   function name, or print full linkage name, respectively). Defaults to
 296   ``linkage``.
 297
 298 .. option:: --help, -h
 299
 300   Show help and usage for this command.
 301
 302 .. _llvm-symbolizer-opt-i:
 303
 304 .. option:: --inlining, --inlines, -i
 305
 306   If a source code location is in an inlined function, prints all the inlined
 307   frames. This is the default.
 308
 309 .. option:: --no-inlines
 310
 311   Don't print inlined frames.
 312
 313 .. option:: --no-demangle
 314
 315   Don't print demangled function names.
 316
 317 .. option:: --obj <path>, --exe, -e
 318
 319   Path to object file to be symbolized. If ``-`` is specified, read the object
 320   directly from the standard input stream. Mutually exclusive with
 321   :option:`--build-id`.
 322
 323 .. _llvm-symbolizer-opt-output-style:
 324
 325 .. option:: --output-style <LLVM|GNU|JSON>
 326
 327   Specify the preferred output style. Defaults to ``LLVM``. When the output
 328   style is set to ``GNU``, the tool follows the style of GNU's **addr2line**.
 329   The differences from the ``LLVM`` style are:
 330
 331   * Does not print the column of a source code location.
 332
 333   * Does not add an empty line after the report for an address.
 334
 335   * Does not replace the name of an inlined function with the name of the
 336     topmost caller when inlined frames are not shown.
 337
 338   * Prints an address's debug-data discriminator when it is non-zero. One way to
 339     produce discriminators is to compile with clang's -fdebug-info-for-profiling.
 340
 341   ``JSON`` style provides a machine readable output in JSON. If addresses are
 342     supplied via stdin, the output JSON will be a series of individual objects.
 343     Otherwise, all results will be contained in a single array.
 344
 345   .. code-block:: console
 346
 347     $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
 348     baz() at /tmp/test.cpp:11:18
 349      (inlined by) main at /tmp/test.cpp:15:0
 350
 351     foo() at /tmp/test.cpp:6:3
 352
 353     $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
 354     main at /tmp/test.cpp:11:18
 355
 356     foo() at /tmp/test.cpp:6:3
 357
 358     $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
 359     baz() at /tmp/test.cpp:11
 360     foo() at /tmp/test.cpp:6
 361
 362     $ clang -g -fdebug-info-for-profiling test.cpp -o profiling.elf
 363     $ llvm-symbolizer --output-style=GNU --obj=profiling.elf 0x401167 -p --no-inlines
 364     main at /tmp/test.cpp:15 (discriminator 2)
 365
 366     $ llvm-symbolizer --output-style=JSON --obj=inlined.elf 0x4004be 0x400486 -p
 367     [
 368       {
 369         "Address": "0x4004be",
 370         "ModuleName": "inlined.elf",
 371         "Symbol": [
 372           {
 373             "Column": 18,
 374             "Discriminator": 0,
 375             "FileName": "/tmp/test.cpp",
 376             "FunctionName": "baz()",
 377             "Line": 11,
 378             "StartAddress": "0x4004be",
 379             "StartFileName": "/tmp/test.cpp",
 380             "StartLine": 9
 381           },
 382           {
 383             "Column": 0,
 384             "Discriminator": 0,
 385             "FileName": "/tmp/test.cpp",
 386             "FunctionName": "main",
 387             "Line": 15,
 388             "StartAddress": "0x4004be",
 389             "StartFileName": "/tmp/test.cpp",
 390             "StartLine": 14
 391           }
 392         ]
 393       },
 394       {
 395         "Address": "0x400486",
 396         "ModuleName": "inlined.elf",
 397         "Symbol": [
 398           {
 399             "Column": 3,
 400             "Discriminator": 0,
 401             "FileName": "/tmp/test.cpp",
 402             "FunctionName": "foo()",
 403             "Line": 6,
 404             "StartAddress": "0x400486",
 405             "StartFileName": "/tmp/test.cpp",
 406             "StartLine": 5
 407           }
 408         ]
 409       }
 410     ]
 411
 412 .. option:: --pretty-print, -p
 413
 414   Print human readable output. If :option:`--inlining` is specified, the
 415   enclosing scope is prefixed by (inlined by).
 416   For JSON output, the option will cause JSON to be indented and split over
 417   new lines. Otherwise, the JSON output will be printed in a compact form.
 418
 419   .. code-block:: console
 420
 421     $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
 422     baz() at /tmp/test.cpp:11:18
 423      (inlined by) main at /tmp/test.cpp:15:0
 424
 425 .. option:: --print-address, --addresses, -a
 426
 427   Print address before the source code location. Defaults to false.
 428
 429   .. code-block:: console
 430
 431     $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
 432     0x4004be
 433     baz()
 434     /tmp/test.cpp:11:18
 435     main
 436     /tmp/test.cpp:15:0
 437
 438     $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
 439     0x4004be: baz() at /tmp/test.cpp:11:18
 440      (inlined by) main at /tmp/test.cpp:15:0
 441
 442 .. option:: --print-source-context-lines <N>
 443
 444   Print ``N`` lines of source context for each symbolized address.
 445
 446   .. code-block:: console
 447
 448     $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=3
 449     baz()
 450     /tmp/test.cpp:11:0
 451     10  :   volatile int k = 42;
 452     11 >:   return foz() + k;
 453     12  : }
 454
 455 .. option:: --relativenames
 456
 457   Print the file's path relative to the compilation directory, instead
 458   of the absolute path. If the command-line to the compiler included
 459   the full path, this will be the same as the default.
 460
 461 .. option:: --verbose
 462
 463   Print verbose address, line and column information.
 464
 465   .. code-block:: console
 466
 467     $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
 468     baz()
 469       Filename: /tmp/test.cpp
 470       Function start filename: /tmp/test.cpp
 471       Function start line: 9
 472       Function start address: 0x4004b6
 473       Line: 11
 474       Column: 18
 475     main
 476       Filename: /tmp/test.cpp
 477       Function start filename: /tmp/test.cpp
 478       Function start line: 14
 479       Function start address: 0x4004b0
 480       Line: 15
 481       Column: 18
 482
 483 .. option:: --version, -v
 484
 485   Print version information for the tool.
 486
 487 .. option:: @<FILE>
 488
 489   Read command-line options from response file `<FILE>`.
 490
 491 WINDOWS/PDB SPECIFIC OPTIONS
 492 -----------------------------
 493
 494 .. option:: --dia
 495
 496   Use the Windows DIA SDK for symbolization. If the DIA SDK is not found,
 497   llvm-symbolizer will fall back to the native implementation.
 498
 499 MACH-O SPECIFIC OPTIONS
 500 -----------------------
 501
 502 .. option:: --default-arch <arch>
 503
 504   If a binary contains object files for multiple architectures (e.g. it is a
 505   Mach-O universal binary), symbolize the object file for a given architecture.
 506   You can also specify the architecture by writing ``binary_name:arch_name`` in
 507   the input (see example below). If the architecture is not specified in either
 508   way, the address will not be symbolized. Defaults to empty string.
 509
 510   .. code-block:: console
 511
 512     $ cat addr.txt
 513     /tmp/mach_universal_binary:i386 0x1f84
 514     /tmp/mach_universal_binary:x86_64 0x100000f24
 515
 516     $ llvm-symbolizer < addr.txt
 517     _main
 518     /tmp/source_i386.cc:8
 519
 520     _main
 521     /tmp/source_x86_64.cc:8
 522
 523 .. option:: --dsym-hint <path/to/file.dSYM>
 524
 525   If the debug info for a binary isn't present in the default location, look for
 526   the debug info at the .dSYM path provided via this option. This flag can be
 527   used multiple times.
 528
 529 EXIT STATUS
 530 -----------
 531
 532 :program:`llvm-symbolizer` returns 0. Other exit codes imply an internal program
 533 error.
 534
 535 SEE ALSO
 536 --------
 537
 538 :manpage:`llvm-addr2line(1)`