usr.bin/clang/llvm-symbolizer/llvm-symbolizer.1

   1 .\" $FreeBSD$
   2 .\" Man page generated from reStructuredText.
   3 .
   4 .TH "LLVM-SYMBOLIZER" "1" "2020-06-26" "10" "LLVM"
   5 .SH NAME
   6 llvm-symbolizer \- convert addresses into source code locations
   7 .
   8 .nr rst2man-indent-level 0
   9 .
  10 .de1 rstReportMargin
  11 \\$1 \\n[an-margin]
  12 level \\n[rst2man-indent-level]
  13 level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
  14 -
  15 \\n[rst2man-indent0]
  16 \\n[rst2man-indent1]
  17 \\n[rst2man-indent2]
  18 ..
  19 .de1 INDENT
  20 .\" .rstReportMargin pre:
  21 . RS \\$1
  22 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
  23 . nr rst2man-indent-level +1
  24 .\" .rstReportMargin post:
  25 ..
  26 .de UNINDENT
  27 . RE
  28 .\" indent \\n[an-margin]
  29 .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
  30 .nr rst2man-indent-level -1
  31 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
  32 .in \\n[rst2man-indent\\n[rst2man-indent-level]]u
  33 ..
  34 .SH SYNOPSIS
  35 .sp
  36 \fBllvm\-symbolizer\fP [\fIoptions\fP] [\fIaddresses...\fP]
  37 .SH DESCRIPTION
  38 .sp
  39 \fBllvm\-symbolizer\fP reads object file names and addresses from the
  40 command\-line and prints corresponding source code locations to standard output.
  41 .sp
  42 If no address is specified on the command\-line, it reads the addresses from
  43 standard input. If no object file is specified on the command\-line, but
  44 addresses are, or if at any time an input value is not recognized, the input is
  45 simply echoed to the output.
  46 .sp
  47 A positional argument or standard input value can be preceded by "DATA" or
  48 "CODE" to indicate that the address should be symbolized as data or executable
  49 code respectively. If neither is specified, "CODE" is assumed. DATA is
  50 symbolized as address and symbol size rather than line number.
  51 .sp
  52 Object files can be specified together with the addresses either on standard
  53 input or as positional arguments on the command\-line, following any "DATA" or
  54 "CODE" prefix.
  55 .sp
  56 \fBllvm\-symbolizer\fP parses options from the environment variable
  57 \fBLLVM_SYMBOLIZER_OPTS\fP after parsing options from the command line.
  58 \fBLLVM_SYMBOLIZER_OPTS\fP is primarily useful for supplementing the command\-line
  59 options when \fBllvm\-symbolizer\fP is invoked by another program or
  60 runtime.
  61 .SH EXAMPLES
  62 .sp
  63 All of the following examples use the following two source files as input. They
  64 use a mixture of C\-style and C++\-style linkage to illustrate how these names are
  65 printed differently (see \fI\%\-\-demangle\fP).
  66 .INDENT 0.0
  67 .INDENT 3.5
  68 .sp
  69 .nf
  70 .ft C
  71 // test.h
  72 extern "C" inline int foz() {
  73   return 1234;
  74 }
  75 .ft P
  76 .fi
  77 .UNINDENT
  78 .UNINDENT
  79 .INDENT 0.0
  80 .INDENT 3.5
  81 .sp
  82 .nf
  83 .ft C
  84 // test.cpp
  85 #include "test.h"
  86 int bar=42;
  87
  88 int foo() {
  89   return bar;
  90 }
  91
  92 int baz() {
  93   volatile int k = 42;
  94   return foz() + k;
  95 }
  96
  97 int main() {
  98   return foo() + baz();
  99 }
 100 .ft P
 101 .fi
 102 .UNINDENT
 103 .UNINDENT
 104 .sp
 105 These files are built as follows:
 106 .INDENT 0.0
 107 .INDENT 3.5
 108 .sp
 109 .nf
 110 .ft C
 111 $ clang \-g test.cpp \-o test.elf
 112 $ clang \-g \-O2 test.cpp \-o inlined.elf
 113 .ft P
 114 .fi
 115 .UNINDENT
 116 .UNINDENT
 117 .sp
 118 Example 1 \- addresses and object on command\-line:
 119 .INDENT 0.0
 120 .INDENT 3.5
 121 .sp
 122 .nf
 123 .ft C
 124 $ llvm\-symbolizer \-\-obj=test.elf 0x4004d0 0x400490
 125 foz
 126 /tmp/test.h:1:0
 127
 128 baz()
 129 /tmp/test.cpp:11:0
 130 .ft P
 131 .fi
 132 .UNINDENT
 133 .UNINDENT
 134 .sp
 135 Example 2 \- addresses on standard input:
 136 .INDENT 0.0
 137 .INDENT 3.5
 138 .sp
 139 .nf
 140 .ft C
 141 $ cat addr.txt
 142 0x4004a0
 143 0x400490
 144 0x4004d0
 145 $ llvm\-symbolizer \-\-obj=test.elf < addr.txt
 146 main
 147 /tmp/test.cpp:15:0
 148
 149 baz()
 150 /tmp/test.cpp:11:0
 151
 152 foz
 153 /tmp/./test.h:1:0
 154 .ft P
 155 .fi
 156 .UNINDENT
 157 .UNINDENT
 158 .sp
 159 Example 3 \- object specified with address:
 160 .INDENT 0.0
 161 .INDENT 3.5
 162 .sp
 163 .nf
 164 .ft C
 165 $ llvm\-symbolizer "test.elf 0x400490" "inlined.elf 0x400480"
 166 baz()
 167 /tmp/test.cpp:11:0
 168
 169 foo()
 170 /tmp/test.cpp:8:10
 171
 172 $ cat addr2.txt
 173 test.elf 0x4004a0
 174 inlined.elf 0x400480
 175
 176 $ llvm\-symbolizer < addr2.txt
 177 main
 178 /tmp/test.cpp:15:0
 179
 180 foo()
 181 /tmp/test.cpp:8:10
 182 .ft P
 183 .fi
 184 .UNINDENT
 185 .UNINDENT
 186 .sp
 187 Example 4 \- CODE and DATA prefixes:
 188 .INDENT 0.0
 189 .INDENT 3.5
 190 .sp
 191 .nf
 192 .ft C
 193 $ llvm\-symbolizer \-\-obj=test.elf "CODE 0x400490" "DATA 0x601028"
 194 baz()
 195 /tmp/test.cpp:11:0
 196
 197 bar
 198 6295592 4
 199
 200 $ cat addr3.txt
 201 CODE test.elf 0x4004a0
 202 DATA inlined.elf 0x601028
 203
 204 $ llvm\-symbolizer < addr3.txt
 205 main
 206 /tmp/test.cpp:15:0
 207
 208 bar
 209 6295592 4
 210 .ft P
 211 .fi
 212 .UNINDENT
 213 .UNINDENT
 214 .SH OPTIONS
 215 .INDENT 0.0
 216 .TP
 217 .B \-\-adjust\-vma <offset>
 218 Add the specified offset to object file addresses when performing lookups.
 219 This can be used to perform lookups as if the object were relocated by the
 220 offset.
 221 .UNINDENT
 222 .INDENT 0.0
 223 .TP
 224 .B \-\-basenames, \-s
 225 Strip directories when printing the file path.
 226 .UNINDENT
 227 .INDENT 0.0
 228 .TP
 229 .B \-\-demangle, \-C
 230 Print demangled function names, if the names are mangled (e.g. the mangled
 231 name \fI_Z3bazv\fP becomes \fIbaz()\fP, whilst the non\-mangled name \fIfoz\fP is printed
 232 as is). Defaults to true.
 233 .UNINDENT
 234 .INDENT 0.0
 235 .TP
 236 .B \-\-dwp <path>
 237 Use the specified DWP file at \fB<path>\fP for any CUs that have split DWARF
 238 debug data.
 239 .UNINDENT
 240 .INDENT 0.0
 241 .TP
 242 .B \-\-fallback\-debug\-path <path>
 243 When a separate file contains debug data, and is referenced by a GNU debug
 244 link section, use the specified path as a basis for locating the debug data if
 245 it cannot be found relative to the object.
 246 .UNINDENT
 247 .INDENT 0.0
 248 .TP
 249 .B \-\-functions [<none|short|linkage>], \-f
 250 Specify the way function names are printed (omit function name, print short
 251 function name, or print full linkage name, respectively). Defaults to
 252 \fBlinkage\fP\&.
 253 .UNINDENT
 254 .INDENT 0.0
 255 .TP
 256 .B \-\-help, \-h
 257 Show help and usage for this command.
 258 .UNINDENT
 259 .INDENT 0.0
 260 .TP
 261 .B \-\-help\-list
 262 Show help and usage for this command without grouping the options into categories.
 263 .UNINDENT
 264 .INDENT 0.0
 265 .TP
 266 .B \-\-inlining, \-\-inlines, \-i
 267 If a source code location is in an inlined function, prints all the inlined
 268 frames. Defaults to true.
 269 .UNINDENT
 270 .INDENT 0.0
 271 .TP
 272 .B \-\-no\-demangle
 273 Don\(aqt print demangled function names.
 274 .UNINDENT
 275 .INDENT 0.0
 276 .TP
 277 .B \-\-obj <path>, \-\-exe, \-e
 278 Path to object file to be symbolized. If \fB\-\fP is specified, read the object
 279 directly from the standard input stream.
 280 .UNINDENT
 281 .INDENT 0.0
 282 .TP
 283 .B \-\-output\-style <LLVM|GNU>
 284 Specify the preferred output style. Defaults to \fBLLVM\fP\&. When the output
 285 style is set to \fBGNU\fP, the tool follows the style of GNU\(aqs \fBaddr2line\fP\&.
 286 The differences from the \fBLLVM\fP style are:
 287 .INDENT 7.0
 288 .IP \(bu 2
 289 Does not print the column of a source code location.
 290 .IP \(bu 2
 291 Does not add an empty line after the report for an address.
 292 .IP \(bu 2
 293 Does not replace the name of an inlined function with the name of the
 294 topmost caller when inlined frames are not shown and \fI\%\-\-use\-symbol\-table\fP
 295 is on.
 296 .UNINDENT
 297 .INDENT 7.0
 298 .INDENT 3.5
 299 .sp
 300 .nf
 301 .ft C
 302 $ llvm\-symbolizer \-\-obj=inlined.elf 0x4004be 0x400486 \-p
 303 baz() at /tmp/test.cpp:11:18
 304  (inlined by) main at /tmp/test.cpp:15:0
 305
 306 foo() at /tmp/test.cpp:6:3
 307
 308 $ llvm\-symbolizer \-\-output\-style=LLVM \-\-obj=inlined.elf 0x4004be 0x400486 \-p \-i=0
 309 main at /tmp/test.cpp:11:18
 310
 311 foo() at /tmp/test.cpp:6:3
 312
 313 $ llvm\-symbolizer \-\-output\-style=GNU \-\-obj=inlined.elf 0x4004be 0x400486 \-p \-i=0
 314 baz() at /tmp/test.cpp:11
 315 foo() at /tmp/test.cpp:6
 316 .ft P
 317 .fi
 318 .UNINDENT
 319 .UNINDENT
 320 .UNINDENT
 321 .INDENT 0.0
 322 .TP
 323 .B \-\-pretty\-print, \-p
 324 Print human readable output. If \fI\%\-\-inlining\fP is specified, the
 325 enclosing scope is prefixed by (inlined by).
 326 .UNINDENT
 327 .INDENT 0.0
 328 .INDENT 3.5
 329 .sp
 330 .nf
 331 .ft C
 332 $ llvm\-symbolizer \-\-obj=inlined.elf 0x4004be \-\-inlining \-\-pretty\-print
 333 baz() at /tmp/test.cpp:11:18
 334  (inlined by) main at /tmp/test.cpp:15:0
 335 .ft P
 336 .fi
 337 .UNINDENT
 338 .UNINDENT
 339 .INDENT 0.0
 340 .TP
 341 .B \-\-print\-address, \-\-addresses, \-a
 342 Print address before the source code location. Defaults to false.
 343 .UNINDENT
 344 .INDENT 0.0
 345 .INDENT 3.5
 346 .sp
 347 .nf
 348 .ft C
 349 $ llvm\-symbolizer \-\-obj=inlined.elf \-\-print\-address 0x4004be
 350 0x4004be
 351 baz()
 352 /tmp/test.cpp:11:18
 353 main
 354 /tmp/test.cpp:15:0
 355
 356 $ llvm\-symbolizer \-\-obj=inlined.elf 0x4004be \-\-pretty\-print \-\-print\-address
 357 0x4004be: baz() at /tmp/test.cpp:11:18
 358  (inlined by) main at /tmp/test.cpp:15:0
 359 .ft P
 360 .fi
 361 .UNINDENT
 362 .UNINDENT
 363 .INDENT 0.0
 364 .TP
 365 .B \-\-print\-source\-context\-lines <N>
 366 Print \fBN\fP lines of source context for each symbolized address.
 367 .UNINDENT
 368 .INDENT 0.0
 369 .INDENT 3.5
 370 .sp
 371 .nf
 372 .ft C
 373 $ llvm\-symbolizer \-\-obj=test.elf 0x400490 \-\-print\-source\-context\-lines=2
 374 baz()
 375 /tmp/test.cpp:11:0
 376 10  :   volatile int k = 42;
 377 11 >:   return foz() + k;
 378 12  : }
 379 .ft P
 380 .fi
 381 .UNINDENT
 382 .UNINDENT
 383 .INDENT 0.0
 384 .TP
 385 .B \-\-use\-symbol\-table
 386 Prefer function names stored in symbol table to function names in debug info
 387 sections. Defaults to true.
 388 .UNINDENT
 389 .INDENT 0.0
 390 .TP
 391 .B \-\-verbose
 392 Print verbose line and column information.
 393 .UNINDENT
 394 .INDENT 0.0
 395 .INDENT 3.5
 396 .sp
 397 .nf
 398 .ft C
 399 $ llvm\-symbolizer \-\-obj=inlined.elf \-\-verbose 0x4004be
 400 baz()
 401   Filename: /tmp/test.cpp
 402 Function start line: 9
 403   Line: 11
 404   Column: 18
 405 main
 406   Filename: /tmp/test.cpp
 407 Function start line: 14
 408   Line: 15
 409   Column: 0
 410 .ft P
 411 .fi
 412 .UNINDENT
 413 .UNINDENT
 414 .INDENT 0.0
 415 .TP
 416 .B \-\-version
 417 Print version information for the tool.
 418 .UNINDENT
 419 .INDENT 0.0
 420 .TP
 421 .B @<FILE>
 422 Read command\-line options from response file \fI<FILE>\fP\&.
 423 .UNINDENT
 424 .SH MACH-O SPECIFIC OPTIONS
 425 .INDENT 0.0
 426 .TP
 427 .B \-\-default\-arch <arch>
 428 If a binary contains object files for multiple architectures (e.g. it is a
 429 Mach\-O universal binary), symbolize the object file for a given architecture.
 430 You can also specify the architecture by writing \fBbinary_name:arch_name\fP in
 431 the input (see example below). If the architecture is not specified in either
 432 way, the address will not be symbolized. Defaults to empty string.
 433 .UNINDENT
 434 .INDENT 0.0
 435 .INDENT 3.5
 436 .sp
 437 .nf
 438 .ft C
 439 $ cat addr.txt
 440 /tmp/mach_universal_binary:i386 0x1f84
 441 /tmp/mach_universal_binary:x86_64 0x100000f24
 442
 443 $ llvm\-symbolizer < addr.txt
 444 _main
 445 /tmp/source_i386.cc:8
 446
 447 _main
 448 /tmp/source_x86_64.cc:8
 449 .ft P
 450 .fi
 451 .UNINDENT
 452 .UNINDENT
 453 .INDENT 0.0
 454 .TP
 455 .B \-\-dsym\-hint <path/to/file.dSYM>
 456 If the debug info for a binary isn\(aqt present in the default location, look for
 457 the debug info at the .dSYM path provided via this option. This flag can be
 458 used multiple times.
 459 .UNINDENT
 460 .SH EXIT STATUS
 461 .sp
 462 \fBllvm\-symbolizer\fP returns 0. Other exit codes imply an internal program
 463 error.
 464 .SH SEE ALSO
 465 .sp
 466 \fBllvm\-addr2line(1)\fP
 467 .SH AUTHOR
 468 Maintained by the LLVM Team (https://llvm.org/).
 469 .SH COPYRIGHT
 470 2003-2020, LLVM Project
 471 .\" Generated by docutils manpage writer.
 472 .