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