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 object file names and addresses from the
  15 command-line and prints corresponding source code locations to standard output.
  16
  17 If no address is specified on the command-line, it reads the addresses from
  18 standard input. If no object file is specified on the command-line, but
  19 addresses are, or if at any time an input value is not recognized, the input is
  20 simply echoed to the output.
  21
  22 A positional argument or standard input value can be preceded by "DATA" or
  23 "CODE" to indicate that the address should be symbolized as data or executable
  24 code respectively. If neither is specified, "CODE" is assumed. DATA is
  25 symbolized as address and symbol size rather than line number.
  26
  27 Object files can be specified together with the addresses either on standard
  28 input or as positional arguments on the command-line, following any "DATA" or
  29 "CODE" prefix.
  30
  31 :program:`llvm-symbolizer` parses options from the environment variable
  32 ``LLVM_SYMBOLIZER_OPTS`` after parsing options from the command line.
  33 ``LLVM_SYMBOLIZER_OPTS`` is primarily useful for supplementing the command-line
  34 options when :program:`llvm-symbolizer` is invoked by another program or
  35 runtime.
  36
  37 EXAMPLES
  38 --------
  39
  40 All of the following examples use the following two source files as input. They
  41 use a mixture of C-style and C++-style linkage to illustrate how these names are
  42 printed differently (see :option:`--demangle`).
  43
  44 .. code-block:: c
  45
  46   // test.h
  47   extern "C" inline int foz() {
  48     return 1234;
  49   }
  50
  51 .. code-block:: c
  52
  53   // test.cpp
  54   #include "test.h"
  55   int bar=42;
  56
  57   int foo() {
  58     return bar;
  59   }
  60
  61   int baz() {
  62     volatile int k = 42;
  63     return foz() + k;
  64   }
  65
  66   int main() {
  67     return foo() + baz();
  68   }
  69
  70 These files are built as follows:
  71
  72 .. code-block:: console
  73
  74   $ clang -g test.cpp -o test.elf
  75   $ clang -g -O2 test.cpp -o inlined.elf
  76
  77 Example 1 - addresses and object on command-line:
  78
  79 .. code-block:: console
  80
  81   $ llvm-symbolizer --obj=test.elf 0x4004d0 0x400490
  82   foz
  83   /tmp/test.h:1:0
  84
  85   baz()
  86   /tmp/test.cpp:11:0
  87
  88 Example 2 - addresses on standard input:
  89
  90 .. code-block:: console
  91
  92   $ cat addr.txt
  93   0x4004a0
  94   0x400490
  95   0x4004d0
  96   $ llvm-symbolizer --obj=test.elf < addr.txt
  97   main
  98   /tmp/test.cpp:15:0
  99
 100   baz()
 101   /tmp/test.cpp:11:0
 102
 103   foz
 104   /tmp/./test.h:1:0
 105
 106 Example 3 - object specified with address:
 107
 108 .. code-block:: console
 109
 110   $ llvm-symbolizer "test.elf 0x400490" "inlined.elf 0x400480"
 111   baz()
 112   /tmp/test.cpp:11:0
 113
 114   foo()
 115   /tmp/test.cpp:8:10
 116
 117   $ cat addr2.txt
 118   test.elf 0x4004a0
 119   inlined.elf 0x400480
 120
 121   $ llvm-symbolizer < addr2.txt
 122   main
 123   /tmp/test.cpp:15:0
 124
 125   foo()
 126   /tmp/test.cpp:8:10
 127
 128 Example 4 - CODE and DATA prefixes:
 129
 130 .. code-block:: console
 131
 132   $ llvm-symbolizer --obj=test.elf "CODE 0x400490" "DATA 0x601028"
 133   baz()
 134   /tmp/test.cpp:11:0
 135
 136   bar
 137   6295592 4
 138
 139   $ cat addr3.txt
 140   CODE test.elf 0x4004a0
 141   DATA inlined.elf 0x601028
 142
 143   $ llvm-symbolizer < addr3.txt
 144   main
 145   /tmp/test.cpp:15:0
 146
 147   bar
 148   6295592 4
 149
 150 Example 5 - path-style options:
 151
 152 This example uses the same source file as above, but the source file's
 153 full path is /tmp/foo/test.cpp and is compiled as follows. The first case
 154 shows the default absolute path, the second --basenames, and the third
 155 shows --relativenames.
 156
 157 .. code-block:: console
 158
 159   $ pwd
 160   /tmp
 161   $ clang -g foo/test.cpp -o test.elf
 162   $ llvm-symbolizer --obj=test.elf 0x4004a0
 163   main
 164   /tmp/foo/test.cpp:15:0
 165   $ llvm-symbolizer --obj=test.elf 0x4004a0 --basenames
 166   main
 167   test.cpp:15:0
 168   $ llvm-symbolizer --obj=test.elf 0x4004a0 --relativenames
 169   main
 170   foo/test.cpp:15:0
 171
 172 OPTIONS
 173 -------
 174
 175 .. option:: --adjust-vma <offset>
 176
 177   Add the specified offset to object file addresses when performing lookups.
 178   This can be used to perform lookups as if the object were relocated by the
 179   offset.
 180
 181 .. option:: --basenames, -s
 182
 183   Print just the file's name without any directories, instead of the
 184   absolute path.
 185
 186 .. _llvm-symbolizer-opt-C:
 187
 188 .. option:: --demangle, -C
 189
 190   Print demangled function names, if the names are mangled (e.g. the mangled
 191   name `_Z3bazv` becomes `baz()`, whilst the non-mangled name `foz` is printed
 192   as is). Defaults to true.
 193
 194 .. option:: --dwp <path>
 195
 196   Use the specified DWP file at ``<path>`` for any CUs that have split DWARF
 197   debug data.
 198
 199 .. option:: --fallback-debug-path <path>
 200
 201   When a separate file contains debug data, and is referenced by a GNU debug
 202   link section, use the specified path as a basis for locating the debug data if
 203   it cannot be found relative to the object.
 204
 205 .. _llvm-symbolizer-opt-f:
 206
 207 .. option:: --functions [=<none|short|linkage>], -f
 208
 209   Specify the way function names are printed (omit function name, print short
 210   function name, or print full linkage name, respectively). Defaults to
 211   ``linkage``.
 212
 213 .. option:: --help, -h
 214
 215   Show help and usage for this command.
 216
 217 .. _llvm-symbolizer-opt-i:
 218
 219 .. option:: --inlining, --inlines, -i
 220
 221   If a source code location is in an inlined function, prints all the inlined
 222   frames. This is the default.
 223
 224 .. option:: --no-inlines
 225
 226   Don't print inlined frames.
 227
 228 .. option:: --no-demangle
 229
 230   Don't print demangled function names.
 231
 232 .. option:: --obj <path>, --exe, -e
 233
 234   Path to object file to be symbolized. If ``-`` is specified, read the object
 235   directly from the standard input stream.
 236
 237 .. _llvm-symbolizer-opt-output-style:
 238
 239 .. option:: --output-style <LLVM|GNU|JSON>
 240
 241   Specify the preferred output style. Defaults to ``LLVM``. When the output
 242   style is set to ``GNU``, the tool follows the style of GNU's **addr2line**.
 243   The differences from the ``LLVM`` style are:
 244
 245   * Does not print the column of a source code location.
 246
 247   * Does not add an empty line after the report for an address.
 248
 249   * Does not replace the name of an inlined function with the name of the
 250     topmost caller when inlined frames are not shown.
 251
 252   * Prints an address's debug-data discriminator when it is non-zero. One way to
 253     produce discriminators is to compile with clang's -fdebug-info-for-profiling.
 254
 255   ``JSON`` style provides a machine readable output in JSON. If addresses are
 256     supplied via stdin, the output JSON will be a series of individual objects.
 257     Otherwise, all results will be contained in a single array.
 258
 259   .. code-block:: console
 260
 261     $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
 262     baz() at /tmp/test.cpp:11:18
 263      (inlined by) main at /tmp/test.cpp:15:0
 264
 265     foo() at /tmp/test.cpp:6:3
 266
 267     $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
 268     main at /tmp/test.cpp:11:18
 269
 270     foo() at /tmp/test.cpp:6:3
 271
 272     $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
 273     baz() at /tmp/test.cpp:11
 274     foo() at /tmp/test.cpp:6
 275
 276     $ clang -g -fdebug-info-for-profiling test.cpp -o profiling.elf
 277     $ llvm-symbolizer --output-style=GNU --obj=profiling.elf 0x401167 -p --no-inlines
 278     main at /tmp/test.cpp:15 (discriminator 2)
 279
 280     $ llvm-symbolizer --output-style=JSON --obj=inlined.elf 0x4004be 0x400486 -p
 281     [
 282       {
 283         "Address": "0x4004be",
 284         "ModuleName": "inlined.elf",
 285         "Symbol": [
 286           {
 287             "Column": 18,
 288             "Discriminator": 0,
 289             "FileName": "/tmp/test.cpp",
 290             "FunctionName": "baz()",
 291             "Line": 11,
 292             "Source": "",
 293             "StartFileName": "/tmp/test.cpp",
 294             "StartLine": 9
 295           },
 296           {
 297             "Column": 0,
 298             "Discriminator": 0,
 299             "FileName": "/tmp/test.cpp",
 300             "FunctionName": "main",
 301             "Line": 15,
 302             "Source": "",
 303             "StartFileName": "/tmp/test.cpp",
 304             "StartLine": 14
 305           }
 306         ]
 307       },
 308       {
 309         "Address": "0x400486",
 310         "ModuleName": "inlined.elf",
 311         "Symbol": [
 312           {
 313             "Column": 3,
 314             "Discriminator": 0,
 315             "FileName": "/tmp/test.cpp",
 316             "FunctionName": "foo()",
 317             "Line": 6,
 318             "Source": "",
 319             "StartFileName": "/tmp/test.cpp",
 320             "StartLine": 5
 321           }
 322         ]
 323       }
 324     ]
 325
 326 .. option:: --pretty-print, -p
 327
 328   Print human readable output. If :option:`--inlining` is specified, the
 329   enclosing scope is prefixed by (inlined by).
 330   For JSON output, the option will cause JSON to be indented and split over
 331   new lines. Otherwise, the JSON output will be printed in a compact form.
 332
 333   .. code-block:: console
 334
 335     $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
 336     baz() at /tmp/test.cpp:11:18
 337      (inlined by) main at /tmp/test.cpp:15:0
 338
 339 .. option:: --print-address, --addresses, -a
 340
 341   Print address before the source code location. Defaults to false.
 342
 343   .. code-block:: console
 344
 345     $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
 346     0x4004be
 347     baz()
 348     /tmp/test.cpp:11:18
 349     main
 350     /tmp/test.cpp:15:0
 351
 352     $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
 353     0x4004be: baz() at /tmp/test.cpp:11:18
 354      (inlined by) main at /tmp/test.cpp:15:0
 355
 356 .. option:: --print-source-context-lines <N>
 357
 358   Print ``N`` lines of source context for each symbolized address.
 359
 360   .. code-block:: console
 361
 362     $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=3
 363     baz()
 364     /tmp/test.cpp:11:0
 365     10  :   volatile int k = 42;
 366     11 >:   return foz() + k;
 367     12  : }
 368
 369 .. option:: --relativenames
 370
 371   Print the file's path relative to the compilation directory, instead
 372   of the absolute path. If the command-line to the compiler included
 373   the full path, this will be the same as the default.
 374
 375 .. option:: --verbose
 376
 377   Print verbose address, line and column information.
 378
 379   .. code-block:: console
 380
 381     $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
 382     baz()
 383       Filename: /tmp/test.cpp
 384       Function start filename: /tmp/test.cpp
 385       Function start line: 9
 386       Function start address: 0x4004b6
 387       Line: 11
 388       Column: 18
 389     main
 390       Filename: /tmp/test.cpp
 391       Function start filename: /tmp/test.cpp
 392       Function start line: 14
 393       Function start address: 0x4004b0
 394       Line: 15
 395       Column: 18
 396
 397 .. option:: --version, -v
 398
 399   Print version information for the tool.
 400
 401 .. option:: @<FILE>
 402
 403   Read command-line options from response file `<FILE>`.
 404
 405 WINDOWS/PDB SPECIFIC OPTIONS
 406 -----------------------------
 407
 408 .. option:: --dia
 409
 410   Use the Windows DIA SDK for symbolization. If the DIA SDK is not found,
 411   llvm-symbolizer will fall back to the native implementation.
 412
 413 MACH-O SPECIFIC OPTIONS
 414 -----------------------
 415
 416 .. option:: --default-arch <arch>
 417
 418   If a binary contains object files for multiple architectures (e.g. it is a
 419   Mach-O universal binary), symbolize the object file for a given architecture.
 420   You can also specify the architecture by writing ``binary_name:arch_name`` in
 421   the input (see example below). If the architecture is not specified in either
 422   way, the address will not be symbolized. Defaults to empty string.
 423
 424   .. code-block:: console
 425
 426     $ cat addr.txt
 427     /tmp/mach_universal_binary:i386 0x1f84
 428     /tmp/mach_universal_binary:x86_64 0x100000f24
 429
 430     $ llvm-symbolizer < addr.txt
 431     _main
 432     /tmp/source_i386.cc:8
 433
 434     _main
 435     /tmp/source_x86_64.cc:8
 436
 437 .. option:: --dsym-hint <path/to/file.dSYM>
 438
 439   If the debug info for a binary isn't present in the default location, look for
 440   the debug info at the .dSYM path provided via this option. This flag can be
 441   used multiple times.
 442
 443 EXIT STATUS
 444 -----------
 445
 446 :program:`llvm-symbolizer` returns 0. Other exit codes imply an internal program
 447 error.
 448
 449 SEE ALSO
 450 --------
 451
 452 :manpage:`llvm-addr2line(1)`