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 EXAMPLES
  32 --------
  33
  34 All of the following examples use the following two source files as input. They
  35 use a mixture of C-style and C++-style linkage to illustrate how these names are
  36 printed differently (see :option:`--demangle`).
  37
  38 .. code-block:: c
  39
  40   // test.h
  41   extern "C" inline int foz() {
  42     return 1234;
  43   }
  44
  45 .. code-block:: c
  46
  47   // test.cpp
  48   #include "test.h"
  49   int bar=42;
  50
  51   int foo() {
  52     return bar;
  53   }
  54
  55   int baz() {
  56     volatile int k = 42;
  57     return foz() + k;
  58   }
  59
  60   int main() {
  61     return foo() + baz();
  62   }
  63
  64 These files are built as follows:
  65
  66 .. code-block:: console
  67
  68   $ clang -g test.cpp -o test.elf
  69   $ clang -g -O2 test.cpp -o inlined.elf
  70
  71 Example 1 - addresses and object on command-line:
  72
  73 .. code-block:: console
  74
  75   $ llvm-symbolizer --obj=test.elf 0x4004d0 0x400490
  76   foz
  77   /tmp/test.h:1:0
  78
  79   baz()
  80   /tmp/test.cpp:11:0
  81
  82 Example 2 - addresses on standard input:
  83
  84 .. code-block:: console
  85
  86   $ cat addr.txt
  87   0x4004a0
  88   0x400490
  89   0x4004d0
  90   $ llvm-symbolizer --obj=test.elf < addr.txt
  91   main
  92   /tmp/test.cpp:15:0
  93
  94   baz()
  95   /tmp/test.cpp:11:0
  96
  97   foz
  98   /tmp/./test.h:1:0
  99
 100 Example 3 - object specified with address:
 101
 102 .. code-block:: console
 103
 104   $ llvm-symbolizer "test.elf 0x400490" "inlined.elf 0x400480"
 105   baz()
 106   /tmp/test.cpp:11:0
 107
 108   foo()
 109   /tmp/test.cpp:8:10
 110
 111   $ cat addr2.txt
 112   test.elf 0x4004a0
 113   inlined.elf 0x400480
 114
 115   $ llvm-symbolizer < addr2.txt
 116   main
 117   /tmp/test.cpp:15:0
 118
 119   foo()
 120   /tmp/test.cpp:8:10
 121
 122 Example 4 - CODE and DATA prefixes:
 123
 124 .. code-block:: console
 125
 126   $ llvm-symbolizer --obj=test.elf "CODE 0x400490" "DATA 0x601028"
 127   baz()
 128   /tmp/test.cpp:11:0
 129
 130   bar
 131   6295592 4
 132
 133   $ cat addr3.txt
 134   CODE test.elf 0x4004a0
 135   DATA inlined.elf 0x601028
 136
 137   $ llvm-symbolizer < addr3.txt
 138   main
 139   /tmp/test.cpp:15:0
 140
 141   bar
 142   6295592 4
 143
 144 OPTIONS
 145 -------
 146
 147 .. option:: --adjust-vma <offset>
 148
 149   Add the specified offset to object file addresses when performing lookups.
 150   This can be used to perform lookups as if the object were relocated by the
 151   offset.
 152
 153 .. option:: --basenames, -s
 154
 155   Strip directories when printing the file path.
 156
 157 .. _llvm-symbolizer-opt-C:
 158
 159 .. option:: --demangle, -C
 160
 161   Print demangled function names, if the names are mangled (e.g. the mangled
 162   name `_Z3bazv` becomes `baz()`, whilst the non-mangled name `foz` is printed
 163   as is). Defaults to true.
 164
 165 .. option:: --dwp <path>
 166
 167   Use the specified DWP file at ``<path>`` for any CUs that have split DWARF
 168   debug data.
 169
 170 .. option:: --fallback-debug-path <path>
 171
 172   When a separate file contains debug data, and is referenced by a GNU debug
 173   link section, use the specified path as a basis for locating the debug data if
 174   it cannot be found relative to the object.
 175
 176 .. _llvm-symbolizer-opt-f:
 177
 178 .. option:: --functions [<none|short|linkage>], -f
 179
 180   Specify the way function names are printed (omit function name, print short
 181   function name, or print full linkage name, respectively). Defaults to
 182   ``linkage``.
 183
 184 .. option:: --help, -h
 185
 186   Show help and usage for this command.
 187
 188 .. option:: --help-list
 189
 190   Show help and usage for this command without grouping the options into categories.
 191
 192 .. _llvm-symbolizer-opt-i:
 193
 194 .. option:: --inlining, --inlines, -i
 195
 196   If a source code location is in an inlined function, prints all the inlined
 197   frames. Defaults to true.
 198
 199 .. option:: --no-demangle
 200
 201   Don't print demangled function names.
 202
 203 .. option:: --obj <path>, --exe, -e
 204
 205   Path to object file to be symbolized. If ``-`` is specified, read the object
 206   directly from the standard input stream.
 207
 208 .. _llvm-symbolizer-opt-output-style:
 209
 210 .. option:: --output-style <LLVM|GNU>
 211
 212   Specify the preferred output style. Defaults to ``LLVM``. When the output
 213   style is set to ``GNU``, the tool follows the style of GNU's **addr2line**.
 214   The differences from the ``LLVM`` style are:
 215
 216   * Does not print the column of a source code location.
 217
 218   * Does not add an empty line after the report for an address.
 219
 220   * Does not replace the name of an inlined function with the name of the
 221     topmost caller when inlined frames are not shown and :option:`--use-symbol-table`
 222     is on.
 223
 224   .. code-block:: console
 225
 226     $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
 227     baz() at /tmp/test.cpp:11:18
 228      (inlined by) main at /tmp/test.cpp:15:0
 229
 230     foo() at /tmp/test.cpp:6:3
 231
 232     $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p -i=0
 233     main at /tmp/test.cpp:11:18
 234
 235     foo() at /tmp/test.cpp:6:3
 236
 237     $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p -i=0
 238     baz() at /tmp/test.cpp:11
 239     foo() at /tmp/test.cpp:6
 240
 241 .. option:: --pretty-print, -p
 242
 243   Print human readable output. If :option:`--inlining` is specified, the
 244   enclosing scope is prefixed by (inlined by).
 245
 246 .. code-block:: console
 247
 248   $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
 249   baz() at /tmp/test.cpp:11:18
 250    (inlined by) main at /tmp/test.cpp:15:0
 251
 252 .. option:: --print-address, --addresses, -a
 253
 254   Print address before the source code location. Defaults to false.
 255
 256 .. code-block:: console
 257
 258   $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
 259   0x4004be
 260   baz()
 261   /tmp/test.cpp:11:18
 262   main
 263   /tmp/test.cpp:15:0
 264
 265   $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
 266   0x4004be: baz() at /tmp/test.cpp:11:18
 267    (inlined by) main at /tmp/test.cpp:15:0
 268
 269 .. option:: --print-source-context-lines <N>
 270
 271   Print ``N`` lines of source context for each symbolized address.
 272
 273 .. code-block:: console
 274
 275   $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=2
 276   baz()
 277   /tmp/test.cpp:11:0
 278   10  :   volatile int k = 42;
 279   11 >:   return foz() + k;
 280   12  : }
 281
 282 .. _llvm-symbolizer-opt-use-symbol-table:
 283
 284 .. option:: --use-symbol-table
 285
 286   Prefer function names stored in symbol table to function names in debug info
 287   sections. Defaults to true.
 288
 289 .. option:: --verbose
 290
 291   Print verbose line and column information.
 292
 293 .. code-block:: console
 294
 295   $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
 296   baz()
 297     Filename: /tmp/test.cpp
 298   Function start line: 9
 299     Line: 11
 300     Column: 18
 301   main
 302     Filename: /tmp/test.cpp
 303   Function start line: 14
 304     Line: 15
 305     Column: 0
 306
 307 .. option:: --version
 308
 309   Print version information for the tool.
 310
 311 .. option:: @<FILE>
 312
 313   Read command-line options from response file `<FILE>`.
 314
 315 MACH-O SPECIFIC OPTIONS
 316 -----------------------
 317
 318 .. option:: --default-arch <arch>
 319
 320   If a binary contains object files for multiple architectures (e.g. it is a
 321   Mach-O universal binary), symbolize the object file for a given architecture.
 322   You can also specify the architecture by writing ``binary_name:arch_name`` in
 323   the input (see example below). If the architecture is not specified in either
 324   way, the address will not be symbolized. Defaults to empty string.
 325
 326 .. code-block:: console
 327
 328   $ cat addr.txt
 329   /tmp/mach_universal_binary:i386 0x1f84
 330   /tmp/mach_universal_binary:x86_64 0x100000f24
 331
 332   $ llvm-symbolizer < addr.txt
 333   _main
 334   /tmp/source_i386.cc:8
 335
 336   _main
 337   /tmp/source_x86_64.cc:8
 338
 339 .. option:: --dsym-hint <path/to/file.dSYM>
 340
 341   If the debug info for a binary isn't present in the default location, look for
 342   the debug info at the .dSYM path provided via this option. This flag can be
 343   used multiple times.
 344
 345 EXIT STATUS
 346 -----------
 347
 348 :program:`llvm-symbolizer` returns 0. Other exit codes imply an internal program
 349 error.
 350
 351 SEE ALSO
 352 --------
 353
 354 :manpage:`llvm-addr2line(1)`