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|JSON>
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.
211
212              • Prints  an  address's  debug-data  discriminator  when  it  is
213                non-zero. One way to produce discriminators is to compile with
214                clang's -fdebug-info-for-profiling.
215
216              JSON style provides a machine readable output in  JSON.  If  ad‐
217              dresses are
218                     supplied  via  stdin, the output JSON will be a series of
219                     individual objects.  Otherwise, all results will be  con‐
220                     tained in a single array.
221
222                 $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
223                 baz() at /tmp/test.cpp:11:18
224                  (inlined by) main at /tmp/test.cpp:15:0
225
226                 foo() at /tmp/test.cpp:6:3
227
228                 $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
229                 main at /tmp/test.cpp:11:18
230
231                 foo() at /tmp/test.cpp:6:3
232
233                 $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
234                 baz() at /tmp/test.cpp:11
235                 foo() at /tmp/test.cpp:6
236
237                 $ clang -g -fdebug-info-for-profiling test.cpp -o profiling.elf
238                 $ llvm-symbolizer --output-style=GNU --obj=profiling.elf 0x401167 -p --no-inlines
239                 main at /tmp/test.cpp:15 (discriminator 2)
240
241                 $ llvm-symbolizer --output-style=JSON --obj=inlined.elf 0x4004be 0x400486 -p
242                 [
243                   {
244                     "Address": "0x4004be",
245                     "ModuleName": "inlined.elf",
246                     "Symbol": [
247                       {
248                         "Column": 18,
249                         "Discriminator": 0,
250                         "FileName": "/tmp/test.cpp",
251                         "FunctionName": "baz()",
252                         "Line": 11,
253                         "Source": "",
254                         "StartFileName": "/tmp/test.cpp",
255                         "StartLine": 9
256                       },
257                       {
258                         "Column": 0,
259                         "Discriminator": 0,
260                         "FileName": "/tmp/test.cpp",
261                         "FunctionName": "main",
262                         "Line": 15,
263                         "Source": "",
264                         "StartFileName": "/tmp/test.cpp",
265                         "StartLine": 14
266                       }
267                     ]
268                   },
269                   {
270                     "Address": "0x400486",
271                     "ModuleName": "inlined.elf",
272                     "Symbol": [
273                       {
274                         "Column": 3,
275                         "Discriminator": 0,
276                         "FileName": "/tmp/test.cpp",
277                         "FunctionName": "foo()",
278                         "Line": 6,
279                         "Source": "",
280                         "StartFileName": "/tmp/test.cpp",
281                         "StartLine": 5
282                       }
283                     ]
284                   }
285                 ]
286
287       --pretty-print, -p
288              Print human readable output. If --inlining is specified, the en‐
289              closing scope is prefixed by (inlined by).  For JSON output, the
290              option  will cause JSON to be indented and split over new lines.
291              Otherwise, the JSON output will be printed in a compact form.
292
293                 $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
294                 baz() at /tmp/test.cpp:11:18
295                  (inlined by) main at /tmp/test.cpp:15:0
296
297       --print-address, --addresses, -a
298              Print address before  the  source  code  location.  Defaults  to
299              false.
300
301                 $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
302                 0x4004be
303                 baz()
304                 /tmp/test.cpp:11:18
305                 main
306                 /tmp/test.cpp:15:0
307
308                 $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
309                 0x4004be: baz() at /tmp/test.cpp:11:18
310                  (inlined by) main at /tmp/test.cpp:15:0
311
312       --print-source-context-lines <N>
313              Print N lines of source context for each symbolized address.
314
315                 $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=3
316                 baz()
317                 /tmp/test.cpp:11:0
318                 10  :   volatile int k = 42;
319                 11 >:   return foz() + k;
320                 12  : }
321
322       --relativenames
323              Print the file's path relative to the compilation directory, in‐
324              stead of the absolute path. If the command-line to the  compiler
325              included the full path, this will be the same as the default.
326
327       --verbose
328              Print verbose address, line and column information.
329
330                 $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
331                 baz()
332                   Filename: /tmp/test.cpp
333                   Function start filename: /tmp/test.cpp
334                   Function start line: 9
335                   Function start address: 0x4004b6
336                   Line: 11
337                   Column: 18
338                 main
339                   Filename: /tmp/test.cpp
340                   Function start filename: /tmp/test.cpp
341                   Function start line: 14
342                   Function start address: 0x4004b0
343                   Line: 15
344                   Column: 18
345
346       --version, -v
347              Print version information for the tool.
348
349       @<FILE>
350              Read command-line options from response file <FILE>.
351

WINDOWS/PDB SPECIFIC OPTIONS

353       --dia  Use the Windows DIA SDK for symbolization. If the DIA SDK is not
354              found, llvm-symbolizer will fall back to the native  implementa‐
355              tion.
356

MACH-O SPECIFIC OPTIONS

358       --default-arch <arch>
359              If  a  binary  contains  object files for multiple architectures
360              (e.g. it is a Mach-O universal  binary),  symbolize  the  object
361              file  for a given architecture.  You can also specify the archi‐
362              tecture by writing binary_name:arch_name in the input (see exam‐
363              ple  below). If the architecture is not specified in either way,
364              the address will not be symbolized. Defaults to empty string.
365
366                 $ cat addr.txt
367                 /tmp/mach_universal_binary:i386 0x1f84
368                 /tmp/mach_universal_binary:x86_64 0x100000f24
369
370                 $ llvm-symbolizer < addr.txt
371                 _main
372                 /tmp/source_i386.cc:8
373
374                 _main
375                 /tmp/source_x86_64.cc:8
376
377       --dsym-hint <path/to/file.dSYM>
378              If the debug info for a binary isn't present in the default  lo‐
379              cation,  look  for the debug info at the .dSYM path provided via
380              this option. This flag can be used multiple times.
381

EXIT STATUS

383       llvm-symbolizer returns 0. Other exit codes imply an  internal  program
384       error.
385

SEE ALSO

387       llvm-addr2line(1)
388

AUTHOR

390       Maintained by the LLVM Team (https://llvm.org/).
391
393       2003-2023, LLVM Project
394
395
396
397
39813                                2023-07-20                LLVM-SYMBOLIZER(1)
Impressum