aboutsummaryrefslogtreecommitdiff
path: root/usr.bin/clang/llvm-symbolizer/llvm-symbolizer.1
diff options
context:
space:
mode:
Diffstat (limited to 'usr.bin/clang/llvm-symbolizer/llvm-symbolizer.1')
-rw-r--r--usr.bin/clang/llvm-symbolizer/llvm-symbolizer.1660
1 files changed, 660 insertions, 0 deletions
diff --git a/usr.bin/clang/llvm-symbolizer/llvm-symbolizer.1 b/usr.bin/clang/llvm-symbolizer/llvm-symbolizer.1
new file mode 100644
index 000000000000..40514158f32e
--- /dev/null
+++ b/usr.bin/clang/llvm-symbolizer/llvm-symbolizer.1
@@ -0,0 +1,660 @@
+.\" Man page generated from reStructuredText.
+.
+.
+.nr rst2man-indent-level 0
+.
+.de1 rstReportMargin
+\\$1 \\n[an-margin]
+level \\n[rst2man-indent-level]
+level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
+-
+\\n[rst2man-indent0]
+\\n[rst2man-indent1]
+\\n[rst2man-indent2]
+..
+.de1 INDENT
+.\" .rstReportMargin pre:
+. RS \\$1
+. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
+. nr rst2man-indent-level +1
+.\" .rstReportMargin post:
+..
+.de UNINDENT
+. RE
+.\" indent \\n[an-margin]
+.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.nr rst2man-indent-level -1
+.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
+.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
+..
+.TH "LLVM-SYMBOLIZER" "1" "2023-05-24" "16" "LLVM"
+.SH NAME
+llvm-symbolizer \- convert addresses into source code locations
+.SH SYNOPSIS
+.sp
+\fBllvm\-symbolizer\fP [\fIoptions\fP] [\fIaddresses...\fP]
+.SH DESCRIPTION
+.sp
+\fBllvm\-symbolizer\fP reads input names and addresses from the command\-line
+and prints corresponding source code locations to standard output. It can also
+symbolize logs containing \fI\%Symbolizer Markup\fP via
+\fI\%\-\-filter\-markup\fP\&.
+.sp
+If no address is specified on the command\-line, it reads the addresses from
+standard input. If no input name is specified on the command\-line, but addresses
+are, or if at any time an input value is not recognized, the input is simply
+echoed to the output.
+.sp
+Input names can be specified together with the addresses either on standard
+input or as positional arguments on the command\-line. By default, input names
+are interpreted as object file paths. However, prefixing a name with
+\fBBUILDID:\fP states that it is a hex build ID rather than a path. This will look
+up the corresponding debug binary. For consistency, prefixing a name with
+\fBFILE:\fP explicitly states that it is an object file path (the default).
+.sp
+A positional argument or standard input value can be preceded by \(dqDATA\(dq or
+\(dqCODE\(dq to indicate that the address should be symbolized as data or executable
+code respectively. If neither is specified, \(dqCODE\(dq is assumed. DATA is
+symbolized as address and symbol size rather than line number.
+.sp
+\fBllvm\-symbolizer\fP parses options from the environment variable
+\fBLLVM_SYMBOLIZER_OPTS\fP after parsing options from the command line.
+\fBLLVM_SYMBOLIZER_OPTS\fP is primarily useful for supplementing the command\-line
+options when \fBllvm\-symbolizer\fP is invoked by another program or
+runtime.
+.SH EXAMPLES
+.sp
+All of the following examples use the following two source files as input. They
+use a mixture of C\-style and C++\-style linkage to illustrate how these names are
+printed differently (see \fI\%\-\-demangle\fP).
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+// test.h
+extern \(dqC\(dq inline int foz() {
+ return 1234;
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+// test.cpp
+#include \(dqtest.h\(dq
+int bar=42;
+
+int foo() {
+ return bar;
+}
+
+int baz() {
+ volatile int k = 42;
+ return foz() + k;
+}
+
+int main() {
+ return foo() + baz();
+}
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+These files are built as follows:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ clang \-g test.cpp \-o test.elf
+$ clang \-g \-O2 test.cpp \-o inlined.elf
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Example 1 \- addresses and object on command\-line:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ llvm\-symbolizer \-\-obj=test.elf 0x4004d0 0x400490
+foz
+/tmp/test.h:1:0
+
+baz()
+/tmp/test.cpp:11:0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Example 2 \- addresses on standard input:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ cat addr.txt
+0x4004a0
+0x400490
+0x4004d0
+$ llvm\-symbolizer \-\-obj=test.elf < addr.txt
+main
+/tmp/test.cpp:15:0
+
+baz()
+/tmp/test.cpp:11:0
+
+foz
+/tmp/./test.h:1:0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Example 3 \- object specified with address:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ llvm\-symbolizer \(dqtest.elf 0x400490\(dq \(dqFILE:inlined.elf 0x400480\(dq
+baz()
+/tmp/test.cpp:11:0
+
+foo()
+/tmp/test.cpp:8:10
+
+$ cat addr2.txt
+FILE:test.elf 0x4004a0
+inlined.elf 0x400480
+
+$ llvm\-symbolizer < addr2.txt
+main
+/tmp/test.cpp:15:0
+
+foo()
+/tmp/test.cpp:8:10
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Example 4 \- BUILDID and FILE prefixes:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ llvm\-symbolizer \(dqFILE:test.elf 0x400490\(dq \(dqDATA BUILDID:123456789abcdef 0x601028\(dq
+baz()
+/tmp/test.cpp:11:0
+
+bar
+6295592 4
+
+$ cat addr3.txt
+FILE:test.elf 0x400490
+DATA BUILDID:123456789abcdef 0x601028
+
+$ llvm\-symbolizer < addr3.txt
+baz()
+/tmp/test.cpp:11:0
+
+bar
+6295592 4
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Example 5 \- CODE and DATA prefixes:
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ llvm\-symbolizer \-\-obj=test.elf \(dqCODE 0x400490\(dq \(dqDATA 0x601028\(dq
+baz()
+/tmp/test.cpp:11:0
+
+bar
+6295592 4
+
+$ cat addr4.txt
+CODE test.elf 0x4004a0
+DATA inlined.elf 0x601028
+
+$ llvm\-symbolizer < addr4.txt
+main
+/tmp/test.cpp:15:0
+
+bar
+6295592 4
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.sp
+Example 6 \- path\-style options:
+.sp
+This example uses the same source file as above, but the source file\(aqs
+full path is /tmp/foo/test.cpp and is compiled as follows. The first case
+shows the default absolute path, the second \-\-basenames, and the third
+shows \-\-relativenames.
+.INDENT 0.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ pwd
+/tmp
+$ clang \-g foo/test.cpp \-o test.elf
+$ llvm\-symbolizer \-\-obj=test.elf 0x4004a0
+main
+/tmp/foo/test.cpp:15:0
+$ llvm\-symbolizer \-\-obj=test.elf 0x4004a0 \-\-basenames
+main
+test.cpp:15:0
+$ llvm\-symbolizer \-\-obj=test.elf 0x4004a0 \-\-relativenames
+main
+foo/test.cpp:15:0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.SH OPTIONS
+.INDENT 0.0
+.TP
+.B \-\-adjust\-vma <offset>
+Add the specified offset to object file addresses when performing lookups.
+This can be used to perform lookups as if the object were relocated by the
+offset.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-basenames, \-s
+Print just the file\(aqs name without any directories, instead of the
+absolute path.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-build\-id
+Look up the object using the given build ID, specified as a hexadecimal
+string. Mutually exclusive with \fI\%\-\-obj\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-color [=<always|auto|never>]
+Specify whether to use color in \fI\%\-\-filter\-markup\fP mode. Defaults to
+\fBauto\fP, which detects whether standard output supports color. Specifying
+\fB\-\-color\fP alone is equivalent to \fB\-\-color=always\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-debug\-file\-directory <path>
+Provide a path to a directory with a \fI\&.build\-id\fP subdirectory to search for
+debug information for stripped binaries. Multiple instances of this argument
+are searched in the order given.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-debuginfod, \-\-no\-debuginfod
+Whether or not to try debuginfod lookups for debug binaries. Unless specified,
+debuginfod is only enabled if libcurl was compiled in (\fBLLVM_ENABLE_CURL\fP)
+and at least one server URL was provided by the environment variable
+\fBDEBUGINFOD_URLS\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-demangle, \-C
+Print demangled function names, if the names are mangled (e.g. the mangled
+name \fI_Z3bazv\fP becomes \fIbaz()\fP, whilst the non\-mangled name \fIfoz\fP is printed
+as is). Defaults to true.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-dwp <path>
+Use the specified DWP file at \fB<path>\fP for any CUs that have split DWARF
+debug data.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-fallback\-debug\-path <path>
+When a separate file contains debug data, and is referenced by a GNU debug
+link section, use the specified path as a basis for locating the debug data if
+it cannot be found relative to the object.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-filter\-markup
+Reads from standard input, converts contained
+\fI\%Symbolizer Markup\fP into human\-readable form,
+and prints the results to standard output. The following markup elements are
+not yet supported:
+.INDENT 7.0
+.IP \(bu 2
+\fB{{{hexdict}}}\fP
+.IP \(bu 2
+\fB{{{dumpfile}}}\fP
+.UNINDENT
+.sp
+The \fB{{{bt}}}\fP backtrace element reports frames using the following syntax:
+.sp
+\fB#<number>[.<inline>] <address> <function> <file>:<line>:<col> (<module>+<relative address>)\fP
+.sp
+\fB<inline>\fP provides frame numbers for calls inlined into the caller
+coresponding to \fB<number>\fP\&. The inlined call numbers start at 1 and increase
+from callee to caller.
+.sp
+\fB<address>\fP is an address inside the call instruction to the function. The
+address may not be the start of the instruction. \fB<relative address>\fP is
+the corresponding virtual offset in the \fB<module>\fP loaded at that address.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-functions [=<none|short|linkage>], \-f
+Specify the way function names are printed (omit function name, print short
+function name, or print full linkage name, respectively). Defaults to
+\fBlinkage\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-help, \-h
+Show help and usage for this command.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-inlining, \-\-inlines, \-i
+If a source code location is in an inlined function, prints all the inlined
+frames. This is the default.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-no\-inlines
+Don\(aqt print inlined frames.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-no\-demangle
+Don\(aqt print demangled function names.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-obj <path>, \-\-exe, \-e
+Path to object file to be symbolized. If \fB\-\fP is specified, read the object
+directly from the standard input stream. Mutually exclusive with
+\fI\%\-\-build\-id\fP\&.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-output\-style <LLVM|GNU|JSON>
+Specify the preferred output style. Defaults to \fBLLVM\fP\&. When the output
+style is set to \fBGNU\fP, the tool follows the style of GNU\(aqs \fBaddr2line\fP\&.
+The differences from the \fBLLVM\fP style are:
+.INDENT 7.0
+.IP \(bu 2
+Does not print the column of a source code location.
+.IP \(bu 2
+Does not add an empty line after the report for an address.
+.IP \(bu 2
+Does not replace the name of an inlined function with the name of the
+topmost caller when inlined frames are not shown.
+.IP \(bu 2
+Prints an address\(aqs debug\-data discriminator when it is non\-zero. One way to
+produce discriminators is to compile with clang\(aqs \-fdebug\-info\-for\-profiling.
+.UNINDENT
+.INDENT 7.0
+.TP
+.B \fBJSON\fP style provides a machine readable output in JSON. If addresses are
+supplied via stdin, the output JSON will be a series of individual objects.
+Otherwise, all results will be contained in a single array.
+.UNINDENT
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ llvm\-symbolizer \-\-obj=inlined.elf 0x4004be 0x400486 \-p
+baz() at /tmp/test.cpp:11:18
+ (inlined by) main at /tmp/test.cpp:15:0
+
+foo() at /tmp/test.cpp:6:3
+
+$ llvm\-symbolizer \-\-output\-style=LLVM \-\-obj=inlined.elf 0x4004be 0x400486 \-p \-\-no\-inlines
+main at /tmp/test.cpp:11:18
+
+foo() at /tmp/test.cpp:6:3
+
+$ llvm\-symbolizer \-\-output\-style=GNU \-\-obj=inlined.elf 0x4004be 0x400486 \-p \-\-no\-inlines
+baz() at /tmp/test.cpp:11
+foo() at /tmp/test.cpp:6
+
+$ clang \-g \-fdebug\-info\-for\-profiling test.cpp \-o profiling.elf
+$ llvm\-symbolizer \-\-output\-style=GNU \-\-obj=profiling.elf 0x401167 \-p \-\-no\-inlines
+main at /tmp/test.cpp:15 (discriminator 2)
+
+$ llvm\-symbolizer \-\-output\-style=JSON \-\-obj=inlined.elf 0x4004be 0x400486 \-p
+[
+ {
+ \(dqAddress\(dq: \(dq0x4004be\(dq,
+ \(dqModuleName\(dq: \(dqinlined.elf\(dq,
+ \(dqSymbol\(dq: [
+ {
+ \(dqColumn\(dq: 18,
+ \(dqDiscriminator\(dq: 0,
+ \(dqFileName\(dq: \(dq/tmp/test.cpp\(dq,
+ \(dqFunctionName\(dq: \(dqbaz()\(dq,
+ \(dqLine\(dq: 11,
+ \(dqStartAddress\(dq: \(dq0x4004be\(dq,
+ \(dqStartFileName\(dq: \(dq/tmp/test.cpp\(dq,
+ \(dqStartLine\(dq: 9
+ },
+ {
+ \(dqColumn\(dq: 0,
+ \(dqDiscriminator\(dq: 0,
+ \(dqFileName\(dq: \(dq/tmp/test.cpp\(dq,
+ \(dqFunctionName\(dq: \(dqmain\(dq,
+ \(dqLine\(dq: 15,
+ \(dqStartAddress\(dq: \(dq0x4004be\(dq,
+ \(dqStartFileName\(dq: \(dq/tmp/test.cpp\(dq,
+ \(dqStartLine\(dq: 14
+ }
+ ]
+ },
+ {
+ \(dqAddress\(dq: \(dq0x400486\(dq,
+ \(dqModuleName\(dq: \(dqinlined.elf\(dq,
+ \(dqSymbol\(dq: [
+ {
+ \(dqColumn\(dq: 3,
+ \(dqDiscriminator\(dq: 0,
+ \(dqFileName\(dq: \(dq/tmp/test.cpp\(dq,
+ \(dqFunctionName\(dq: \(dqfoo()\(dq,
+ \(dqLine\(dq: 6,
+ \(dqStartAddress\(dq: \(dq0x400486\(dq,
+ \(dqStartFileName\(dq: \(dq/tmp/test.cpp\(dq,
+ \(dqStartLine\(dq: 5
+ }
+ ]
+ }
+]
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-pretty\-print, \-p
+Print human readable output. If \fI\%\-\-inlining\fP is specified, the
+enclosing scope is prefixed by (inlined by).
+For JSON output, the option will cause JSON to be indented and split over
+new lines. Otherwise, the JSON output will be printed in a compact form.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ llvm\-symbolizer \-\-obj=inlined.elf 0x4004be \-\-inlining \-\-pretty\-print
+baz() at /tmp/test.cpp:11:18
+ (inlined by) main at /tmp/test.cpp:15:0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-print\-address, \-\-addresses, \-a
+Print address before the source code location. Defaults to false.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ llvm\-symbolizer \-\-obj=inlined.elf \-\-print\-address 0x4004be
+0x4004be
+baz()
+/tmp/test.cpp:11:18
+main
+/tmp/test.cpp:15:0
+
+$ llvm\-symbolizer \-\-obj=inlined.elf 0x4004be \-\-pretty\-print \-\-print\-address
+0x4004be: baz() at /tmp/test.cpp:11:18
+ (inlined by) main at /tmp/test.cpp:15:0
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-print\-source\-context\-lines <N>
+Print \fBN\fP lines of source context for each symbolized address.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ llvm\-symbolizer \-\-obj=test.elf 0x400490 \-\-print\-source\-context\-lines=3
+baz()
+/tmp/test.cpp:11:0
+10 : volatile int k = 42;
+11 >: return foz() + k;
+12 : }
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-relativenames
+Print the file\(aqs path relative to the compilation directory, instead
+of the absolute path. If the command\-line to the compiler included
+the full path, this will be the same as the default.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-verbose
+Print verbose address, line and column information.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ llvm\-symbolizer \-\-obj=inlined.elf \-\-verbose 0x4004be
+baz()
+ Filename: /tmp/test.cpp
+ Function start filename: /tmp/test.cpp
+ Function start line: 9
+ Function start address: 0x4004b6
+ Line: 11
+ Column: 18
+main
+ Filename: /tmp/test.cpp
+ Function start filename: /tmp/test.cpp
+ Function start line: 14
+ Function start address: 0x4004b0
+ Line: 15
+ Column: 18
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-version, \-v
+Print version information for the tool.
+.UNINDENT
+.INDENT 0.0
+.TP
+.B @<FILE>
+Read command\-line options from response file \fI<FILE>\fP\&.
+.UNINDENT
+.SH WINDOWS/PDB SPECIFIC OPTIONS
+.INDENT 0.0
+.TP
+.B \-\-dia
+Use the Windows DIA SDK for symbolization. If the DIA SDK is not found,
+llvm\-symbolizer will fall back to the native implementation.
+.UNINDENT
+.SH MACH-O SPECIFIC OPTIONS
+.INDENT 0.0
+.TP
+.B \-\-default\-arch <arch>
+If a binary contains object files for multiple architectures (e.g. it is a
+Mach\-O universal binary), symbolize the object file for a given architecture.
+You can also specify the architecture by writing \fBbinary_name:arch_name\fP in
+the input (see example below). If the architecture is not specified in either
+way, the address will not be symbolized. Defaults to empty string.
+.INDENT 7.0
+.INDENT 3.5
+.sp
+.nf
+.ft C
+$ cat addr.txt
+/tmp/mach_universal_binary:i386 0x1f84
+/tmp/mach_universal_binary:x86_64 0x100000f24
+
+$ llvm\-symbolizer < addr.txt
+_main
+/tmp/source_i386.cc:8
+
+_main
+/tmp/source_x86_64.cc:8
+.ft P
+.fi
+.UNINDENT
+.UNINDENT
+.UNINDENT
+.INDENT 0.0
+.TP
+.B \-\-dsym\-hint <path/to/file.dSYM>
+If the debug info for a binary isn\(aqt present in the default location, look for
+the debug info at the .dSYM path provided via this option. This flag can be
+used multiple times.
+.UNINDENT
+.SH EXIT STATUS
+.sp
+\fBllvm\-symbolizer\fP returns 0. Other exit codes imply an internal program
+error.
+.SH SEE ALSO
+.sp
+\fBllvm\-addr2line(1)\fP
+.SH AUTHOR
+Maintained by the LLVM Team (https://llvm.org/).
+.SH COPYRIGHT
+2003-2023, LLVM Project
+.\" Generated by docutils manpage writer.
+.