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  $ pwd
159  /tmp
160  $ clang -g foo/test.cpp -o test.elf
161  $ llvm-symbolizer --obj=test.elf 0x4004a0
162  main
163  /tmp/foo/test.cpp:15:0
164  $ llvm-symbolizer --obj=test.elf 0x4004a0 --basenames
165  main
166  test.cpp:15:0
167  $ llvm-symbolizer --obj=test.elf 0x4004a0 --relativenames
168  main
169  foo/test.cpp:15:0
170
171OPTIONS
172-------
173
174.. option:: --adjust-vma <offset>
175
176  Add the specified offset to object file addresses when performing lookups.
177  This can be used to perform lookups as if the object were relocated by the
178  offset.
179
180.. option:: --basenames, -s
181
182  Print just the file's name without any directories, instead of the
183  absolute path.
184
185.. option:: --relativenames
186
187  Print the file's path relative to the compilation directory, instead
188  of the absolute path. If the command-line to the compiler included
189  the full path, this will be the same as the default.
190
191.. _llvm-symbolizer-opt-C:
192
193.. option:: --demangle, -C
194
195  Print demangled function names, if the names are mangled (e.g. the mangled
196  name `_Z3bazv` becomes `baz()`, whilst the non-mangled name `foz` is printed
197  as is). Defaults to true.
198
199.. option:: --dwp <path>
200
201  Use the specified DWP file at ``<path>`` for any CUs that have split DWARF
202  debug data.
203
204.. option:: --fallback-debug-path <path>
205
206  When a separate file contains debug data, and is referenced by a GNU debug
207  link section, use the specified path as a basis for locating the debug data if
208  it cannot be found relative to the object.
209
210.. _llvm-symbolizer-opt-f:
211
212.. option:: --functions [=<none|short|linkage>], -f
213
214  Specify the way function names are printed (omit function name, print short
215  function name, or print full linkage name, respectively). Defaults to
216  ``linkage``.
217
218.. option:: --help, -h
219
220  Show help and usage for this command.
221
222.. option:: --help-list
223
224  Show help and usage for this command without grouping the options into categories.
225
226.. _llvm-symbolizer-opt-i:
227
228.. option:: --inlining, --inlines, -i
229
230  If a source code location is in an inlined function, prints all the inlined
231  frames. Defaults to true.
232
233.. option:: --no-demangle
234
235  Don't print demangled function names.
236
237.. option:: --obj <path>, --exe, -e
238
239  Path to object file to be symbolized. If ``-`` is specified, read the object
240  directly from the standard input stream.
241
242.. _llvm-symbolizer-opt-output-style:
243
244.. option:: --output-style <LLVM|GNU>
245
246  Specify the preferred output style. Defaults to ``LLVM``. When the output
247  style is set to ``GNU``, the tool follows the style of GNU's **addr2line**.
248  The differences from the ``LLVM`` style are:
249
250  * Does not print the column of a source code location.
251
252  * Does not add an empty line after the report for an address.
253
254  * Does not replace the name of an inlined function with the name of the
255    topmost caller when inlined frames are not shown and :option:`--use-symbol-table`
256    is on.
257
258  * Prints an address's debug-data discriminator when it is non-zero. One way to
259    produce discriminators is to compile with clang's -fdebug-info-for-profiling.
260
261  .. code-block:: console
262
263    $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
264    baz() at /tmp/test.cpp:11:18
265     (inlined by) main at /tmp/test.cpp:15:0
266
267    foo() at /tmp/test.cpp:6:3
268
269    $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p -i=0
270    main at /tmp/test.cpp:11:18
271
272    foo() at /tmp/test.cpp:6:3
273
274    $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p -i=0
275    baz() at /tmp/test.cpp:11
276    foo() at /tmp/test.cpp:6
277
278    $ clang -g -fdebug-info-for-profiling test.cpp -o profiling.elf
279    $ llvm-symbolizer --output-style=GNU --obj=profiling.elf 0x401167 -p -i=0
280    main at /tmp/test.cpp:15 (discriminator 2)
281
282.. option:: --pretty-print, -p
283
284  Print human readable output. If :option:`--inlining` is specified, the
285  enclosing scope is prefixed by (inlined by).
286
287  .. code-block:: console
288
289    $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
290    baz() at /tmp/test.cpp:11:18
291     (inlined by) main at /tmp/test.cpp:15:0
292
293.. option:: --print-address, --addresses, -a
294
295  Print address before the source code location. Defaults to false.
296
297  .. code-block:: console
298
299    $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
300    0x4004be
301    baz()
302    /tmp/test.cpp:11:18
303    main
304    /tmp/test.cpp:15:0
305
306    $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
307    0x4004be: baz() at /tmp/test.cpp:11:18
308     (inlined by) main at /tmp/test.cpp:15:0
309
310.. option:: --print-source-context-lines <N>
311
312  Print ``N`` lines of source context for each symbolized address.
313
314  .. code-block:: console
315
316    $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=2
317    baz()
318    /tmp/test.cpp:11:0
319    10  :   volatile int k = 42;
320    11 >:   return foz() + k;
321    12  : }
322
323.. _llvm-symbolizer-opt-use-symbol-table:
324
325.. option:: --use-symbol-table
326
327  Prefer function names stored in symbol table to function names in debug info
328  sections. Defaults to true.
329
330.. option:: --verbose
331
332  Print verbose line and column information.
333
334  .. code-block:: console
335
336    $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
337    baz()
338      Filename: /tmp/test.cpp
339    Function start line: 9
340      Line: 11
341      Column: 18
342    main
343      Filename: /tmp/test.cpp
344    Function start line: 14
345      Line: 15
346      Column: 0
347
348.. option:: --version
349
350  Print version information for the tool.
351
352.. option:: @<FILE>
353
354  Read command-line options from response file `<FILE>`.
355
356MACH-O SPECIFIC OPTIONS
357-----------------------
358
359.. option:: --default-arch <arch>
360
361  If a binary contains object files for multiple architectures (e.g. it is a
362  Mach-O universal binary), symbolize the object file for a given architecture.
363  You can also specify the architecture by writing ``binary_name:arch_name`` in
364  the input (see example below). If the architecture is not specified in either
365  way, the address will not be symbolized. Defaults to empty string.
366
367  .. code-block:: console
368
369    $ cat addr.txt
370    /tmp/mach_universal_binary:i386 0x1f84
371    /tmp/mach_universal_binary:x86_64 0x100000f24
372
373    $ llvm-symbolizer < addr.txt
374    _main
375    /tmp/source_i386.cc:8
376
377    _main
378    /tmp/source_x86_64.cc:8
379
380.. option:: --dsym-hint <path/to/file.dSYM>
381
382  If the debug info for a binary isn't present in the default location, look for
383  the debug info at the .dSYM path provided via this option. This flag can be
384  used multiple times.
385
386EXIT STATUS
387-----------
388
389:program:`llvm-symbolizer` returns 0. Other exit codes imply an internal program
390error.
391
392SEE ALSO
393--------
394
395:manpage:`llvm-addr2line(1)`
396