Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, February 9, 2022
 
 

dwarfdump (1)

Name

dwarfdump - dumps DWARF debug information of an ELF object

Synopsis

dwarfdump [options] objectfilename

Description

DWARFDUMP()                                                        DWARFDUMP()



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  objectfile-
       name ) all sections print (but some sections cannot be printed indepen-
       dently  safely,  so  those  are  only  printed  at  offsets  where  the
       .debug_info section refers to those sections).


       All  options  are available in the traditional (single-letter) form and
       in a long-options form with meaningful names.


       With no options dwarfdump prints a basic set of DWARF section  informa-
       tion.   If  any  option  is  given on the command line the basic set is
       ignored and one must tell dwarfdump what to print or check (for example
       by adding the -a option).


       As of June 2011 the printing options and the checking options are mutu-
       ally 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 --format-dense (-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-r99.

       The --format-registers (-R) option uses  a  built-in  generic  register
       name set handling up to 1200 registers named r0-r1199.

       The  -file-abi=<abi> (-x abi=<abi>) description below shows how to name
       an abi and use that to  guide  the  --print-frame (-f)  or  --print-eh-
       frame (-F) processing.

       Unless  one  of --print-frame (-f) or --print-eh-frame (-F) or --print-
       all (-a) is used any abi reference is ignored  because  no  frame  data
       will be printed.


       Unless  the cpu for the object file being dumped has many registers, do
       not use --format-registers or -file-abi=<abi> as  those  can  be  need-
       lessly slow dumping frame sections. Instead, use the correct abi (if it
       exists   in   dwarfdump.conf)   or   a   generic   such   as    --file-
       abi=abi=generic100 or --file-abi=abi=generic500
        .

       The  most useful abi choices are likely mips or x86 or x86_64 or ppc or
       arm
        .  Without --format-registers (-R)  or  -file-abi=<abi> (-x abi=<abi>)
       dwarfdump  ignores the dwarfdump.conf file and uses compiled-in generic
       set of register names.  If  no  --file-name=<path> (-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  --file-name=<path> (-x name=<path>) is given the last of
       these is used and all other such files are ignored.

       Some checking ( -k) options (See "Check DWARF Integrity"  in  the  help
       output)  print  so-called  harmless  errors.  These are compiler errors
       that do not cause any known problem and are only detected inside  libd-
       warf  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 sec-
       tion in objectfilename.

URI STYLE INPUT STRINGS
       The <objectfilename> and all the options taking name strings  look  for
       URIs  and  translate  the URI strings to characters by default.  So any
       single % character is treated as if the following  two  characters  are
       hex digits representing the underlying true character.  Various charac-
       ters 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  --format-producer=S&T (-cS&T) the & character might cause input
       issues so --format-producer=S%26T should be used instead.  To  actually
       input a single % character (in a name, for example), double it to %% on
       the command line (or simply use %25).

       Options --format-suppress-uri (-U) (turning off URI interpretation) and
       --format-suppress-uri-msg (-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 exposi-
       tion 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
       --print-all (-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).


       --print-abbrev (-b)
              Print  the  .debug_abbrev  section. Because the DWARF specifica-
              tions 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.


       --print-loc (-c)
              Print locations lists.


       --elf (-E)
              prints, for Elf objects, object file details.   See  the  "Print
              ELF  sections  header"  section  of the help file for additional
              choices on elf printing.  If  libdwarf  or  dwarfdump  is  built
              without libelf this option is unavailable.


       --print-frame (-f)
              Print the .debug_frame section.

       --print-eh-frame (-F)
              Print the GNU .eh_frame section.


       --print-info (-i)
              Print the .debug_info section.


       --print-fission (-I)
              Print  any .gdb_index, .debug_cu_index, and .debug_tu_index sec-
              tions that exist in the object.


       --print-gnu-debuglinkIfthe.gnu_debuglinksection
              is present its content is printed.   If  the  .note.gnu.build-id
              section  is present its content is printed.  If a DWARF contain-
              ing file named by the  content  of  the  .gnu_debuglink  section
              exists the name will be printed.


       --print-lines (-l)
              Print  the  .debug_info  section and the associated line section
              data.

       --print-lines-short (-ls)
              Print the .debug_info section and the  associated  line  section
              data,  but  omit  the <pc> address.  Useful when a comparison of
              line sections from objects with slight differences is required.


       --print-macinfo (-m)
              Print the .debug_macinfo (DWARF 2,3,4) and .debug_macro (DWARF5)
              sections.


       --print-ranges (-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.


       --print-pubnames (-p)
              Print the .debug_pubnames section.


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


       --print-aranges (-r)
              Print the .debug_aranges section.

       --print-strings (-s)
              Print .debug_string section.


       --print-static (-ta)
              Print   the   IRIX   only   sections   .debug_static_funcs   and
              .debug_static_vars.


       --print-type (-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.  Other tools may be more
       useful than dwarfdump for printing  object-file  details.   See  "Print
       Relocations Info" in the help output for additional relocation printing
       choices.


       --reloc (-o)
              Print all relocation records as well as we can manage.  If libd-
              warf  or  dwarfdump  were  built  without  libelf this option is
              unavailable.


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


CHECKING OPTIONS
       --check-all (-ka)
              Turns   on   all   checking   options   except    --check-frame-
              extended (-kxe)  (which  might be slow enough one might not want
              to use it routinely.)


       --check-abbrev (-kb)
              Checks for certain abbreviations  section  errors  when  reading
              DIEs.


       --check-constants (-kc)
              Checks for errors in constants in debug_info.

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

       --check-silent-ks
              Turns off some verbose checking detection.


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

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

       --check-attr-encodings (-kE)
              Checks the integer encoding representation in  debug_info,  com-
              puting  whether these integer values could fit in fewer bytes if
              represented in LEB128.


       --check-frame-info (-kf)
              Turns on checking for FDE errors (.debug_frame and .eh_frame).

       --check-files-lines (-kF)
              Turns on checking for line table errors.

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

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

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


       --check-loc (-kl)
              Turns on locations list checking.

       --check-ranges (-km)
              Turns on checking of ranges.

       --check-aranges (-kM)
              Turns on checking of aranges.

       --check-tag-attr (-kr)
              Turns on DIE tag-attr combinations checking,  looking  for  sur-
              prising attributes for DIE tags.

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

       --check-self-refs (-kS)
              Turns on checking DIE references for circular references.

       --check-tag-tag (-kt)
              Turns  on  tag-tag combinations checking, looking for surprising
              parent-child DIE relationships.

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

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


       --check-frame-basic (-kx)
              Turns on basic frames checking for .debug_frame and .eh_frame).

       --check-frame-extended (-kxe)
              Turns off basic check_frames and turns on extended frame  check-
              ing for .debug_frame and .eh_frame.  This option can be slow.


       --check-type (-ky)
              Turns on type_offset checking (ensuring local attribute  offsets
              refer to what they should) and  that  DW_AT_decl_file  and  some
              other offsets refer to appropriate locations.


OPTION MODIFIERS
       --format-extensions (-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.


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


       --format-supress-offsets (-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.


       --format-ellipsis (-e)
              Turns on truncation of attribute  and  tag  names.  For  example
              DW_TAG_foo  becomes foo. Not compatible with checking, only use-
              ful for printing DIEs.


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


       --format-limit=<num> (-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 '--format-limit=1'


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


       --format-suppress-lookup (-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.


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


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


       --format-registers (-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'


       --version (-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  --search  (-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  --search  (-S) causes the .debug_info section to be inspected.  No
       checking  options  or  printing  options  should   be   supplied   with
       --search(-S)  options.   The  strings should use URI-style to avoid any
       conflicts with the command-line parser applicable (bash, sh,  ...)   or
       getopt().

       These  are  particularly useful when the amount of DWARF information is
       really large.

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


       --search-match=<string> (-Smatch=string)

       --search-match-count=<string> (-Svmatch=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.   The  count  (Sv)  form
              reports the count of occurrences.


       --search-any=<string> (-Sany=string)

       --search-any-count=<string> (-Svany=string)
              When  printing  DIEs  for  each tag value or attribute name that
              contains 'string' somewhere in the tag or attribute (case insen-
              sitive)  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 count (Sv) form reports the count of
              occurrences.


       --search-regex=string (-Sregex=string)

       --search-regex-count=string (-Svregex=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
              count (Sv) form reports the count of occurrences.


       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 --search-any (-Sany) and  --regex-any (-Sregex)  options  are  only
       usable  if  regular-expression  library functions required are found at
       configure time.

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


       --search-match-count=string1 (-S vmatch=string1)
              Prints information about the DIEs that -S matches and prints the
              count of occurrences.


       -S match=string1 -W


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


       -S match=string2 -Wp


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


       -S match=string3 -Wc

       --search-match=string3 --search-print-children
              Prints the children tree for the DIEs that -S matches.


       --format-gcc (-cg)
              Restricts  printing/checking  to compilers whose producer string
              starts with 'GNU' and turns off -cs.


       --format-snc (-cs)
              Restricts printing/checking to compilers whose  producer  string
              starts with 'SN' and turns off -cg.


       --format-producer=<name> (-c<name>)
              Restricts  printing/checking  to compilers whose producer string
              contains 'name' (not case sensitive).  The 'name' is read  as  a
              URI string.



OTHER OPTIONS
       -x name=<path>

       --file-name=/p/a/t/h.conf (-xname=/p/a/t/h.conf)
              The file path given is the name of a file assumed to be a dwarf-
              dump.conf-like file.  The file path is read as a URI string.


       -x abi=ppc

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


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


       -x tied=/t/i/depath

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

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


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

       -q

       --format-suppress-uri-msg
              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.


       -u cuname

       --format-file=<file>
              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 'file' is read as a URI string.


       -U

       --format-suppress-uri
              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.   Likely  something  no  one
              needs to do.


       -h

       --help Show this man page.


FILES
       dwarfdump

        ./dwarfdump.conf

       $(HOME)/.dwarfdump.conf

       $(HOME)/dwarfdump.conf

       <install-prefix>/lib/dwarfdump.conf


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | library/libdwarf |
       +---------------+------------------+
       |Stability      | Volatile         |
       +---------------+------------------+

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

       Source  code  for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source    was    downloaded    from    https://www.prevanders.net/libd-
       warf-20191104.tar.gz.

       Further information about this software can be found on the open source
       community website at https://www.prevanders.net/dwarf.html.

BUGS
       Support for DWARF5 is being completed but may not be complete.




                                                                   DWARFDUMP()