Provided by: dwarfdump_20180809-1_amd64 bug

NAME

       dwarfdump - dumps DWARF debug information of an ELF object

SYNOPSIS

       dwarfdump [options] objectfilename

DESCRIPTION

       The  dwarfdump  command  prints or checks DWARF sections as requested by specific options.
       With no options (but with the required objectfilename  )  all  sections  print  (but  some
       sections  cannot  be  printed  independently  safely, so those are only printed at offsets
       where the .debug_info section refers to those sections).

       As of June 2011 the printing options and the checking options are mutually  exclusive  (if
       checking  options  are  selected  the  section  details  are not printed). When errors are
       encountered dwarfdump does attempt to print sufficient context so that one can  understand
       exactly  where  the error is in the DWARF.  This change makes checking really large object
       files much easier.

       The format is intended to be human readable.  If a script is to parse the output,  the  -d
       option is useful.

       Not all sections actually exist in any given object file.

       The  format  may  change from release to release, so it is unwise to depend too heavily on
       the format.

       Frame information (.debug_frame and .eh_frame) is heavily dependent on the ABI/ISA of  the
       object  file.   By  default  we  use  a  generic  set of register names handling up to 100
       registers named r0-100.  The '-R'  option  uses  a  built-in  generic  register  name  set
       handling  up to 1200 registers named r0-r1199.  The '-x abi=<abi>' description below shows
       how to name an abi and use that to guide the -f or -F processing.  Unless the cpu for  the
       object  file being dumped has many registers, do not use -R or -x abi=generic as those can
       be needlessly slow dumping frame sections. Instead, use the correct abi (if it  exists  in
       dwarfdump.conf)  or  a  generic  such  as  -x abi=generic100 or -x abi=generic500.  To get
       MIPS/IRIX register names names and call the old version 2 libdwarf frame interface use the
       option '-x abi=mips'.  Without '-R' or '-x abi=<abi>' dwarfdump ignores the dwarfdump.conf
       file and uses compiled-in generic set of register names.  If no '-x name=<path>' is given,
       dwarfdump    looks    for    "./dwarfdump.conf",    "$HOME/.dwarfdump.conf",    "<install-
       prefix>/lib/dwarfdump.conf" and takes the first it finds.  If one or more '-x name=<path>'
       is given the last of these is used and all other such files are ignored.

       If '-x nosanitizestrings' is given then unprintable characters are not translated to '%xx'
       (two digit hex preceded by the '%' character)   (with  this  option  bogus  characters  in
       strings could cause terminal windows to behave oddly).

       Some  -k  (checking)  options  print so-called harmless errors.  These are compiler errors
       that do not cause any known problem and are only detected inside libdwarf  itself.   These
       are  difficult  to properly report in dwarfdump and any error strings may not appear close
       to the time the error was encountered.

       If zlib compression was used on the DWARF sections in the object file being read the  real
       section names such as .zdebug_info etc will be reported by dwarfdump.  When dwarfdump says
       something is at offset 55 of .zdebug_info (or the like)  keep  in  mind  that  the  offset
       applies  to  the  uncompressed section (in memory), not the .zdebug_ compressed section in
       objectfilename.

