1LLVM-SYMBOLIZER(1) LLVM LLVM-SYMBOLIZER(1)
2
6 llvm-symbolizer - convert addresses into source code locations
7
9 llvm-symbolizer [options] [addresses...]
10
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 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 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 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 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
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 // test.h
47 extern "C" inline int foz() {
48 return 1234;
49 }
50 // test.cpp
52 #include "test.h"
53 int bar=42;
54 int foo() {
56 return bar;
57 }
58 int baz() {
60 volatile int k = 42;
61 return foz() + k;
62 }
63 int main() {
65 return foo() + baz();
66 }
67 These files are built as follows:
69 $ clang -g test.cpp -o test.elf
71 $ clang -g -O2 test.cpp -o inlined.elf
72 Example 1 - addresses and object on command-line:
74 $ llvm-symbolizer --obj=test.elf 0x4004d0 0x400490
76 foz
77 /tmp/test.h:1:0
78 baz()
80 /tmp/test.cpp:11:0
81 Example 2 - addresses on standard input:
83 $ 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 baz()
93 /tmp/test.cpp:11:0
94 foz
96 /tmp/./test.h:1:0
97 Example 3 - object specified with address:
99 $ llvm-symbolizer "test.elf 0x400490" "FILE:inlined.elf 0x400480"
101 baz()
102 /tmp/test.cpp:11:0
103 foo()
105 /tmp/test.cpp:8:10
106 $ cat addr2.txt
108 FILE:test.elf 0x4004a0
109 inlined.elf 0x400480
110 $ llvm-symbolizer < addr2.txt
112 main
113 /tmp/test.cpp:15:0
114 foo()
116 /tmp/test.cpp:8:10
117 Example 4 - BUILDID and FILE prefixes:
119 $ llvm-symbolizer "FILE:test.elf 0x400490" "DATA BUILDID:123456789abcdef 0x601028"
121 baz()
122 /tmp/test.cpp:11:0
123 bar
125 6295592 4
126 $ cat addr3.txt
128 FILE:test.elf 0x400490
129 DATA BUILDID:123456789abcdef 0x601028
130 $ llvm-symbolizer < addr3.txt
132 baz()
133 /tmp/test.cpp:11:0
134 bar
136 6295592 4
137 Example 5 - CODE and DATA prefixes:
139 $ llvm-symbolizer --obj=test.elf "CODE 0x400490" "DATA 0x601028"
141 baz()
142 /tmp/test.cpp:11:0
143 bar
145 6295592 4
146 $ cat addr4.txt
148 CODE test.elf 0x4004a0
149 DATA inlined.elf 0x601028
150 $ llvm-symbolizer < addr4.txt
152 main
153 /tmp/test.cpp:15:0
154 bar
156 6295592 4
157 Example 6 - path-style options:
159 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 $ 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
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 --basenames, -s
185 Print just the file's name without any directories, instead of
186 the absolute path.
187 --build-id
189 Look up the object using the given build ID, specified as a
190 hexadecimal string. Mutually exclusive with --obj.
191 --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 --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 --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 --dwp <path>
209 Use the specified DWP file at <path> for any CUs that have split
210 DWARF debug data.
211 --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 --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 • {{{hexdict}}}
224 • {{{dumpfile}}}
226 The {{{bt}}} backtrace element reports frames using the follow‐
228 ing syntax:
229 #<number>[.<inline>] <address> <function> <file>:<line>:<col>
231 (<module>+<relative address>)
232 <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 <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 --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 --help, -h
248 Show help and usage for this command.
249 --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 --no-inlines
255 Don't print inlined frames.
256 --no-demangle
258 Don't print demangled function names.
259 --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 --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 • Does not print the column of a source code location.
271 • Does not add an empty line after the report for an address.
273 • Does not replace the name of an inlined function with the name
275 of the topmost caller when inlined frames are not shown.
276 • 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 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 $ 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 foo() at /tmp/test.cpp:6:3
292 $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
294 main at /tmp/test.cpp:11:18
295 foo() at /tmp/test.cpp:6:3
297 $ 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 $ 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 $ 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 --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 $ 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 --print-address, --addresses, -a
363 Print address before the source code location. Defaults to
364 false.
365 $ 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 $ 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 --print-source-context-lines <N>
378 Print N lines of source context for each symbolized address.
379 $ 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 --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 --verbose
393 Print verbose address, line and column information.
394 $ 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 --version, -v
412 Print version information for the tool.
413 @<FILE>
415 Read command-line options from response file <FILE>.
416
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
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 $ cat addr.txt
432 /tmp/mach_universal_binary:i386 0x1f84
433 /tmp/mach_universal_binary:x86_64 0x100000f24
434 $ llvm-symbolizer < addr.txt
436 _main
437 /tmp/source_i386.cc:8
438 _main
440 /tmp/source_x86_64.cc:8
441 --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
448 llvm-symbolizer returns 0. Other exit codes imply an internal program
449 error.
450
452 llvm-addr2line(1)
453
455 Maintained by the LLVM Team (https://llvm.org/).
456
458 2003-2023, LLVM Project
45915 2023-07-20 LLVM-SYMBOLIZER(1)