diff options
Diffstat (limited to 'dwarfdump/dwarfdump.1')
| -rw-r--r-- | dwarfdump/dwarfdump.1 | 523 |
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. |