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

WINDOWS/PDB SPECIFIC OPTIONS

300       --dia  Use the Windows DIA SDK for symbolization. If the DIA SDK is not
301              found,  llvm-symbolizer will fall back to the native implementa‐
302              tion.
303

MACH-O SPECIFIC OPTIONS

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

EXIT STATUS

330       llvm-symbolizer  returns  0. Other exit codes imply an internal program
331       error.
332

SEE ALSO

334       llvm-addr2line(1)
335

AUTHOR

337       Maintained by the LLVM Team (https://llvm.org/).
338
340       2003-2023, LLVM Project
341
342
343
344
34512                                2023-07-20                LLVM-SYMBOLIZER(1)
Impressum