1LLVM-SYMBOLIZER(1)                   LLVM                   LLVM-SYMBOLIZER(1)
2
3
4

NAME

6       llvm-symbolizer - convert addresses into source code locations
7

SYNOPSIS

9       llvm-symbolizer [options] [addresses...]
10

DESCRIPTION

12       llvm-symbolizer  reads  object  file  names and addresses from the com‐
13       mand-line and prints corresponding source code  locations  to  standard
14       output.
15
16       If  no address is specified on the command-line, it reads the addresses
17       from standard input. If  no  object  file  is  specified  on  the  com‐
18       mand-line,  but  addresses are, or if at any time an input value is not
19       recognized, the input is simply echoed to the output.
20
21       A positional argument or standard input value can be preceded by "DATA"
22       or  "CODE" to indicate that the address should be symbolized as data or
23       executable code respectively. If neither is specified,  "CODE"  is  as‐
24       sumed.  DATA  is symbolized as address and symbol size rather than line
25       number.
26
27       Object files can be specified together with  the  addresses  either  on
28       standard  input or as positional arguments on the command-line, follow‐
29       ing any "DATA" or "CODE" prefix.
30
31       llvm-symbolizer parses options from the environment variable  LLVM_SYM‐
32       BOLIZER_OPTS after parsing options from the command line.  LLVM_SYMBOL‐
33       IZER_OPTS is primarily useful for supplementing  the  command-line  op‐
34       tions when llvm-symbolizer is invoked by another program or runtime.
35

EXAMPLES

37       All of the following examples use the following two source files as in‐
38       put. They use a mixture of C-style and C++-style linkage to  illustrate
39       how these names are printed differently (see --demangle).
40
41          // test.h
42          extern "C" inline int foz() {
43            return 1234;
44          }
45
46          // test.cpp
47          #include "test.h"
48          int bar=42;
49
50          int foo() {
51            return bar;
52          }
53
54          int baz() {
55            volatile int k = 42;
56            return foz() + k;
57          }
58
59          int main() {
60            return foo() + baz();
61          }
62
63       These files are built as follows:
64
65          $ clang -g test.cpp -o test.elf
66          $ clang -g -O2 test.cpp -o inlined.elf
67
68       Example 1 - addresses and object on command-line:
69
70          $ llvm-symbolizer --obj=test.elf 0x4004d0 0x400490
71          foz
72          /tmp/test.h:1:0
73
74          baz()
75          /tmp/test.cpp:11:0
76
77       Example 2 - addresses on standard input:
78
79          $ cat addr.txt
80          0x4004a0
81          0x400490
82          0x4004d0
83          $ llvm-symbolizer --obj=test.elf < addr.txt
84          main
85          /tmp/test.cpp:15:0
86
87          baz()
88          /tmp/test.cpp:11:0
89
90          foz
91          /tmp/./test.h:1:0
92
93       Example 3 - object specified with address:
94
95          $ llvm-symbolizer "test.elf 0x400490" "inlined.elf 0x400480"
96          baz()
97          /tmp/test.cpp:11:0
98
99          foo()
100          /tmp/test.cpp:8:10
101
102          $ cat addr2.txt
103          test.elf 0x4004a0
104          inlined.elf 0x400480
105
106          $ llvm-symbolizer < addr2.txt
107          main
108          /tmp/test.cpp:15:0
109
110          foo()
111          /tmp/test.cpp:8:10
112
113       Example 4 - CODE and DATA prefixes:
114
115          $ llvm-symbolizer --obj=test.elf "CODE 0x400490" "DATA 0x601028"
116          baz()
117          /tmp/test.cpp:11:0
118
119          bar
120          6295592 4
121
122          $ cat addr3.txt
123          CODE test.elf 0x4004a0
124          DATA inlined.elf 0x601028
125
126          $ llvm-symbolizer < addr3.txt
127          main
128          /tmp/test.cpp:15:0
129
130          bar
131          6295592 4
132
133       Example 5 - path-style options:
134
135       This  example uses the same source file as above, but the source file's
136       full path is /tmp/foo/test.cpp and is compiled as  follows.  The  first
137       case  shows  the default absolute path, the second --basenames, and the
138       third shows --relativenames.
139
140          $ pwd
141          /tmp
142          $ clang -g foo/test.cpp -o test.elf
143          $ llvm-symbolizer --obj=test.elf 0x4004a0
144          main
145          /tmp/foo/test.cpp:15:0
146          $ llvm-symbolizer --obj=test.elf 0x4004a0 --basenames
147          main
148          test.cpp:15:0
149          $ llvm-symbolizer --obj=test.elf 0x4004a0 --relativenames
150          main
151          foo/test.cpp:15:0
152

OPTIONS

