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