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 OPTIONS
 151 -------
 152
 153 .. option:: --adjust-vma <offset>
 154
 155   Add the specified offset to object file addresses when performing lookups.
 156   This can be used to perform lookups as if the object were relocated by the
 157   offset.
 158
 159 .. option:: --basenames, -s
 160
 161   Strip directories when printing the file path.
 162
 163 .. _llvm-symbolizer-opt-C:
 164
 165 .. option:: --demangle, -C
 166
 167   Print demangled function names, if the names are mangled (e.g. the mangled
 168   name `_Z3bazv` becomes `baz()`, whilst the non-mangled name `foz` is printed
 169   as is). Defaults to true.
 170
 171 .. option:: --dwp <path>
 172
 173   Use the specified DWP file at ``<path>`` for any CUs that have split DWARF
 174   debug data.
 175
 176 .. option:: --fallback-debug-path <path>
 177
 178   When a separate file contains debug data, and is referenced by a GNU debug
 179   link section, use the specified path as a basis for locating the debug data if
 180   it cannot be found relative to the object.
 181
 182 .. _llvm-symbolizer-opt-f:
 183
 184 .. option:: --functions [<none|short|linkage>], -f
 185
 186   Specify the way function names are printed (omit function name, print short
 187   function name, or print full linkage name, respectively). Defaults to
 188   ``linkage``.
 189
 190 .. option:: --help, -h
 191
 192   Show help and usage for this command.
 193
 194 .. option:: --help-list
 195
 196   Show help and usage for this command without grouping the options into categories.
 197
 198 .. _llvm-symbolizer-opt-i:
 199
 200 .. option:: --inlining, --inlines, -i
 201
 202   If a source code location is in an inlined function, prints all the inlined
 203   frames. Defaults to true.
 204
 205 .. option:: --no-demangle
 206
 207   Don't print demangled function names.
 208
 209 .. option:: --obj <path>, --exe, -e
 210
 211   Path to object file to be symbolized. If ``-`` is specified, read the object
 212   directly from the standard input stream.
 213
 214 .. _llvm-symbolizer-opt-output-style:
 215
 216 .. option:: --output-style <LLVM|GNU>
 217
 218   Specify the preferred output style. Defaults to ``LLVM``. When the output
 219   style is set to ``GNU``, the tool follows the style of GNU's **addr2line**.
 220   The differences from the ``LLVM`` style are:
 221
 222   * Does not print the column of a source code location.
 223
 224   * Does not add an empty line after the report for an address.
 225
 226   * Does not replace the name of an inlined function with the name of the
 227     topmost caller when inlined frames are not shown and :option:`--use-symbol-table`
 228     is on.
 229
 230   .. code-block:: console
 231
 232     $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
 233     baz() at /tmp/test.cpp:11:18
 234      (inlined by) main at /tmp/test.cpp:15:0
 235
 236     foo() at /tmp/test.cpp:6:3
 237
 238     $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p -i=0
 239     main at /tmp/test.cpp:11:18
 240
 241     foo() at /tmp/test.cpp:6:3
 242
 243     $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p -i=0
 244     baz() at /tmp/test.cpp:11
 245     foo() at /tmp/test.cpp:6
 246
 247 .. option:: --pretty-print, -p
 248
 249   Print human readable output. If :option:`--inlining` is specified, the
 250   enclosing scope is prefixed by (inlined by).
 251
 252 .. code-block:: console
 253
 254   $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
 255   baz() at /tmp/test.cpp:11:18
 256    (inlined by) main at /tmp/test.cpp:15:0
 257
 258 .. option:: --print-address, --addresses, -a
 259
 260   Print address before the source code location. Defaults to false.
 261
 262 .. code-block:: console
 263
 264   $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
 265   0x4004be
 266   baz()
 267   /tmp/test.cpp:11:18
 268   main
 269   /tmp/test.cpp:15:0
 270
 271   $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
 272   0x4004be: baz() at /tmp/test.cpp:11:18
 273    (inlined by) main at /tmp/test.cpp:15:0
 274
 275 .. option:: --print-source-context-lines <N>
 276
 277   Print ``N`` lines of source context for each symbolized address.
 278
 279 .. code-block:: console
 280
 281   $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=2
 282   baz()
 283   /tmp/test.cpp:11:0
 284   10  :   volatile int k = 42;
 285   11 >:   return foz() + k;
 286   12  : }
 287
 288 .. _llvm-symbolizer-opt-use-symbol-table:
 289
 290 .. option:: --use-symbol-table
 291
 292   Prefer function names stored in symbol table to function names in debug info
 293   sections. Defaults to true.
 294
 295 .. option:: --verbose
 296
 297   Print verbose line and column information.
 298
 299 .. code-block:: console
 300
 301   $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
 302   baz()
 303     Filename: /tmp/test.cpp
 304   Function start line: 9
 305     Line: 11
 306     Column: 18
 307   main
 308     Filename: /tmp/test.cpp
 309   Function start line: 14
 310     Line: 15
 311     Column: 0
 312
 313 .. option:: --version
 314
 315   Print version information for the tool.
 316
 317 .. option:: @<FILE>
 318
 319   Read command-line options from response file `<FILE>`.
 320
 321 MACH-O SPECIFIC OPTIONS
 322 -----------------------
 323
 324 .. option:: --default-arch <arch>
 325
 326   If a binary contains object files for multiple architectures (e.g. it is a
 327   Mach-O universal binary), symbolize the object file for a given architecture.
 328   You can also specify the architecture by writing ``binary_name:arch_name`` in
 329   the input (see example below). If the architecture is not specified in either
 330   way, the address will not be symbolized. Defaults to empty string.
 331
 332 .. code-block:: console
 333
 334   $ cat addr.txt
 335   /tmp/mach_universal_binary:i386 0x1f84
 336   /tmp/mach_universal_binary:x86_64 0x100000f24
 337
 338   $ llvm-symbolizer < addr.txt
 339   _main
 340   /tmp/source_i386.cc:8
 341
 342   _main
 343   /tmp/source_x86_64.cc:8
 344
 345 .. option:: --dsym-hint <path/to/file.dSYM>
 346
 347   If the debug info for a binary isn't present in the default location, look for
 348   the debug info at the .dSYM path provided via this option. This flag can be
 349   used multiple times.
 350
 351 EXIT STATUS
 352 -----------
 353
 354 :program:`llvm-symbolizer` returns 0. Other exit codes imply an internal program
 355 error.
 356
 357 SEE ALSO
 358 --------
 359
 360 :manpage:`llvm-addr2line(1)`