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 --debug-file-directory <path>
198 Provide a path to a directory with a .build-id subdirectory to
199 search for debug information for stripped binaries. Multiple in‐
200 stances of this argument are searched in the order given.
201 --debuginfod, --no-debuginfod
203 Whether or not to try debuginfod lookups for debug binaries. Un‐
204 less specified, debuginfod is only enabled if libcurl was com‐
205 piled in (LLVM_ENABLE_CURL) and at least one server URL was pro‐
206 vided by the environment variable DEBUGINFOD_URLS.
207 --demangle, -C
209 Print demangled function names, if the names are mangled (e.g.
210 the mangled name _Z3bazv becomes baz(), whilst the non-mangled
211 name foz is printed as is). Defaults to true.
212 --dwp <path>
214 Use the specified DWP file at <path> for any CUs that have split
215 DWARF debug data.
216 --fallback-debug-path <path>
218 When a separate file contains debug data, and is referenced by a
219 GNU debug link section, use the specified path as a basis for
220 locating the debug data if it cannot be found relative to the
221 object.
222 --filter-markup
224 Reads from standard input, converts contained Symbolizer Markup
225 into human-readable form, and prints the results to standard
226 output. The following markup elements are not yet supported:
227 • {{{hexdict}}}
229 • {{{dumpfile}}}
231 The {{{bt}}} backtrace element reports frames using the follow‐
233 ing syntax:
234 #<number>[.<inline>] <address> <function> <file>:<line>:<col>
236 (<module>+<relative address>)
237 <inline> provides frame numbers for calls inlined into the
239 caller coresponding to <number>. The inlined call numbers start
240 at 1 and increase from callee to caller.
241 <address> is an address inside the call instruction to the func‐
243 tion. The address may not be the start of the instruction.
244 <relative address> is the corresponding virtual offset in the
245 <module> loaded at that address.
246 --functions [=<none|short|linkage>], -f
248 Specify the way function names are printed (omit function name,
249 print short function name, or print full linkage name, respec‐
250 tively). Defaults to linkage.
251 --help, -h
253 Show help and usage for this command.
254 --inlining, --inlines, -i
256 If a source code location is in an inlined function, prints all
257 the inlined frames. This is the default.
258 --no-inlines
260 Don't print inlined frames.
261 --no-demangle
263 Don't print demangled function names.
264 --obj <path>, --exe, -e
266 Path to object file to be symbolized. If - is specified, read
267 the object directly from the standard input stream. Mutually ex‐
268 clusive with --build-id.
269 --output-style <LLVM|GNU|JSON>
271 Specify the preferred output style. Defaults to LLVM. When the
272 output style is set to GNU, the tool follows the style of GNU's
273 addr2line. The differences from the LLVM style are:
274 • Does not print the column of a source code location.
276 • Does not add an empty line after the report for an address.
278 • Does not replace the name of an inlined function with the name
280 of the topmost caller when inlined frames are not shown.
281 • Prints an address's debug-data discriminator when it is
283 non-zero. One way to produce discriminators is to compile with
284 clang's -fdebug-info-for-profiling.
285 JSON style provides a machine readable output in JSON. If ad‐
287 dresses are
288 supplied via stdin, the output JSON will be a series of
289 individual objects. Otherwise, all results will be con‐
290 tained in a single array.
291 $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
293 baz() at /tmp/test.cpp:11:18
294 (inlined by) main at /tmp/test.cpp:15:0
295 foo() at /tmp/test.cpp:6:3
297 $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
299 main at /tmp/test.cpp:11:18
300 foo() at /tmp/test.cpp:6:3
302 $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p --no-inlines
304 baz() at /tmp/test.cpp:11
305 foo() at /tmp/test.cpp:6
306 $ clang -g -fdebug-info-for-profiling test.cpp -o profiling.elf
308 $ llvm-symbolizer --output-style=GNU --obj=profiling.elf 0x401167 -p --no-inlines
309 main at /tmp/test.cpp:15 (discriminator 2)
310 $ llvm-symbolizer --output-style=JSON --obj=inlined.elf 0x4004be 0x400486 -p
312 [
313 {
314 "Address": "0x4004be",
315 "ModuleName": "inlined.elf",
316 "Symbol": [
317 {
318 "Column": 18,
319 "Discriminator": 0,
320 "FileName": "/tmp/test.cpp",
321 "FunctionName": "baz()",
322 "Line": 11,
323 "StartAddress": "0x4004be",
324 "StartFileName": "/tmp/test.cpp",
325 "StartLine": 9
326 },
327 {
328 "Column": 0,
329 "Discriminator": 0,
330 "FileName": "/tmp/test.cpp",
331 "FunctionName": "main",
332 "Line": 15,
333 "StartAddress": "0x4004be",
334 "StartFileName": "/tmp/test.cpp",
335 "StartLine": 14
336 }
337 ]
338 },
339 {
340 "Address": "0x400486",
341 "ModuleName": "inlined.elf",
342 "Symbol": [
343 {
344 "Column": 3,
345 "Discriminator": 0,
346 "FileName": "/tmp/test.cpp",
347 "FunctionName": "foo()",
348 "Line": 6,
349 "StartAddress": "0x400486",
350 "StartFileName": "/tmp/test.cpp",
351 "StartLine": 5
352 }
353 ]
354 }
355 ]
356 --pretty-print, -p
358 Print human readable output. If --inlining is specified, the en‐
359 closing scope is prefixed by (inlined by). For JSON output, the
360 option will cause JSON to be indented and split over new lines.
361 Otherwise, the JSON output will be printed in a compact form.
362 $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
364 baz() at /tmp/test.cpp:11:18
365 (inlined by) main at /tmp/test.cpp:15:0
366 --print-address, --addresses, -a
368 Print address before the source code location. Defaults to
369 false.
370 $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
372 0x4004be
373 baz()
374 /tmp/test.cpp:11:18
375 main
376 /tmp/test.cpp:15:0
377 $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
379 0x4004be: baz() at /tmp/test.cpp:11:18
380 (inlined by) main at /tmp/test.cpp:15:0
381 --print-source-context-lines <N>
383 Print N lines of source context for each symbolized address.
384 $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=3
386 baz()
387 /tmp/test.cpp:11:0
388 10 : volatile int k = 42;
389 11 >: return foz() + k;
390 12 : }
391 --relativenames
393 Print the file's path relative to the compilation directory, in‐
394 stead of the absolute path. If the command-line to the compiler
395 included the full path, this will be the same as the default.
396 --verbose
398 Print verbose address, line and column information.
399 $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
401 baz()
402 Filename: /tmp/test.cpp
403 Function start filename: /tmp/test.cpp
404 Function start line: 9
405 Function start address: 0x4004b6
406 Line: 11
407 Column: 18
408 main
409 Filename: /tmp/test.cpp
410 Function start filename: /tmp/test.cpp
411 Function start line: 14
412 Function start address: 0x4004b0
413 Line: 15
414 Column: 18
415 --version, -v
417 Print version information for the tool.
418 @<FILE>
420 Read command-line options from response file <FILE>.
421
423 --dia Use the Windows DIA SDK for symbolization. If the DIA SDK is not
424 found, llvm-symbolizer will fall back to the native implementa‐
425 tion.
426
428 --default-arch <arch>
429 If a binary contains object files for multiple architectures
430 (e.g. it is a Mach-O universal binary), symbolize the object
431 file for a given architecture. You can also specify the archi‐
432 tecture by writing binary_name:arch_name in the input (see exam‐
433 ple below). If the architecture is not specified in either way,
434 the address will not be symbolized. Defaults to empty string.
435 $ cat addr.txt
437 /tmp/mach_universal_binary:i386 0x1f84
438 /tmp/mach_universal_binary:x86_64 0x100000f24
439 $ llvm-symbolizer < addr.txt
441 _main
442 /tmp/source_i386.cc:8
443 _main
445 /tmp/source_x86_64.cc:8
446 --dsym-hint <path/to/file.dSYM>
448 If the debug info for a binary isn't present in the default lo‐
449 cation, look for the debug info at the .dSYM path provided via
450 this option. This flag can be used multiple times.
451
453 llvm-symbolizer returns 0. Other exit codes imply an internal program
454 error.
455
457 llvm-addr2line(1)
458
460 Maintained by the LLVM Team (https://llvm.org/).
461
463 2003-2023, LLVM Project
46417 2023-11-28 LLVM-SYMBOLIZER(1)