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.. _llvm-symbolizer-opt-C:
187
188.. option:: --demangle, -C
189
190  Print demangled function names, if the names are mangled (e.g. the mangled
191  name `_Z3bazv` becomes `baz()`, whilst the non-mangled name `foz` is printed
192  as is). Defaults to true.
193
194.. option:: --dwp <path>
195
196  Use the specified DWP file at ``<path>`` for any CUs that have split DWARF
197  debug data.
198
199.. option:: --fallback-debug-path <path>
200
201  When a separate file contains debug data, and is referenced by a GNU debug
202  link section, use the specified path as a basis for locating the debug data if
203  it cannot be found relative to the object.
204
205.. _llvm-symbolizer-opt-f:
206
207.. option:: --functions [=<none|short|linkage>], -f
208
209  Specify the way function names are printed (omit function name, print short
210  function name, or print full linkage name, respectively). Defaults to
211  ``linkage``.
212
213.. option:: --help, -h
214
215  Show help and usage for this command.
216
217.. _llvm-symbolizer-opt-i:
218
219.. option:: --inlining, --inlines, -i
220
221  If a source code location is in an inlined function, prints all the inlined
222  frames. This is the default.
223
224.. option:: --no-inlines
225
226  Don't print inlined frames.
227
228.. option:: --no-demangle
229
230  Don't print demangled function names.
231
232.. option:: --obj <path>, --exe, -e
233
234  Path to object file to be symbolized. If ``-`` is specified, read the object
235  directly from the standard input stream.
236
237.. _llvm-symbolizer-opt-output-style:
238
239.. option:: --output-style <LLVM|GNU|JSON>
240
241  Specify the preferred output style. Defaults to ``LLVM``. When the output
242  style is set to ``GNU``, the tool follows the style of GNU's **addr2line**.
243  The differences from the ``LLVM`` style are:
244
245  * Does not print the column of a source code location.
246
247  * Does not add an empty line after the report for an address.
248
249  * Does not replace the name of an inlined function with the name of the
250    topmost caller when inlined frames are not shown.
251
252  * Prints an address's debug-data discriminator when it is non-zero. One way to
253    produce discriminators is to compile with clang's -fdebug-info-for-profiling.
254
255  ``JSON`` style provides a machine readable output in JSON. If addresses are
256    supplied via stdin, the output JSON will be a series of individual objects.
257    Otherwise, all results will be contained in a single array.
258
259  .. code-block:: console
260
261    $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
262    baz() at /tmp/test.cpp:11:18
263     (inlined by) main at /tmp/test.cpp:15:0
264
265    foo() at /tmp/test.cpp:6:3
266
267    $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
268    main at /tmp/test.cpp:11:18
269
270    foo() at /tmp/test.cpp:6:3
271
272    $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
273    baz() at /tmp/test.cpp:11
274    foo() at /tmp/test.cpp:6
275
276    $ clang -g -fdebug-info-for-profiling test.cpp -o profiling.elf
277    $ llvm-symbolizer --output-style=GNU --obj=profiling.elf 0x401167 -p --no-inlines
278    main at /tmp/test.cpp:15 (discriminator 2)
279
280    $ llvm-symbolizer --output-style=JSON --obj=inlined.elf 0x4004be 0x400486 -p
281    [
282      {
283        "Address": "0x4004be",
284        "ModuleName": "inlined.elf",
285        "Symbol": [
286          {
287            "Column": 18,
288            "Discriminator": 0,
289            "FileName": "/tmp/test.cpp",
290            "FunctionName": "baz()",
291            "Line": 11,
292            "StartAddress": "0x4004be",
293            "StartFileName": "/tmp/test.cpp",
294            "StartLine": 9
295          },
296          {
297            "Column": 0,
298            "Discriminator": 0,
299            "FileName": "/tmp/test.cpp",
300            "FunctionName": "main",
301            "Line": 15,
302            "StartAddress": "0x4004be",
303            "StartFileName": "/tmp/test.cpp",
304            "StartLine": 14
305          }
306        ]
307      },
308      {
309        "Address": "0x400486",
310        "ModuleName": "inlined.elf",
311        "Symbol": [
312          {
313            "Column": 3,
314            "Discriminator": 0,
315            "FileName": "/tmp/test.cpp",
316            "FunctionName": "foo()",
317            "Line": 6,
318            "StartAddress": "0x400486",
319            "StartFileName": "/tmp/test.cpp",
320            "StartLine": 5
321          }
322        ]
323      }
324    ]
325
326.. option:: --pretty-print, -p
327
328  Print human readable output. If :option:`--inlining` is specified, the
329  enclosing scope is prefixed by (inlined by).
330  For JSON output, the option will cause JSON to be indented and split over
331  new lines. Otherwise, the JSON output will be printed in a compact form.
332
333  .. code-block:: console
334
335    $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
336    baz() at /tmp/test.cpp:11:18
337     (inlined by) main at /tmp/test.cpp:15:0
338
339.. option:: --print-address, --addresses, -a
340
341  Print address before the source code location. Defaults to false.
342
343  .. code-block:: console
344
345    $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
346    0x4004be
347    baz()
348    /tmp/test.cpp:11:18
349    main
350    /tmp/test.cpp:15:0
351
352    $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
353    0x4004be: baz() at /tmp/test.cpp:11:18
354     (inlined by) main at /tmp/test.cpp:15:0
355
356.. option:: --print-source-context-lines <N>
357
358  Print ``N`` lines of source context for each symbolized address.
359
360  .. code-block:: console
361
362    $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=3
363    baz()
364    /tmp/test.cpp:11:0
365    10  :   volatile int k = 42;
366    11 >:   return foz() + k;
367    12  : }
368
369.. option:: --relativenames
370
371  Print the file's path relative to the compilation directory, instead
372  of the absolute path. If the command-line to the compiler included
373  the full path, this will be the same as the default.
374
375.. option:: --verbose
376
377  Print verbose address, line and column information.
378
379  .. code-block:: console
380
381    $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
382    baz()
383      Filename: /tmp/test.cpp
384      Function start filename: /tmp/test.cpp
385      Function start line: 9
386      Function start address: 0x4004b6
387      Line: 11
388      Column: 18
389    main
390      Filename: /tmp/test.cpp
391      Function start filename: /tmp/test.cpp
392      Function start line: 14
393      Function start address: 0x4004b0
394      Line: 15
395      Column: 18
396
397.. option:: --version, -v
398
399  Print version information for the tool.
400
401.. option:: @<FILE>
402
403  Read command-line options from response file `<FILE>`.
404
405WINDOWS/PDB SPECIFIC OPTIONS
406-----------------------------
407
408.. option:: --dia
409
410  Use the Windows DIA SDK for symbolization. If the DIA SDK is not found,
411  llvm-symbolizer will fall back to the native implementation.
412
413MACH-O SPECIFIC OPTIONS
414-----------------------
415
416.. option:: --default-arch <arch>
417
418  If a binary contains object files for multiple architectures (e.g. it is a
419  Mach-O universal binary), symbolize the object file for a given architecture.
420  You can also specify the architecture by writing ``binary_name:arch_name`` in
421  the input (see example below). If the architecture is not specified in either
422  way, the address will not be symbolized. Defaults to empty string.
423
424  .. code-block:: console
425
426    $ cat addr.txt
427    /tmp/mach_universal_binary:i386 0x1f84
428    /tmp/mach_universal_binary:x86_64 0x100000f24
429
430    $ llvm-symbolizer < addr.txt
431    _main
432    /tmp/source_i386.cc:8
433
434    _main
435    /tmp/source_x86_64.cc:8
436
437.. option:: --dsym-hint <path/to/file.dSYM>
438
439  If the debug info for a binary isn't present in the default location, look for
440  the debug info at the .dSYM path provided via this option. This flag can be
441  used multiple times.
442
443EXIT STATUS
444-----------
445
446:program:`llvm-symbolizer` returns 0. Other exit codes imply an internal program
447error.
448
449SEE ALSO
450--------
451
452:manpage:`llvm-addr2line(1)`
453