Adding upstream version 0.15.upstream/0.15upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 207 insertions, 0 deletions

diff --git a/dwz.1 b/dwz.1
new file mode 100644
index 0000000..1cff329
--- /dev/null
+++ b/dwz.1
@@ -0,0 +1,207 @@
+.TH dwz 1 "15 Feb 2021"
+.SH NAME
+dwz \- DWARF optimization and duplicate removal tool
+.SH SYNOPSIS
+dwz
+.RB [OPTION...]\ [FILES]
+.SH DESCRIPTION
+\fBdwz\fR is a program that attempts to optimize DWARF debugging information
+contained in ELF shared libraries and ELF executables for size, by
+replacing DWARF information representation with equivalent smaller
+representation where possible and by reducing the amount of duplication
+using techniques from DWARF standard appendix E - creating
+\fIDW_TAG_partial_unit\fR
+compilation units (CUs) for duplicated information and using
+\fIDW_TAG_imported_unit\fR
+to import it into each CU that needs it.
+
+The tool handles DWARF 32-bit format debugging sections of versions 2,
+3, 4, most of version 5 and GNU extensions on top of those.  It is
+strongly recommended to use at least DWARF 3, but using DWARF 4 or
+higher will work much better.
+
+While most of DWARF 5 is supported dwz doesn't yet generate spec
+compliant DWARF Supplementary Object Files (DWARF 5, section
+7.3.6) unless the \fI--dwarf-5\fR option is used. Instead of a
+\fI.debug_sup\fR section it will generate by default a \fI.gnu_debugaltlink\fR
+section. And it will use the \fIDW_FORM_GNU_strp_alt\fR and
+\fIDW_FORM_GNU_reg_alt\fR, instead of \fIDW_FORM_strp_sup\fR
+and \fIDW_FORM_ref_sup\fR to keep compatibility with existing DWARF
+consumers.
+
+DWARF 4 \fI.debug_types\fR are supported, but DWARF 5 \fIDW_UT_type\fR
+units are not. Likewise \fI.gdb_index\fR is supported, but the DWARF 5
+\fI.debug_names\fR is not. Also some forms and sections that are only
+emitted by GCC when generating Split DWARF, \fIDW_FORM_strx\fR and
+\fI.debug_str_offsets\fR, \fIDW_FORM_addrx\fR and \fI.debug_addr\fR,
+\fIDW_FORM_rnglistx\fR and \fIDW_FORM_loclistsx\fR, are not supported
+yet.
+
+The tool has two main modes of operation, without the
+\fI-m\fR option it attempts to optimize DWARF debugging information in each
+given object (executable or shared library) individually, with the
+\fI-m\fR option it afterwards attempts to optimize even more by moving
+DWARF debugging information entries (DIEs), strings and macro descriptions
+duplicated in more than one object into a newly created ELF ET_REL
+object whose filename is given as
+\fI-m\fR
+option argument.  The debug sections in the executables and shared libraries
+specified on the command line are then modified again, referring to
+the entities in the newly created object.
+.SH OPTIONS
+.TP
+.B \-m\ FILE \-\-multifile FILE
+Multifile mode.
+After processing all named executables and shared libraries, attempt to
+create ELF object
+\fIFILE\fR
+and put debugging information duplicated in more than one object there,
+afterwards optimize each named executable or shared library even further
+if possible.
+.TP
+.B \-h\ \-\-hardlink
+Look for executables or shared libraries hardlinked together, instead
+of rewriting them individually rewrite just one of them and hardlink the
+rest to the first one again.
+.TP
+.B \-M NAME \-\-multifile-name NAME
+Specify the name of the common file that should be put into the
+\fI.gnu_debugaltlink\fR section alongside with its build ID.  By default
+\fBdwz\fR puts there the argument of the \fB-m\fR option.
+.TP
+.B \-r \-\-relative
+Specify that the name of the common file to be put into the
+\fI.gnu_debugaltlink\fR
+section is supposed to be relative path from the directory containing
+the executable or shared library to the file named in the argument
+of the \fB-m\fR option.  Either \fB-M\fR or \fB-r\fR
+option can be specified, but not both.
+.TP
+.B \-p N \-\-multifile-pointer-size <N|auto|native>
+Specify the pointer size of the multifile, in bytes.  If auto, use the
+pointer size of the files, provided they match.  If native, use native pointer
+size, as specified in the help message.
+.TP
+.B \-p <l|b|auto> \-\-multifile-endian <l|b|auto|native>
+Specify the endianity of the multifile.  If auto, use the endianity of
+the files, provided they match.  If native, use native endianity, as specified
+in the help message.
+.TP
+.B \-q \-\-quiet
+Silence up some of the most common messages.
+.TP
+.B \-o FILE \-\-output FILE
+This option instructs
+\fBdwz\fR not to overwrite the specified file, but instead store the new content
+into \fBFILE\fR.  Nothing is written if \fBdwz\fR
+exits with non-zero exit code.  Can be used only with a single executable
+or shared library (if there are no arguments at all,
+\fIa.out\fR
+is assumed).
+.TP
+.B \-l <COUNT|none> \-\-low\-mem\-die\-limit <COUNT|none>
+Handle executables or shared libraries containing more than
+\fICOUNT\fR debugging information entries in their \fI.debug_info\fR
+section using a slower and more memory usage friendly mode and don't
+attempt to optimize that object in multifile mode.
+The default is 10 million DIEs.  There is a risk that for very large
+amounts of debugging information in a single shared library or executable
+there might not be enough memory (especially when \fBdwz\fR
+tool is 32-bit binary, it might run out of available virtual address
+space even sooner).  Specifying none as argument disables the limit.
+.TP
+.B \-L <COUNT|none> \-\-max\-die\-limit <COUNT|none>
+Don't attempt to optimize executables or shared libraries
+containing more than
+\fICOUNT\fR DIEs at all.  The default is 50 million DIEs.  Specifying none as
+argument disables the limit.
+.TP
+.B \-5 \-\-dwarf\-5
+Emit standard DWARF 5 Supplementary Object Files with \fI.debug_sup\fR and
+corresponding forms, instead of the GNU extension \fI.gnu_debugaltlink\fR
+and corresponding forms.
+.TP
+.B \-j <N> \-\-jobs <N>
+Process \fIN\fR files in parallel.  The default is processors / 2.  Disabled
+when multifile is used.
+.TP
+.B \-\-odr / \-\-no-odr
+.B Experimental.
+Enable/disable One-Definition-Rule optimization for C++ compilation units.
+This optimization causes struct/union/class DIEs with the same name to be
+considered equal.  This has the effect that DIEs referring to distinct DIEs
+representing the same type (like f.i. pointer type DIEs) are considered equal,
+and may be deduplicated.  The status of this optimization is experimental.
+It's disabled in low-mem mode.
+Disabled by default.
+.TP
+.B \-\-odr-mode=<basic|link>
+Set the One-Definition-Rule optimization aggressiveness: basic or link.
+When using the link setting, the optimization will attempt to replace
+declarations of a struct/union/class with a corresponding definition.  When
+using the basic setting, that part of the optimization is disabled.
+In normal operation, the link setting should be used.  The basic setting is
+provided only as fallback in case of problems with the link setting.  Set to
+link by default.
+.TP
+.B \-\-import-optimize / \-\-no-import-optimize
+Enable/disable optimization that reduces the number of
+\fIDW_TAG_imported_unit\fR DIEs generated to import the partial units created
+by \fBdwz\fR.  Disabling the optimization can be used to work around problems
+in the optimization, or to make it easier to observe which CU imports which
+PU.
+Enabled by default.
+.TP
+.B \-? \-\-help
+Print short help and exit.
+.TP
+.B \-v \-\-version
+Print version number and short licensing notice and exit.
+.SH ARGUMENTS
+Command-line arguments should be the executables, shared libraries
+or their stripped to file separate debug information objects.
+.SH EXAMPLES
+.RS
+$ dwz -m .dwz/foobar-1.2.debug -rh \\
+  bin/foo.debug bin/foo2.debug foo/lib/libbar.so.debug
+.RE
+will attempt to optimize debugging information in
+\fIbin/foo.debug\fR, \fIbin/foo2.debug\fR and
+\fIlib/libbar.so.debug\fR (by modifying the files in place) and
+when beneficial also will create \fI.dwz/foobar-1.2.debug\fR file.
+\fI.gnu_debugaltlink\fR section in the first two files will refer to
+\fI../.dwz/foobar-1.2.debug\fR and in the last file to
+\fI../../.dwz/foobar-1.2.debug\fR.  If e.g.
+\fIbin/foo.debug\fR and \fIbin/foo2.debug\fR were hardlinked
+together initially, they will be hardlinked again and for multifile
+optimizations considered just as a single file rather than two.
+.RS
+$ dwz -o foo.dwz foo
+.RE
+will not modify \fIfoo\fR
+but instead store the ELF object with optimized debugging information
+if successful into \fIfoo.dwz\fR
+file it creates.
+.RS
+$ dwz *.debug foo/*.debug
+.RE
+will attempt to optimize debugging information in *.debug and foo/*.debug
+files, optimizing each file individually in place.
+.RS
+$ dwz
+.RE
+is equivalent to \fIdwz a.out\fR command.
+.SH SEE ALSO
+.BR http://dwarfstd.org/doc/DWARF4.pdf
+,
+.BR http://dwarfstd.org/doc/DWARF5.pdf
+,
+.BR gdb (1).
+.SH AUTHORS
+Jakub Jelinek <jakub@redhat.com>,
+Tom de Vries <tdevries@suse.de>,
+Mark Wielaard <mark@klomp.org>
+.SH BUGS
+Use the Bugzilla link of the project web page or our mailing list.
+.nh
+.BR https://sourceware.org/dwz/ ", " <dwz@sourceware.org> .