dwww Home | Manual pages | Find package

dwz(1)                      General Commands Manual                     dwz(1)

NAME
       dwz - DWARF optimization and duplicate removal tool

SYNOPSIS
       dwz [OPTION...] [FILES]

DESCRIPTION
       dwz  is a program that attempts to optimize DWARF debugging information
       contained in ELF shared libraries and ELF executables for size, by  re-
       placing DWARF information representation with equivalent smaller repre-
       sentation where possible and by reducing the amount of duplication  us-
       ing  techniques  from  DWARF standard appendix E - creating DW_TAG_par-
       tial_unit compilation units (CUs) for duplicated information and  using
       DW_TAG_imported_unit 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  com-
       pliant DWARF Supplementary Object Files (DWARF 5, section 7.3.6) unless
       the --dwarf-5 option is used. Instead of a .debug_sup section  it  will
       generate  by  default  a .gnu_debugaltlink section. And it will use the
       DW_FORM_GNU_strp_alt    and     DW_FORM_GNU_reg_alt,     instead     of
       DW_FORM_strp_sup  and DW_FORM_ref_sup to keep compatibility with exist-
       ing DWARF consumers.

       DWARF 4 .debug_types are supported, but DWARF 5  DW_UT_type  units  are
       not.  Likewise .gdb_index is supported, but the DWARF 5 .debug_names is
       not. Also some forms and sections that are only  emitted  by  GCC  when
       generating    Split   DWARF,   DW_FORM_strx   and   .debug_str_offsets,
       DW_FORM_addrx and .debug_addr, DW_FORM_rnglistx and  DW_FORM_loclistsx,
       are not supported yet.

       The  tool has two main modes of operation, without the -m option it at-
       tempts to optimize DWARF debugging information  in  each  given  object
       (executable  or shared library) individually, with the -m option it af-
       terwards attempts to optimize even more by moving DWARF  debugging  in-
       formation  entries (DIEs), strings and macro descriptions duplicated in
       more than one object into a newly created ELF ET_REL object whose file-
       name  is  given  as -m option argument.  The debug sections in the exe-
       cutables and shared libraries specified on the command  line  are  then
       modified again, referring to the entities in the newly created object.

OPTIONS
       -m FILE --multifile FILE
              Multifile  mode.   After  processing  all  named executables and
              shared libraries, attempt to create ELF object FILE and put  de-
              bugging  information  duplicated  in more than one object there,
              afterwards optimize each named executable or shared library even
              further if possible.

       -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.

       -M NAME --multifile-name NAME
              Specify  the name of the common file that should be put into the
              .gnu_debugaltlink section alongside with its build ID.   By  de-
              fault dwz puts there the argument of the -m option.

       -r --relative
              Specify  that  the  name  of  the common file to be put into the
              .gnu_debugaltlink 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 -m option.  Either  -M  or  -r
              option can be specified, but not both.

       -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  na-
              tive, use native pointer size, as specified in the help message.

       -p <l|b|auto> --multifile-endian <l|b|auto|native>
              Specify  the endianity of the multifile.  If auto, use the endi-
              anity of the files, provided they match.  If native, use  native
              endianity, as specified in the help message.

       -q --quiet
              Silence up some of the most common messages.

       -o FILE --output FILE
              This  option  instructs dwz not to overwrite the specified file,
              but instead store the new content into FILE.  Nothing is written
              if  dwz  exits with non-zero exit code.  Can be used only with a
              single executable or shared library (if there are  no  arguments
              at all, a.out is assumed).

       -l <COUNT|none> --low-mem-die-limit <COUNT|none>
              Handle  executables  or  shared  libraries  containing more than
              COUNT debugging information entries in their .debug_info section
              using a slower and more memory usage friendly mode and don't at-
              tempt 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 dwz tool is
              32-bit binary, it might run out  of  available  virtual  address
              space  even  sooner).   Specifying none as argument disables the
              limit.

       -L <COUNT|none> --max-die-limit <COUNT|none>
              Don't attempt to optimize executables or shared  libraries  con-
              taining  more than COUNT DIEs at all.  The default is 50 million
              DIEs.  Specifying none as argument disables the limit.

       -5 --dwarf-5
              Emit standard DWARF 5 Supplementary Object Files with .debug_sup
              and  corresponding  forms, instead of the GNU extension .gnu_de-
              bugaltlink and corresponding forms.

       -j <N> --jobs <N>
              Process N files in parallel.  The default  is  processors  /  2.
              Disabled when multifile is used.

       --odr / --no-odr
              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.

       --odr-mode=<basic|link>
              Set the One-Definition-Rule optimization  aggressiveness:  basic
              or link.  When using the link setting, the optimization will at-
              tempt 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.

       --import-optimize / --no-import-optimize
              Enable/disable   optimization   that   reduces   the  number  of
              DW_TAG_imported_unit DIEs generated to import the partial  units
              created  by dwz.  Disabling the optimization can be used to work
              around problems in the optimization, or to make it easier to ob-
              serve which CU imports which PU.  Enabled by default.

       -? --help
              Print short help and exit.

       -v --version
              Print version number and short licensing notice and exit.

ARGUMENTS
       Command-line  arguments  should be the executables, shared libraries or
       their stripped to file separate debug information objects.

EXAMPLES
              $ dwz -m .dwz/foobar-1.2.debug -rh \
                bin/foo.debug bin/foo2.debug foo/lib/libbar.so.debug
       will  attempt  to  optimize  debugging  information  in  bin/foo.debug,
       bin/foo2.debug  and  lib/libbar.so.debug  (by  modifying  the  files in
       place) and when beneficial also will create .dwz/foobar-1.2.debug file.
       .gnu_debugaltlink  section  in  the  first  two  files  will  refer  to
       ../.dwz/foobar-1.2.debug  and  in  the  last  file  to  ../../.dwz/foo-
       bar-1.2.debug.    If   e.g.    bin/foo.debug  and  bin/foo2.debug  were
       hardlinked together initially, they will be hardlinked  again  and  for
       multifile  optimizations  considered  just as a single file rather than
       two.
              $ dwz -o foo.dwz foo
       will not modify foo but instead store the ELF object with optimized de-
       bugging information if successful into foo.dwz file it creates.
              $ dwz *.debug foo/*.debug
       will attempt to optimize debugging information in *.debug and foo/*.de-
       bug files, optimizing each file individually in place.
              $ dwz
       is equivalent to dwz a.out command.

SEE ALSO
       http://dwarfstd.org/doc/DWARF4.pdf , http://dwarfstd.org/doc/DWARF5.pdf
       , gdb(1).

AUTHORS
       Jakub Jelinek <jakub@redhat.com>, Tom de Vries <tdevries@suse.de>, Mark
       Wielaard <mark@klomp.org>

BUGS
       Use the Bugzilla link of the project web  page  or  our  mailing  list.
       https://sourceware.org/dwz/, <dwz@sourceware.org>.

                                  15 Feb 2021                           dwz(1)

Generated by dwww version 1.15 on Sat Jun 15 20:42:29 CEST 2024.