URI STYLE INPUT STRINGS

       The <objectfilename> and the options taking name strings look for URIs and  translate  the
       URI strings to characters by default (see -x, -c<compiler name>, -S, -u).  So any single %
       character is treated as if the following two characters are hex  digits  representing  the
       underlying  true  character.  Various characters are meaningful to shells (such as bash or
       sh) and to getopt (such as the space character) If the URI translation  does  anything  it
       prints  the  before  and after of the URI translation on standard output, so inspection of
       the first lines of output will show if URI did anything.  The  actual  options  themselves
       are  assumed  to be non-URI.  So in the option '-cS&T' the -c portion must be non-URI, but
       the & character might cause input issues so '-cS%26T' could be used instead.  To  actually
       input a single % character (in a name, for example), double it to %% on the command line.

       Options  -U  (turning off URI interpretation) and -q (making finding URI sequences silent)
       give finer control of URI interpretation.  PP As an example, to get a string'a b' make the
       string  'a%20b' (here the quote (') is for exposition not part of the string, though quote
       is certainly problematic in a name).  Instead of escaping " quotes  in  the  string,  type
       %25, as in
        'a  "b'  should  be  typed  'a%20%25b' Any characters can be typed in URI style, not just
       characters which are problematic to the shell or getopt.  We strongly suggest you not type
       URI-style  characters  where  such are not needed or use the % character itself in command
       line strings unless you must.

PRINTING OPTIONS

       -a     Print each section as independently  as  possible.  Sections  that  can  safely  be
              printed independently (like .debug_abbrev) have relevant info printed in the report
              (sometimes dependent on -v).

       -b     Print the .debug_abbrev section. Because the DWARF specifications do not  rule  out
              garbage  data  areas in .debug_abbrev (if they are not referenced from .debug_info)
              any garbage bytes can result in this print failing.

       -c     Print locations lists.

       -E     Print ELF header information and index, address and size for all sections.

       -Eh    Effectively does nothing (use another tool to print the Elf file header).

       -El    Print index, address and size for the .debug_line section.

       -Ei    Print index, address and size for the .debug_info section.

       -Ea    Print index, address and size for the .debug_abbrev section.

       -Ep    Print index, address and size for the .debug_pubnames section.

       -Er    Print index, address and size for the .debug_aranges section.

       -Ef    Print index, address and size for the .debug_frame section.

       -Eo    Print index, address and size for the .debug_loc section.

       -ER    Print index, address and size for the .debug_ranges section.

       -Es    Print index, address and size for the .debug_string section.

       -Et    Print index, address and size for the .debug_pubtypes section.

       -Ex    Print index, address and size for the .text section.

       -Ed    Print index, address and size for the .text and .debug_* sections.

       -f     Print the .debug_frame section.

       -F     Print the .eh_frame section.

       -h     Print the dwarfdump options list.

       -i     Print the .debug_info section.

       -I     Print the .gdb_index, .debug_cu_index, .debug_tu_index sections if any exist.

       -l     Print the .debug_info section and the associated line section data.

       -ls    Print the .debug_info section and the associated line section data, but  omits  the
              <pc> address. Useful when a comparison is required.

       -m     Print the .debug_macinfo section.

       -N     Print  .debug_ranges  section.  Because  the  DWARF  specifications do not rule out
              garbage data areas in .debug_ranges (if they are not referenced  from  .debug_info)
              any garbage bytes can result in this print failing.

       -p     Print the .debug_pubnames section.

       --print-str-offsets
              Print the .debug_str_offsets section.

       -r     Print the .debug_aranges section.

       -s     Print .debug_string section.

       -ta    Print the IRIX only sections .debug_static_funcs and .debug_static_vars.

       -tf    Print the IRIX only section .debug_static_funcs.

       -tv    Print the IRIX only section .debug_static_vars.

       -w     Print the IRIX-only .debug_weaknames section.

       -y     Print the .debug_pubtypes section (and .debug_typenames, an SGI IRIX-only section).

       Having  dwarfdump  print  relocations may help establish whether dwarfdump understands any
       relocations that might exist.

       -o     Print all relocation records as well as we can manage.

       -oi    Print .rel*debug_info relocations.

       -ol    Print .rel*debug_line relocation.

       -op    Print .rel*debug_pubnames relocation.

       -oa    Has no effect.

       -or    Print .rel*debug_aranges relocations.

       -of    Print .rel*debug_frame relocations.

       -oo    Print .rel*debug_loc relocations.

       -oR    Print .rel*debug_ranges relocations.

       -g     Normally used only for testing libdwarf, this  tells  dwarfdump  to  use  an  older
              dwarf_loclist()  interface  function  (a  function that cannot handle all DWARF4 or
              DWARF5 location lists).  Before November 2015 it implied -i, now you should use  -i
              -g to also get .debug_info printed.

       -V     Print a dwarfdump date/version string and stop.

CHECKING OPTIONS

       -cg    Restricts  checking  to compilers whose producer string starts with 'GNU' and turns
              off -cs.

       -cs    Restricts checking to compilers whose producer string starts with  'SN'  and  turns
              off -cg.

       -cname Restricts  checking  to  compilers  whose producer string contains 'name' (not case
              sensitive).  The 'name' is read as a URI string.

       -ka    Turns on all checking options except -kxe (-kxe might be slow enough one mignt  not
              want to use it routinely.)

       -kb    Checks for certain abbreviations section errors when reading DIEs.

       -kc    Checks for errors in constants in debug_info.

       -kd    Turns  on  full  reporting  of  error totals per producer.  (the default shows less
              detail).

       -kD    Turns on reporting of duplicated attributes.  Duplicated  attributes  on  a  single
              DW_TAG are improper DWARF, but at least one compiler emitted such.

       -ke    Turns on reading pubnames and checking for fde errors.

       -kE    Checks  the  integer encoding representation in debug_info, computing whether these
              integer values could fit in fewer bytes if represented in LEB128.

       -kf    Turns on checking for FDE errors.

       -kF    Turns on checking for line table errors.

       -kg    Turns on checking for unused gaps in .debug_info (these gaps are not an error, just
              a waste of space).

       -kG    Print  only  unique  errors.  Error  lines  are simpified (hex numbers removed, for
              example) and when a given  message  string  would  otherwise  appear  again  it  is
              suppressed.

       -ki    Causes  a  summary of checking results per compiler (producer) to be printed at the
              end.

       -kl    Turns on locations list checking.

       -km    Turns on checking of ranges.

       -kM    Turns on checking of aranges.

       -kr    Turns on DIE tag-attr combinations checking.

       -kR    Turns on reading DIEs and checking for forward declarations rom DW_AT_specification
              attributes.   (which  are  not  an  error  but  can be a source of inefficiency for
              debuggers).

       -ks    Turns on extra reporting for some DIE errors checking detects.

       -kS    Turns on checking DIE references for circular references.

       -kt    Turns on tag-tag combinations checking.

       -ku    Print tag-tree and tag-attribute usage (basic format).

       -kuf   Print tag-tree and tag-attribute  usage  (full  format).   For  standard  TAGs  and
              ATtributes this presents an overview of how they were used.

       -kx    Turns on check_frames.

       -kxe   Turns off basic check_frames and turns on extended frame checking.

       -ky    Turns on type_offset, decl_file checking,

OPTION MODIFIERS

       -C     Normally  when checking for tag-tag or tag-attribute combinations both the standard
              combinations and some common extensions are allowed.  With -C  the  extensions  are
              taken out of the allowed class of combinations.

       -d     When  printing DIEs, put all the attributes for each DIE on the same (long) line as
              the TAG. This makes searching for DIE information (as with grep)  much  simpler  as
              the entire DIE is on one line.

       -D     Turns  off  the  display of section offsets and attribute values in printed output.
              So the .debug_info output is just TAGs and Attributes.  For pubnames (and the like)
              it  removes  offsets  from the output.  For locations lists it removes offsets from
              the output, but that is useless since the attribute values don't  show  so  neither
              does the location data.

       -e     Turns on truncation of attribute and tag names. For example DW_TAG_foo becomes foo.
              Not compatible with checking, only useful for printing DIEs.

       -G     When printing, add global offsets to the offsets printed.

       -H number
              When printing or checking .debug_info, this terminates the  search  after  'number'
              compilation  units.  When  printing  frame  information  this  terminates  the  FDE
              reporting after 'number' FDEs and the CIE reporting (which occurs if one  adds  -v)
              after 'number' CIEs. Example '-H 1'

       -M     When  printing, this means one want to have the FORM show for each attribute.  If a
              -v is also added (or more than one) then details of any form indirection  are  also
              shown.

       -n     When  printing  frames,  this turns off the search for function names.  In a really
              large object the search can take more time than one wants to wait, so  this  avoids
              the search.

       -O file=<path>
              The  <path>  will  be used as the file name for output instead of writing to stdout
              (stdout is the default).

       -Q     Suppresses section data printing (set automatically with a checking option).

       -R     When printing frames for ABIs with lots  of  registers,  this  allows  up  to  1200
              registers  to  be  named  (like R999) without choosing an ABI with, for example '-x
              abi=ppc'

       -v     Increases the detail shown when printing.  In some sections, using more -v  options
              will  increase  the  detail  (one  to three are useful) or may change the report to
              show, for example, the actual line-data-commands instead  of  the  resultant  line-
              table.

SELECTIVE ENTRY PRINTING

       These  -S  options  stand alone and basic print information about the compilation unit and
       DIE where the string(s) appear.  At most one of each of the following is effective (so for
       example  one  can  only  have  one  'match',  but  one can have a 'match', an 'any', and a
       'regex').  Any -S causes the .debug_info section to be inspected.  No checking options  or
       printing options should be supplied with -S.

       If  v  is added to the -S option, the number of occurrences is printed.  (see below for an
       example).

       -S match=string
              When printing DIEs for each tag value  or  attribute  name  that  matches  'string'
              exactly print the compilation unit information and its section offset.  Any CU with
              no match is not printed.  The 'string' is read as a URI string.

       -S any=string
              When printing DIEs for each tag value or  attribute  name  that  contains  'string'
              somewhere  in  the  tag  or attribute (case insensitive) print the compilation unit
              information and its section offset.  Any CU with no  match  is  not  printed.   The
              'string' is read as a URI string.

       -S regex=string
              When  printing DIEs for each tag value or attribute name where the 'string' reqular
              expression matches print the compilation unit information and its  section  offset.
              Any CU with no match is not printed.  The 'string' is read as a URI string.

       The  string  cannot  have spaces or other characters which are meaningful to getopt(3) and
       the shell will strip off quotes and other characters.  So the string is assumed to  be  in
       URI  style  and  is translated.  In other words, to match 'a b' make the -S string 'a%20b'
       Instead of escaping " quotes in the string, type %25, as in
        'a "b' should be typed 'a%20%25b' (the '  are  for  exposition  here,  not  part  of  the
       strings).   Any  characters  can  be  typed  in  URI  style, not just characters which are
       problematic to the shell or getopt.

       The -S any= and -S regex= options are only usable if the library  functions  required  are
       found at configure time.

       The  -W  option  is  a  modifier  to  the -S option, and increases the amount of output -W
       prints.  An example v modifier to the -S option is shown below.  And we  show  the  -W  in
       context with a -S option.

       -S vmatch=string1
              Prints  information  about  the  DIEs  that  -S  matches  and  prints  the count of
              occurrences

       -S match=string1 -W
              Prints the parent tree and the children tree for the DIEs that -S matches.

       -S match=string2 -Wp
              Prints the parent tree for the DIEs that -S matches.

       -S match=string3 -Wc
              Prints the parent tree for the DIEs that -S matches.

OTHER OPTIONS

       -# number
              This option controls internal debugging output,  higher  numbers  mean  more  debug
              actions. See the source code.

       -x name=/p/a/t/h.conf
              The file path given is the name of a file assumed to be a dwarfdump.conf-like file.
              The file path is read as a URI string.

       -x abi=ppc
              Selects the abi  (from  a  dwarfdump.conf  file)  to  be  used  in  printing  frame
              information (here using ppc as an example).  The abi is read as a URI string.

       -x groupnumber=<n>
              For  an object file with both DWARF5 split dwarf (.debug_info.dwo for example)  and
              ordinary DWARF sections (.debug_info for example) in the  single  object  file  one
              must  use -x groupnumber=2 to print the dwo sections.  Adding -x tied=<path> naming
              the same object file ties in the non-dwo sections.

       -x tied=/t/i/depath
              Used when opening a main object that is a .dwo or .dwp file.  The  tied  file  path
              names the executable which has the .debug_addr section that may be referred to from
              the main object. See Split Objects (aka Debug Fission).

       -x line5=s2l
              Normally used only to test libdwarf interfaces.  There are  4  different  interface
              function  sets and to ensure they all work this option lets us choose which to use.
              The options are 's2l' (default, Allows standard and two-level line tables using the
              latest  interface functions), 'std' (Allows standard single level line tables using
              the latest interface functions), 'orig' (allows  DWARF2,3,4  original  line  tables
              using  an  older interface function set), 'orig2l' (allows original line tables and
              some two-level line tables using an older interface set).

       -P     When checking this adds the list of compilation-unit names seen for each  producer-
              compiler to the printed checking results.

       -q     When  a  URI is found and translated while reading the command line, be quiet about
              the URI translation. That is,  don't  print  the  original  and  translated  option
              strings.

       -E     Turns on printing object-internal header data for some systems (for Unix/Linux does
              nothing).

       -u cuname
              Turns on selective printing of DIEs (printing  like  -i).   Only  the  DIEs  for  a
              compilation unit that match the name provided are printed.  If the compilation unit
              is ./a/b/c.c the 'cuname' you provide should be c.c as the characters  through  the
              final  path-separating  / are ignored.  If 'cuname' begins with a / then the entire
              name string of a compilation unit must match 'cuname'.  The 'cuname' is read  as  a
              URI string.

       -U     Turn off the URI interpretation of the command line strings entirely. Must be be on
              the command line before any URI strings encountered to be fully effective.

       -z     No longer supported.

FILES

       dwarfdump

        ./dwarfdump.conf

       $(HOME)/.dwarfdump.conf

       $(HOME)/dwarfdump.conf

       <install-prefix>/lib/dwarfdump.conf

NOTES

       In some cases compilers use DW_FORM_data1 (for example) and in such cases  the  signedness
       of  the  value  must  be taken from context. Rather than attempt to determine the context,
       dwarfdump prints the value with both signednesses whenever there is  ambiguity  about  the
       correct  interpretation.  For example, "DW_AT_const_value           176(as signed = -80)".
       For normal DWARF consumers that correctly and fully evaluate all attributes  there  is  no
       ambiguity  of  signedness: the ambiguity for dwarfdump is due to dwarfdump evaluating DIEs
       in a simple order and not keeping track of much context.

BUGS

       Support for DWARF3 is being completed but may not be complete.

                                                                                      DWARFDUMP()