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  input names and addresses from the command-line
13       and prints corresponding source code locations to standard  output.  It
14       can    also   symbolize   logs   containing   Symbolizer   Markup   via
15       --filter-markup.
16
17       If no address is specified on the command-line, it reads the  addresses
18       from standard input. If no input name is specified on the command-line,
19       but addresses are, or if at any time an input value is not  recognized,
20       the input is simply echoed to the output.
21
22       Input  names  can  be  specified  together with the addresses either on
23       standard input or as positional arguments on the command-line.  By  de‐
24       fault,  input names are interpreted as object file paths. However, pre‐
25       fixing a name with BUILDID: states that it is a  hex  build  ID  rather
26       than a path. This will look up the corresponding debug binary. For con‐
27       sistency, prefixing a name with FILE: explicitly states that it  is  an
28       object file path (the default).
29
30       A positional argument or standard input value can be preceded by "DATA"
31       or "CODE" to indicate that the address should be symbolized as data  or
32       executable  code  respectively.  If neither is specified, "CODE" is as‐
33       sumed. DATA is symbolized as address and symbol size rather  than  line
34       number.
35
36       llvm-symbolizer  parses options from the environment variable LLVM_SYM‐
37       BOLIZER_OPTS after parsing options from the command line.  LLVM_SYMBOL‐
38       IZER_OPTS  is  primarily  useful for supplementing the command-line op‐
39       tions when llvm-symbolizer is invoked by another program or runtime.
40

EXAMPLES

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

OPTIONS

179       --adjust-vma <offset>
180              Add  the specified offset to object file addresses when perform‐
181              ing lookups.  This can be used to perform lookups as if the  ob‐
182              ject were relocated by the offset.
183
184       --basenames, -s
185              Print  just  the file's name without any directories, instead of
186              the absolute path.
187
188       --build-id
189              Look up the object using the given  build  ID,  specified  as  a
190              hexadecimal string. Mutually exclusive with --obj.
191
192       --color [=<always|auto|never>]
193              Specify  whether  to use color in --filter-markup mode. Defaults
194              to auto, which detects whether standard output  supports  color.
195              Specifying --color alone is equivalent to --color=always.
196
197       --debuginfod, --no-debuginfod
198              Whether or not to try debuginfod lookups for debug binaries. Un‐
199              less specified, debuginfod is only enabled if libcurl  was  com‐
200              piled in (LLVM_ENABLE_CURL) and at least one server URL was pro‐
201              vided by the environment variable DEBUGINFOD_URLS.
202
203       --demangle, -C
204              Print demangled function names, if the names are  mangled  (e.g.
205              the  mangled  name _Z3bazv becomes baz(), whilst the non-mangled
206              name foz is printed as is). Defaults to true.
207
208       --dwp <path>
209              Use the specified DWP file at <path> for any CUs that have split
210              DWARF debug data.
211
212       --fallback-debug-path <path>
213              When a separate file contains debug data, and is referenced by a
214              GNU debug link section, use the specified path as  a  basis  for
215              locating  the  debug  data if it cannot be found relative to the
216              object.
217
218       --filter-markup
219              Reads from standard input, converts contained Symbolizer  Markup
220              into  human-readable  form,  and  prints the results to standard
221              output. The following markup elements are not yet supported:
222
223{{{hexdict}}}
224
225{{{dumpfile}}}
226
227              The {{{bt}}} backtrace element reports frames using the  follow‐
228              ing syntax:
229
230              #<number>[.<inline>]  <address>  <function>  <file>:<line>:<col>
231              (<module>+<relative address>)
232
233              <inline> provides frame  numbers  for  calls  inlined  into  the
234              caller  coresponding to <number>. The inlined call numbers start
235              at 1 and increase from callee to caller.
236
237              <address> is an address inside the call instruction to the func‐
238              tion.   The  address  may  not  be the start of the instruction.
239              <relative address> is the corresponding virtual  offset  in  the
240              <module> loaded at that address.
241
242       --functions [=<none|short|linkage>], -f
243              Specify  the way function names are printed (omit function name,
244              print short function name, or print full linkage  name,  respec‐
245              tively). Defaults to linkage.
246
247       --help, -h
248              Show help and usage for this command.
249
250       --inlining, --inlines, -i
251              If  a source code location is in an inlined function, prints all
252              the inlined frames. This is the default.
253
254       --no-inlines
255              Don't print inlined frames.
256
257       --no-demangle
258              Don't print demangled function names.
259
260       --obj <path>, --exe, -e
261              Path to object file to be symbolized. If -  is  specified,  read
262              the object directly from the standard input stream. Mutually ex‐
263              clusive with --build-id.
264
265       --output-style <LLVM|GNU|JSON>
266              Specify the preferred output style. Defaults to LLVM.  When  the
267              output  style is set to GNU, the tool follows the style of GNU's
268              addr2line.  The differences from the LLVM style are:
269
270              • Does not print the column of a source code location.
271
272              • Does not add an empty line after the report for an address.
273
274              • Does not replace the name of an inlined function with the name
275                of the topmost caller when inlined frames are not shown.
276
277              • Prints  an  address's  debug-data  discriminator  when  it  is
278                non-zero. One way to produce discriminators is to compile with
279                clang's -fdebug-info-for-profiling.
280
281              JSON  style  provides  a machine readable output in JSON. If ad‐
282              dresses are
283                     supplied via stdin, the output JSON will be a  series  of
284                     individual  objects.  Otherwise, all results will be con‐
285                     tained in a single array.
286
287                 $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
288                 baz() at /tmp/test.cpp:11:18
289                  (inlined by) main at /tmp/test.cpp:15:0
290
291                 foo() at /tmp/test.cpp:6:3
292
293                 $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
294                 main at /tmp/test.cpp:11:18
295
296                 foo() at /tmp/test.cpp:6:3
297
298                 $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
299                 baz() at /tmp/test.cpp:11
300                 foo() at /tmp/test.cpp:6
301
302                 $ clang -g -fdebug-info-for-profiling test.cpp -o profiling.elf
303                 $ llvm-symbolizer --output-style=GNU --obj=profiling.elf 0x401167 -p --no-inlines
304                 main at /tmp/test.cpp:15 (discriminator 2)
305
306                 $ llvm-symbolizer --output-style=JSON --obj=inlined.elf 0x4004be 0x400486 -p
307                 [
308                   {
309                     "Address": "0x4004be",
310                     "ModuleName": "inlined.elf",
311                     "Symbol": [
312                       {
313                         "Column": 18,
314                         "Discriminator": 0,
315                         "FileName": "/tmp/test.cpp",
316                         "FunctionName": "baz()",
317                         "Line": 11,
318                         "StartAddress": "0x4004be",
319                         "StartFileName": "/tmp/test.cpp",
320                         "StartLine": 9
321                       },
322                       {
323                         "Column": 0,
324                         "Discriminator": 0,
325                         "FileName": "/tmp/test.cpp",
326                         "FunctionName": "main",
327                         "Line": 15,
328                         "StartAddress": "0x4004be",
329                         "StartFileName": "/tmp/test.cpp",
330                         "StartLine": 14
331                       }
332                     ]
333                   },
334                   {
335                     "Address": "0x400486",
336                     "ModuleName": "inlined.elf",
337                     "Symbol": [
338                       {
339                         "Column": 3,
340                         "Discriminator": 0,
341                         "FileName": "/tmp/test.cpp",
342                         "FunctionName": "foo()",
343                         "Line": 6,
344                         "StartAddress": "0x400486",
345                         "StartFileName": "/tmp/test.cpp",
346                         "StartLine": 5
347                       }
348                     ]
349                   }
350                 ]
351
352       --pretty-print, -p
353              Print human readable output. If --inlining is specified, the en‐
354              closing scope is prefixed by (inlined by).  For JSON output, the
355              option will cause JSON to be indented and split over new  lines.
356              Otherwise, the JSON output will be printed in a compact form.
357
358                 $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
359                 baz() at /tmp/test.cpp:11:18
360                  (inlined by) main at /tmp/test.cpp:15:0
361
362       --print-address, --addresses, -a
363              Print  address  before  the  source  code  location. Defaults to
364              false.
365
366                 $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
367                 0x4004be
368                 baz()
369                 /tmp/test.cpp:11:18
370                 main
371                 /tmp/test.cpp:15:0
372
373                 $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
374                 0x4004be: baz() at /tmp/test.cpp:11:18
375                  (inlined by) main at /tmp/test.cpp:15:0
376
377       --print-source-context-lines <N>
378              Print N lines of source context for each symbolized address.
379
380                 $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=3
381                 baz()
382                 /tmp/test.cpp:11:0
383                 10  :   volatile int k = 42;
384                 11 >:   return foz() + k;
385                 12  : }
386
387       --relativenames
388              Print the file's path relative to the compilation directory, in‐
389              stead  of the absolute path. If the command-line to the compiler
390              included the full path, this will be the same as the default.
391
392       --verbose
393              Print verbose address, line and column information.
394
395                 $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
396                 baz()
397                   Filename: /tmp/test.cpp
398                   Function start filename: /tmp/test.cpp
399                   Function start line: 9
400                   Function start address: 0x4004b6
401                   Line: 11
402                   Column: 18
403                 main
404                   Filename: /tmp/test.cpp
405                   Function start filename: /tmp/test.cpp
406                   Function start line: 14
407                   Function start address: 0x4004b0
408                   Line: 15
409                   Column: 18
410
411       --version, -v
412              Print version information for the tool.
413
414       @<FILE>
415              Read command-line options from response file <FILE>.
416

