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