154       --adjust-vma <offset>
155              Add the specified offset to object file addresses when  perform‐
156              ing  lookups.  This can be used to perform lookups as if the ob‐
157              ject were relocated by the offset.
158
159       --basenames, -s
160              Print just the file's name without any directories,  instead  of
161              the absolute path.
162
163       --relativenames
164              Print the file's path relative to the compilation directory, in‐
165              stead of the absolute path. If the command-line to the  compiler
166              included the full path, this will be the same as the default.
167
168       --demangle, -C
169              Print  demangled  function names, if the names are mangled (e.g.
170              the mangled name _Z3bazv becomes baz(), whilst  the  non-mangled
171              name foz is printed as is). Defaults to true.
172
173       --dwp <path>
174              Use the specified DWP file at <path> for any CUs that have split
175              DWARF debug data.
176
177       --fallback-debug-path <path>
178              When a separate file contains debug data, and is referenced by a
179              GNU  debug  link  section, use the specified path as a basis for
180              locating the debug data if it cannot be found  relative  to  the
181              object.
182
183       --functions [=<none|short|linkage>], -f
184              Specify  the way function names are printed (omit function name,
185              print short function name, or print full linkage  name,  respec‐
186              tively). Defaults to linkage.
187
188       --help, -h
189              Show help and usage for this command.
190
191       --help-list
192              Show  help  and  usage for this command without grouping the op‐
193              tions into categories.
194
195       --inlining, --inlines, -i
196              If a source code location is in an inlined function, prints  all
197              the inlined frames. Defaults to true.
198
199       --no-demangle
200              Don't print demangled function names.
201
202       --obj <path>, --exe, -e
203              Path  to  object  file to be symbolized. If - is specified, read
204              the object directly from the standard input stream.
205
206       --output-style <LLVM|GNU>
207              Specify the preferred output style. Defaults to LLVM.  When  the
208              output  style is set to GNU, the tool follows the style of GNU's
209              addr2line.  The differences from the LLVM style are:
210
211              • Does not print the column of a source code location.
212
213              • Does not add an empty line after the report for an address.
214
215              • Does not replace the name of an inlined function with the name
216                of  the  topmost  caller when inlined frames are not shown and
217                --use-symbol-table is on.
218
219              • Prints  an  address's  debug-data  discriminator  when  it  is
220                non-zero. One way to produce discriminators is to compile with
221                clang's -fdebug-info-for-profiling.
222
223                 $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
224                 baz() at /tmp/test.cpp:11:18
225                  (inlined by) main at /tmp/test.cpp:15:0
226
227                 foo() at /tmp/test.cpp:6:3
228
229                 $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p -i=0
230                 main at /tmp/test.cpp:11:18
231
232                 foo() at /tmp/test.cpp:6:3
233
234                 $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p -i=0
235                 baz() at /tmp/test.cpp:11
236                 foo() at /tmp/test.cpp:6
237
238                 $ clang -g -fdebug-info-for-profiling test.cpp -o profiling.elf
239                 $ llvm-symbolizer --output-style=GNU --obj=profiling.elf 0x401167 -p -i=0
240                 main at /tmp/test.cpp:15 (discriminator 2)
241
242       --pretty-print, -p
243              Print human readable output. If --inlining is specified, the en‐
244              closing scope is prefixed by (inlined by).
245
246                 $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
247                 baz() at /tmp/test.cpp:11:18
248                  (inlined by) main at /tmp/test.cpp:15:0
249
250       --print-address, --addresses, -a
251              Print  address  before  the  source  code  location. Defaults to
252              false.
253
254                 $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
255                 0x4004be
256                 baz()
257                 /tmp/test.cpp:11:18
258                 main
259                 /tmp/test.cpp:15:0
260
261                 $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
262                 0x4004be: baz() at /tmp/test.cpp:11:18
263                  (inlined by) main at /tmp/test.cpp:15:0
264
265       --print-source-context-lines <N>
266              Print N lines of source context for each symbolized address.
267
268                 $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=2
269                 baz()
270                 /tmp/test.cpp:11:0
271                 10  :   volatile int k = 42;
272                 11 >:   return foz() + k;
273                 12  : }
274
275       --use-symbol-table
276              Prefer function names stored in symbol table to  function  names
277              in debug info sections. Defaults to true.
278
279       --verbose
280              Print verbose line and column information.
281
282                 $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
283                 baz()
284                   Filename: /tmp/test.cpp
285                 Function start line: 9
286                   Line: 11
287                   Column: 18
288                 main
289                   Filename: /tmp/test.cpp
290                 Function start line: 14
291                   Line: 15
292                   Column: 0
293
294       --version
295              Print version information for the tool.
296
297       @<FILE>
298              Read command-line options from response file <FILE>.
299

MACH-O SPECIFIC OPTIONS

301       --default-arch <arch>
302              If  a  binary  contains  object files for multiple architectures
303              (e.g. it is a Mach-O universal  binary),  symbolize  the  object
304              file  for a given architecture.  You can also specify the archi‐
305              tecture by writing binary_name:arch_name in the input (see exam‐
306              ple  below). If the architecture is not specified in either way,
307              the address will not be symbolized. Defaults to empty string.
308
309                 $ cat addr.txt
310                 /tmp/mach_universal_binary:i386 0x1f84
311                 /tmp/mach_universal_binary:x86_64 0x100000f24
312
313                 $ llvm-symbolizer < addr.txt
314                 _main
315                 /tmp/source_i386.cc:8
316
317                 _main
318                 /tmp/source_x86_64.cc:8
319
320       --dsym-hint <path/to/file.dSYM>
321              If the debug info for a binary isn't present in the default  lo‐
322              cation,  look  for the debug info at the .dSYM path provided via
323              this option. This flag can be used multiple times.
324

EXIT STATUS

326       llvm-symbolizer returns 0. Other exit codes imply an  internal  program
327       error.
328

SEE ALSO

330       llvm-addr2line(1)
331

AUTHOR

333       Maintained by the LLVM Team (https://llvm.org/).
334
336       2003-2021, LLVM Project
337
338
339
340
34111                                2021-07-22                LLVM-SYMBOLIZER(1)
Impressum