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