llvm.org GIT mirror llvm / 95a26fa
[docs][llvm-symbolizer] Improve llvm-symbolizer documentation As detailed in https://bugs.llvm.org/show_bug.cgi?id=42253, there were a number of issues in the llvm-symbolizer documentation. This patch fixes them by: 1. Adding [addresses...] to the synopsis, and matching the formatting of other tools. 2. Rewriting the description to fix grammar issues and mention other usage options. 3. Rewriting the examples to be easier to read. 4. Re-ordering the options into alphabetical order. 5. Improving the text of some of the option descriptions, and adding some examples to individual options. 6. Splitting the Mach-O options into a separate section of the document. 7. Standardizing on double dashes for long options throughout the file. 8. Adding a reference to the llvm-addr2line document. Reviewed by: mtrent, ikudrin Differential Revision: https://reviews.llvm.org/D63651 git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@364410 91177308-0d34-0410-b5e6-96231b3b80d8 James Henderson a month ago
1 changed file(s) with 300 addition(s) and 128 deletion(s). Raw diff Collapse all Expand all
33 SYNOPSIS
44 --------
55
6 :program:`llvm-symbolizer` [options]
6 :program:`llvm-symbolizer` [*options*] [*addresses...*]
77
88 DESCRIPTION
99 -----------
1010
11 :program:`llvm-symbolizer` reads object file names and addresses from standard
12 input and prints corresponding source code locations to standard output.
13 If object file is specified in command line, :program:`llvm-symbolizer`
14 processes only addresses from standard input, the rest is output verbatim.
15 This program uses debug info sections and symbol table in the object files.
16
17 EXAMPLE
11 :program:`llvm-symbolizer` reads object file names and addresses from the
12 command-line and prints corresponding source code locations to standard output.
13
14 If no address is specified on the command-line, it reads the addresses from
15 standard input. If no object file is specified on the command-line, but
16 addresses are, or if at any time an input value is not recognized, the input is
17 simply echoed to the output.
18
19 A positional argument or standard input value can be preceded by "DATA" or
20 "CODE" to indicate that the address should be symbolized as data or executable
21 code respectively. If neither is specified, "CODE" is assumed. DATA is
22 symbolized as address and symbol size rather than line number.
23
24 Object files can be specified together with the addresses either on standard
25 input or as positional arguments on the command-line, following any "DATA" or
26 "CODE" prefix.
27
28 EXAMPLES
1829 --------
1930
31 All of the following examples use the following two source files as input. They
32 use a mixture of C-style and C++-style linkage to illustrate how these names are
33 printed differently (see :option:`--demangle`).
34
35 .. code-block:: c
36
37 // test.h
38 extern "C" inline int foz() {
39 return 1234;
40 }
41
42 .. code-block:: c
43
44 // test.cpp
45 #include "test.h"
46 int bar=42;
47
48 int foo() {
49 return bar;
50 }
51
52 int baz() {
53 volatile int k = 42;
54 return foz() + k;
55 }
56
57 int main() {
58 return foo() + baz();
59 }
60
61 These files are built as follows:
62
63 .. code-block:: console
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 .. code-block:: console
71
72 $ llvm-symbolizer --obj=test.elf 0x4004d0 0x400490
73 foz
74 /tmp/test.h:1:0
75
76 baz()
77 /tmp/test.cpp:11:0
78
79 Example 2 - addresses on standard input:
80
2081 .. code-block:: console
2182
2283 $ cat addr.txt
23 a.out 0x4004f4
24 /tmp/b.out 0x400528
25 /tmp/c.so 0x710
26 /tmp/mach_universal_binary:i386 0x1f84
27 /tmp/mach_universal_binary:x86_64 0x100000f24
28 $ llvm-symbolizer < addr.txt
29 main
30 /tmp/a.cc:4
31
32 f(int, int)
33 /tmp/b.cc:11
34
35 h_inlined_into_g
36 /tmp/header.h:2
37 g_inlined_into_f
38 /tmp/header.h:7
39 f_inlined_into_main
40 /tmp/source.cc:3
41 main
42 /tmp/source.cc:8
43
44 _main
45 /tmp/source_i386.cc:8
46
47 _main
48 /tmp/source_x86_64.cc:8
84 0x4004a0
85 0x400490
86 0x4004d0
87 $ llvm-symbolizer --obj=test.elf < addr.txt
88 main
89 /tmp/test.cpp:15:0
90
91 baz()
92 /tmp/test.cpp:11:0
93
94 foz
95 /tmp/./test.h:1:0
96
97 Example 3 - object specified with address:
98
99 .. code-block:: console
100
101 $ llvm-symbolizer "test.elf 0x400490" "inlined.elf 0x400480"
102 baz()
103 /tmp/test.cpp:11:0
104
105 foo()
106 /tmp/test.cpp:8:10
107
49108 $ cat addr2.txt
50 0x4004f4
51 0x401000
52 $ llvm-symbolizer -obj=a.out < addr2.txt
53 main
54 /tmp/a.cc:4
55
56 foo(int)
57 /tmp/a.cc:12
58 $cat addr.txt
59 0x40054d
60 $llvm-symbolizer -inlining -print-address -pretty-print -obj=addr.exe < addr.txt
61 0x40054d: inc at /tmp/x.c:3:3
62 (inlined by) main at /tmp/x.c:9:0
63 $llvm-symbolizer -inlining -pretty-print -obj=addr.exe < addr.txt
64 inc at /tmp/x.c:3:3
65 (inlined by) main at /tmp/x.c:9:0
109 test.elf 0x4004a0
110 inlined.elf 0x400480
111
112 $ llvm-symbolizer < addr2.txt
113 main
114 /tmp/test.cpp:15:0
115
116 foo()
117 /tmp/test.cpp:8:10
118
119 Example 4 - CODE and DATA prefixes:
120
121 .. code-block:: console
122
123 $ llvm-symbolizer --obj=test.elf "CODE 0x400490" "DATA 0x601028"
124 baz()
125 /tmp/test.cpp:11:0
126
127 bar
128 6295592 4
129
130 $ cat addr3.txt
131 CODE test.elf 0x4004a0
132 DATA inlined.elf 0x601028
133
134 $ llvm-symbolizer < addr3.txt
135 main
136 /tmp/test.cpp:15:0
137
138 bar
139 6295592 4
66140
67141 OPTIONS
68142 -------
69143
70 .. option:: -obj, -exe, -e
71
72 Path to object file to be symbolized.
144 .. option:: --adjust-vma
145
146 Add the specified offset to object file addresses when performing lookups.
147 This can be used to perform lookups as if the object were relocated by the
148 offset.
149
150 .. option:: --basenames, -s
151
152 Strip directories when printing the file path.
153
154 .. _llvm-symbolizer-opt-C:
155
156 .. option:: --demangle, -C
157
158 Print demangled function names, if the names are mangled (e.g. the mangled
159 name `_Z3bazv` becomes `baz()`, whilst the non-mangled name `foz` is printed
160 as is). Defaults to true.
161
162 .. option:: --dwp
163
164 Use the specified DWP file at ```` for any CUs that have split DWARF
165 debug data.
166
167 .. option:: --fallback-debug-path
168
169 When a separate file contains debug data, and is referenced by a GNU debug
170 link section, use the specified path as a basis for locating the debug data if
171 it cannot be found relative to the object.
73172
74173 .. _llvm-symbolizer-opt-f:
75174
76 .. option:: -functions [], -f
77
78 Specify the way function names are printed (omit function name,
79 print short function name, or print full linkage name, respectively).
80 Defaults to ``linkage``.
81
82 .. _llvm-symbolizer-opt-use-symbol-table:
83
84 .. option:: -use-symbol-table
85
86 Prefer function names stored in symbol table to function names
87 in debug info sections. Defaults to true.
88
89 .. _llvm-symbolizer-opt-C:
90
91 .. option:: -demangle, -C
92
93 Print demangled function names. Defaults to true.
94
95 .. option:: -no-demangle
96
97 Don't print demangled function names.
175 .. option:: --functions [], -f
176
177 Specify the way function names are printed (omit function name, print short
178 function name, or print full linkage name, respectively). Defaults to
179 ``linkage``.
180
181 .. option:: --help, -h
182
183 Show help and usage for this command.
184
185 .. option:: --help-list
186
187 Show help and usage for this command without grouping the options into categories.
98188
99189 .. _llvm-symbolizer-opt-i:
100190
101 .. option:: -inlining, -inlines, -i
102
103 If a source code location is in an inlined function, prints all the
104 inlined frames. Defaults to true.
105
106 .. option:: -default-arch
107
108 If a binary contains object files for multiple architectures (e.g. it is a
109 Mach-O universal binary), symbolize the object file for a given architecture.
110 You can also specify architecture by writing ``binary_name:arch_name`` in the
111 input (see example above). If architecture is not specified in either way,
112 address will not be symbolized. Defaults to empty string.
113
114 .. option:: -dsym-hint
115
116 (Darwin-only flag). If the debug info for a binary isn't present in the default
117 location, look for the debug info at the .dSYM path provided via the
118 ``-dsym-hint`` flag. This flag can be used multiple times.
119
120 .. option:: -print-address, -addresses, -a
121
122 Print address before the source code location. Defaults to false.
123
124 .. option:: -pretty-print, -p
125
126 Print human readable output. If ``-inlining`` is specified, enclosing scope is
127 prefixed by (inlined by). Refer to listed examples.
128
129 .. option:: -basenames, -s
130
131 Strip directories when printing the file path.
132
133 .. option:: -adjust-vma
134
135 Add the specified offset to object file addresses when performing lookups. This
136 can be used to perform lookups as if the object were relocated by the offset.
191 .. option:: --inlining, --inlines, -i
192
193 If a source code location is in an inlined function, prints all the inlined
194 frames. Defaults to true.
195
196 .. option:: --no-demangle
197
198 Don't print demangled function names.
199
200 .. option:: --obj , --exe, -e
201
202 Path to object file to be symbolized. If ``-`` is specified, read the object
203 directly from the standard input stream.
137204
138205 .. _llvm-symbolizer-opt-output-style:
139206
140 .. option:: -output-style
207 .. option:: --output-style
141208
142209 Specify the preferred output style. Defaults to ``LLVM``. When the output
143210 style is set to ``GNU``, the tool follows the style of GNU's **addr2line**.
148215 * Does not add an empty line after the report for an address.
149216
150217 * Does not replace the name of an inlined function with the name of the
151 topmost caller when inlined frames are not shown and ``-use-symbol-table``
218 topmost caller when inlined frames are not shown and :option:`--use-symbol-table`
152219 is on.
153220
154221 .. code-block:: console
155222
156 $ llvm-symbolizer -p -e=addr.exe 0x40054d 0x400568
157 inc at /tmp/x.c:3:3
158 (inlined by) main at /tmp/x.c:14:0
159
160 main at /tmp/x.c:14:3
161
162 $ llvm-symbolizer --output-style=LLVM -p -i=0 -e=addr.exe 0x40054d 0x400568
163 main at /tmp/x.c:3:3
164
165 main at /tmp/x.c:14:3
166
167 $ llvm-symbolizer --output-style=GNU -p -i=0 -e=addr.exe 0x40054d 0x400568
168 inc at /tmp/x.c:3
169 main at /tmp/x.c:14
223 $ llvm-symbolizer --obj=inlined.elf 0x4004be 0x400486 -p
224 baz() at /tmp/test.cpp:11:18
225 (inlined by) main at /tmp/test.cpp:15:0
226
227 foo() at /tmp/test.cpp:6:3
228
229 $ llvm-symbolizer --output-style=LLVM --obj=inlined.elf 0x4004be 0x400486 -p -i=0
230 main at /tmp/test.cpp:11:18
231
232 foo() at /tmp/test.cpp:6:3
233
234 $ llvm-symbolizer --output-style=GNU --obj=inlined.elf 0x4004be 0x400486 -p -i=0
235 baz() at /tmp/test.cpp:11
236 foo() at /tmp/test.cpp:6
237
238 .. option:: --pretty-print, -p
239
240 Print human readable output. If :option:`--inlining` is specified, the
241 enclosing scope is prefixed by (inlined by).
242
243 .. code-block:: console
244
245 $ llvm-symbolizer --obj=inlined.elf 0x4004be --inlining --pretty-print
246 baz() at /tmp/test.cpp:11:18
247 (inlined by) main at /tmp/test.cpp:15:0
248
249 .. option:: --print-address, --addresses, -a
250
251 Print address before the source code location. Defaults to false.
252
253 .. code-block:: console
254
255 $ llvm-symbolizer --obj=inlined.elf --print-address 0x4004be
256 0x4004be
257 baz()
258 /tmp/test.cpp:11:18
259 main
260 /tmp/test.cpp:15:0
261
262 $ llvm-symbolizer --obj=inlined.elf 0x4004be --pretty-print --print-address
263 0x4004be: baz() at /tmp/test.cpp:11:18
264 (inlined by) main at /tmp/test.cpp:15:0
265
266 .. option:: --print-source-context-lines
267
268 Print ``N`` lines of source context for each symbolized address.
269
270 .. code-block:: console
271
272 $ llvm-symbolizer --obj=test.elf 0x400490 --print-source-context-lines=2
273 baz()
274 /tmp/test.cpp:11:0
275 10 : volatile int k = 42;
276 11 >: return foz() + k;
277 12 : }
278
279 .. _llvm-symbolizer-opt-use-symbol-table:
280
281 .. option:: --use-symbol-table
282
283 Prefer function names stored in symbol table to function names in debug info
284 sections. Defaults to true.
285
286 .. option:: --verbose
287
288 Print verbose line and column information.
289
290 .. code-block:: console
291
292 $ llvm-symbolizer --obj=inlined.elf --verbose 0x4004be
293 baz()
294 Filename: /tmp/test.cpp
295 Function start line: 9
296 Line: 11
297 Column: 18
298 main
299 Filename: /tmp/test.cpp
300 Function start line: 14
301 Line: 15
302 Column: 0
303
304 .. option:: --version
305
306 Print version information for the tool.
170307
171308 .. option:: @
172309
173 Read command-line options from response file ``.
310 Read command-line options from response file ``.
311
312 MACH-O SPECIFIC OPTIONS
313 -----------------------
314
315 .. option:: --default-arch
316
317 If a binary contains object files for multiple architectures (e.g. it is a
318 Mach-O universal binary), symbolize the object file for a given architecture.
319 You can also specify the architecture by writing ``binary_name:arch_name`` in
320 the input (see example below). If the architecture is not specified in either
321 way, the address will not be symbolized. Defaults to empty string.
322
323 .. code-block:: console
324
325 $ cat addr.txt
326 /tmp/mach_universal_binary:i386 0x1f84
327 /tmp/mach_universal_binary:x86_64 0x100000f24
328
329 $ llvm-symbolizer < addr.txt
330 _main
331 /tmp/source_i386.cc:8
332
333 _main
334 /tmp/source_x86_64.cc:8
335
336 .. option:: --dsym-hint
337
338 If the debug info for a binary isn't present in the default location, look for
339 the debug info at the .dSYM path provided via this option. This flag can be
340 used multiple times.
174341
175342 EXIT STATUS
176343 -----------
177344
178345 :program:`llvm-symbolizer` returns 0. Other exit codes imply an internal program
179346 error.
347
348 SEE ALSO
349 --------
350
351 :manpage:`llvm-addr2line(1)`