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