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