Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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  .de-
       bug_info	section	refers to those	sections).

       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 -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 de-
       pend 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' op-
       tion uses a built-in generic register name set handling up to 1200 reg-
       isters 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 sec-
       tions. 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",	 "<in-
       stall-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 win-
       dows 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 de-
       tected 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 re-
       ported 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<com-
       piler  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 %  charac-
       ter (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  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.

       -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_* sec-
	      tions.

       -f     Print the	.debug_frame section.

       -F     Print the	.eh_frame section.

       -h     Print IRIX exception tables (unsupported).

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

       -r     Print the	.debug_aranges section.

       -s     Print .debug_string section.

       -ta    Print  the  IRIX	only  sections	.debug_static_funcs  and  .de-
	      bug_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  No-
	      vember  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  de-
	      fault shows less detail).

       -kD    Turns  on	 reporting  of	duplicated attributes.	Duplicated at-
	      tributes 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, com-
	      puting 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 oth-
	      erwise 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 stan-
	      dard 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	check-
	      ing.

       -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	infor-
	      mation  (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 At-
	      tributes.	 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  use-
	      ful 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 in-
	      formation	 this terminates the FDE reporting after 'number' FDEs
	      and the CIE reporting (which occurs if one adds -v) after	 'num-
	      ber' 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 al-
	      lows up to 1200 registers	to be named (like R999)	without	choos-
	      ing an ABI with, for example '-x abi=ppc'

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

SELECTIVE ENTRY	PRINTING
       These -S	options	stand alone and	basic print information	about the com-
       pilation	 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	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.

       -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 es-
       caping "	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	 func-
       tions 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	dwarf-
	      dump.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 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  .de-
	      bug_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' (al-
	      lows 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  en-
	      tirely.  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	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.

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

								   DWARFDUMP()

NAME | SYNOPSIS | DESCRIPTION | URI STYLE INPUT STRINGS | PRINTING OPTIONS | CHECKING OPTIONS | OPTION MODIFIERS | SELECTIVE ENTRY PRINTING | OTHER OPTIONS | FILES | NOTES | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=dwarfdump&sektion=1&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help