WINDOWS/PDB SPECIFIC OPTIONS

418       --dia  Use the Windows DIA SDK for symbolization. If the DIA SDK is not
419              found,  llvm-symbolizer will fall back to the native implementa‐
420              tion.
421

MACH-O SPECIFIC OPTIONS

423       --default-arch <arch>
424              If a binary contains object  files  for  multiple  architectures
425              (e.g.  it  is  a  Mach-O universal binary), symbolize the object
426              file for a given architecture.  You can also specify the  archi‐
427              tecture by writing binary_name:arch_name in the input (see exam‐
428              ple below). If the architecture is not specified in either  way,
429              the address will not be symbolized. Defaults to empty string.
430
431                 $ cat addr.txt
432                 /tmp/mach_universal_binary:i386 0x1f84
433                 /tmp/mach_universal_binary:x86_64 0x100000f24
434
435                 $ llvm-symbolizer < addr.txt
436                 _main
437                 /tmp/source_i386.cc:8
438
439                 _main
440                 /tmp/source_x86_64.cc:8
441
442       --dsym-hint <path/to/file.dSYM>
443              If  the debug info for a binary isn't present in the default lo‐
444              cation, look for the debug info at the .dSYM path  provided  via
445              this option. This flag can be used multiple times.
446

EXIT STATUS

448       llvm-symbolizer  returns  0. Other exit codes imply an internal program
449       error.
450

SEE ALSO

452       llvm-addr2line(1)
453

AUTHOR

455       Maintained by the LLVM Team (https://llvm.org/).
456
458       2003-2023, LLVM Project
459
460
461
462
46315                                2023-07-20                LLVM-SYMBOLIZER(1)
Impressum