Imported Upstream version 20120410upstream/20120410upstream

1 files changed, 523 insertions, 0 deletions

diff --git a/dwarfdump/dwarfdump.1 b/dwarfdump/dwarfdump.1
new file mode 100644
index 0000000..bb7ee37
--- /dev/null
+++ b/dwarfdump/dwarfdump.1
@@ -0,0 +1,523 @@
+.TH DWARFDUMP
+.SH NAME
+dwarfdump \- dumps DWARF debug information of an ELF object
+.SH SYNOPSIS
+.B dwarfdump [options] \f2objectfilename\fP
+.SH DESCRIPTION
+The 
+.B dwarfdump
+command prints or checks DWARF sections as requested by specific options.
+With no options (but with the required \f2objectfilename\fP ) 
+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).
+.PP
+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.
+.PP
+The format is intended to be human readable.
+If a script is to parse the output, the
+.B \-d
+option is useful.
+.PP
+Not all sections actually exist in any given object file.
+.PP
+The format may change from release to release, so it is
+unwise to depend too heavily on the format.
+.PP
+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.
+.PP
+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.
+.SH URI STYLE INPUT STRINGS
+.PP
+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.
+.PP
+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.
+.SH PRINTING OPTIONS
+.TP
+.B \-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).
+
+.TP
+.B \-b
+Print the .debug_abbrev section. Because the DWARF specfications
+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.
+
+.TP
+.B \-c
+Print locations lists.
+
+.TP
+.B \-f
+Print the .debug_frame section.
+.TP
+.B \-F
+Print the .eh_frame section.
+
+.TP
+.B \-i
+Print  the .debug_info section.
+
+.TP
+.B \-l
+Print the .debug_info section and the associated line section data.
+
+.TP
+.B \-m
+Print the .debug_macinfo section.
+
+.TP
+.B \-N
+Print .debug_ranges section.  Because the DWARF specfications
+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.
+
+.TP
+.B \-p
+Print the .debug_pubnames section.
+
+.TP
+.B \-r
+Print the .debug_aranges section.
+.TP
+.B \-s
+Print .debug_string section.
+
+.TP
+.B \-ta
+Print the IRIX only sections .debug_static_funcs and .debug_static_vars.
+
+.TP
+.B \-tf
+Print the IRIX only section .debug_static_funcs.
+.TP
+.B \-tv
+Print the IRIX only section .debug_static_vars.
+
+.TP
+.B \-w
+Print the IRIX-only .debug_weaknames section.
+
+.TP
+.B \-y
+Print the .debug_pubtypes section (and .debug_typenames,
+an SGI IRIX-only section).
+
+.PP
+Having dwarfdump print relocations may help establish whether
+dwarfdump understands any relocations that might exist.
+
+.TP
+.B \-o    
+Print all relocation records as well as we can manage.
+.TP
+.B \-oi  
+Print .rel*debug_info relocations.
+.TP
+.B \-ol  
+Print .rel*debug_line relocation.
+.TP
+.B \-op  
+Print .rel*debug_pubnames relocation.
+.TP
+.B \-oa  
+Has no effect.
+.TP
+.B \-or  
+Print .rel*debug_aranges relocations.
+.TP
+.B \-of  
+Print .rel*debug_frame relocations.
+.TP
+.B \-oo  
+Print .rel*debug_loc relocations.
+.TP
+.B \-oR  
+Print .rel*debug_ranges relocations.
+
+.TP
+.B \-g
+Normally used only for testing libdwarf, this tells dwarfdump to
+print .debug_info and use an older dwarf_loclist() interface
+function (a function that cannot handle all current
+location lists).
+.TP
+.B \-V  
+Print a dwarfdump date/version string and stop.
+
+.SH CHECKING OPTIONS
+.TP
+.B \-cg 
+Restricts checking to compilers whose
+producer string starts with 'GNU'
+and turns off -cs .
+
+.TP
+.B \-cs
+Restricts checking to compilers whose
+producer string starts with 'SN'
+and turns off -cg .
+.TP
+.B \-cname
+Restricts checking to compilers whose
+producer string contains 'name' (not case sensitive).
+The 'name' is read as a URI string.
+
+.TP
+.B \
+-ka        : Turns on all checking options except -kxe (-kxe might
+             be slow enough one mignt not want to use it routinely.)
+
+.TP
+.B \
+-kb        : Checks for certain abbreviations section errors when reading
+             DIEs.
+.TP
+.B \-kc 
+Checks for errors in constants in debug_info.
+.TP
+.B \-kd 
+Turns on full reporting of error totals per producer.
+(the default shows less detail).
+.TP
+.B \-ke 
+Turns on reading pubnames and checking for fde errors.
+.TP
+.B \-kf 
+Turns on checking for FDE errors.
+.TP
+.B \-kF 
+Turns on checking for line table errors.
+.TP
+.B \-kg 
+Turns on checking for unused gaps in .debug_info (these
+gaps are not an error, just a waste of space).
+
+.TP
+.B \-ki 
+Causes a summary of checking results per compiler (producer)
+to be printed at the end.
+.TP
+.B \-kl 
+Turns on locations list checking.
+.TP
+.B \-km 
+Turns on checking of ranges.
+.TP
+.B \-kM 
+Turns on checking of aranges.
+.TP
+.B \-kr
+Turns on DIE tag-attr combinations checking.
+.TP
+.B \-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).
+.TP
+.B \-ks 
+Turns on extra reporting for some DIE errors checking detects .
+.TP
+.B \-kS 
+Turns on checking DIE references for circular references.
+.TP
+.B \-kt 
+Turns on tag-tag combinations checking.
+.TP
+.B \-kx 
+Turns on check_frames.
+.TP
+.B \-kxe 
+Turns off basic check_frames and turns on extended frame checking.
+.TP
+.B \-ky 
+Turns on type_offset, decl_file checking,
+
+.SH OPTION MODIFIERS
+
+.TP
+.B \-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.
+
+.TP
+.B \-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.
+
+.TP
+.B \-D
+Turns off the display of section offsets and attribute values in printed output.
+So the .debug_info output isjust 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.
+
+.TP
+.B \-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.
+
+.TP
+.B \-G
+When printing, add global offsets to the offsets printed.
+
+.TP
+.B \-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'
+
+.TP
+.B \-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.
+
+.TP
+.B \-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.
+
+.TP
+.B \-Q 
+Suppresses section data printing (set automatically with a checking option).
+
+.TP
+.B \-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'
+
+.TP 
+.B \-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.
+
+.SH SELECTIVE ENTRY PRINTING
+
+.PP
+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.
+
+.TP
+.B \-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.
+.TP
+.B \-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.
+.TP
+.B \-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.
+
+.PP
+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.
+.PP
+The -S any= and -S regex= options are only usable
+if the library functions required are found at configure time.
+.PP
+The -W option is a modifier to the -S option, and
+increases the amount of output -W prints.
+Now we show the -W in context with a -S option.
+
+.TP
+.B \-S match=string1 -W
+Prints the parent tree and the children tree for the
+DIEs that -S matches.
+
+.TP
+.B \-S match=string2 -Wp
+Prints the parent tree for the DIEs that -S matches.
+
+.TP
+.B \-S match=string3 -Wc
+Prints the parent tree for the DIEs that -S matches.
+
+.SH OTHER OPTIONS
+
+.TP
+.B \-# number 
+This option controls internal debugging output,
+higher numbers mean more debug actions. See the source code.
+
+
+.TP
+.B \-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.
+
+.TP
+.B \-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.
+
+.TP
+.B \-P 
+When  checking this adds the list of compilation-unit names
+seen for each producer-compiler to the printed checking results.
+.TP
+.B \-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.
+
+.TP
+.B \-E 
+Turns on printing object-internal header data for some
+systems (for Unix/Linux does nothing).
+
+.TP
+.B \-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.
+
+.TP
+.B \-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.
+
+.TP
+.B \-z
+No longer suported.
+
+
+.SH FILES
+dwarfdump
+
+dwarfdump.conf
+
+./dwarfdump.conf
+
+$(HOME)/.dwarfdump.conf
+
+$(HOME)/dwarfdump.conf
+
+<install-prefix>/lib/dwarfdump.conf
+.SH 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.
+.SH BUGS
+Support for DWARF3 is being completed but may not be complete.