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