Crate gimli [−] [src]
A lazy, zero-copy parser for the DWARF debugging information format.
Zero-copy: everything is just a reference to the original input buffer. No copies of the input data ever get made.
Lazy: only the compilation units' entries that you iterate over get parsed, and only as deep as you ask. Skip over a compilation unit and its entries don't get parsed.
Cross-platform:
gimliisn't coupled to any platform or object file format. Use your own ELF parser on Linux or a Mach-O parser on OSX.- Unsure which object file parser to use? Try the cross-platform
objectcrate.
- Unsure which object file parser to use? Try the cross-platform
This library primarily targets the fourth edition of the standard (the most recent, at time of writing).
Example Usage
Print out all of the functions in the debuggee program:
extern crate gimli; // Read the .debug_info and .debug_abbrev sections with whatever object // loader you're using. let debug_info = gimli::DebugInfo::<gimli::LittleEndian>::new(read_debug_info()); let debug_abbrev = gimli::DebugAbbrev::<gimli::LittleEndian>::new(read_debug_abbrev()); // Iterate over all compilation units. let mut iter = debug_info.units(); while let Some(unit) = try!(iter.next()) { // Parse the abbreviations for this compilation unit. let abbrevs = try!(unit.abbreviations(debug_abbrev)); // Iterate over all of this compilation unit's entries. let mut entries = unit.entries(&abbrevs); while let Some((_, entry)) = try!(entries.next_dfs()) { // If we find an entry for a function, print it. if entry.tag() == gimli::DW_TAG_subprogram { println!("Found a function: {:?}", entry); } } }
See the example programs for complete examples.
API Structure
Basic familiarity with DWARF is assumed.
Each section gets its own type. Consider these types the entry points to the library:
DebugAbbrev: The.debug_abbrevsection.DebugAranges: The.debug_arangessection.DebugFrame: The.debug_framesection.DebugInfo: The.debug_infosection.DebugLine: The.debug_linesection.DebugLoc: The.debug_locsection.DebugPubNames: The.debug_pubnamessection.DebugPubTypes: The.debug_pubtypessection.DebugRanges: The.debug_rangessection.DebugStr: The.debug_strsection.DebugTypes: The.debug_typessection.
Each section type exposes methods for accessing the debugging data encoded in that section. For example, the
DebugInfostruct has theunitsmethod for iterating over the compilation units defined within it.Offsets into a section are strongly typed: an offset into
.debug_infois theDebugInfoOffsettype. It cannot be used to index into theDebugLinetype becauseDebugLinerepresents the.debug_linesection. There are similar types for offsets relative to a compilation unit rather than a section.
Using with FallibleIterator
The standard library's Iterator trait and related APIs do not play well
with iterators where the next operation is fallible. One can make the
Iterator's associated Item type be a Result<T, E>, however the
provided methods cannot gracefully handle the case when an Err is
returned.
This situation led to the
fallible-iterator crate's
existence. You can read more of the rationale for its existence in its
docs. The crate provides the helpers you have come to expect (eg map,
filter, etc) for iterators that can fail.
gimli's many lazy parsing iterators are a perfect match for the
fallible-iterator crate's FallibleIterator trait because parsing is not
done eagerly. Parse errors later in the input might only be discovered after
having iterated through many items.
To use gimli iterators with FallibleIterator, import the crate and trait
into your code:
// Add the `fallible-iterator` crate. Don't forget to add it to your // `Cargo.toml`, too! extern crate fallible_iterator; extern crate gimli; // Use the `FallibleIterator` trait so its methods are in scope! use fallible_iterator::FallibleIterator; use gimli::{DebugAranges, LittleEndian}; fn find_sum_of_address_range_lengths(aranges: DebugAranges<LittleEndian>) -> gimli::Result<u64> { // `DebugAranges::items` returns a `FallibleIterator`! aranges.items() // `map` is provided by `FallibleIterator`! .map(|arange| arange.length()) // `fold` is provided by `FallibleIterator`! .fold(0, |sum, len| sum + len) }
Structs
| Abbreviation |
An abbreviation describes the shape of a |
| Abbreviations |
A set of type abbreviations. |
| ArangeEntry |
A single parsed arange. |
| Attribute |
An attribute in a |
| AttributeSpecification |
The description of an attribute in an abbreviated type. It is a pair of name and form. |
| AttrsIter |
An iterator over a particular entry's attributes. |
| Augmentation |
We support the z-style augmentation defined by |
| BaseAddresses |
Optional base addresses for the relative |
| CallFrameInstructionIter |
A lazy iterator parsing call frame instructions. |
| CfiEntriesIter |
An iterator over CIE and FDE entries in a |
| CommonInformationEntry |
|
| CompilationUnitHeader |
The header of a compilation unit's debugging information. |
| CompilationUnitHeadersIter |
An iterator over the compilation- and partial-units of a section. |
| CompleteLineNumberProgram |
A line number program that has previously been run to completion. |
| DebugAbbrev |
The |
| DebugAbbrevOffset |
An offset into the |
| DebugFrame |
|
| DebugFrameOffset |
An offset into the |
| DebugInfo |
The |
| DebugInfoOffset |
An offset into the |
| DebugLine |
The |
| DebugLineOffset |
An offset into the |
| DebugLoc |
The |
| DebugLocOffset |
An offset into the |
| DebugMacinfoOffset |
An offset into the |
| DebugRanges |
The |
| DebugRangesOffset |
An offset into the |
| DebugStr |
The |
| DebugStrOffset |
An offset into the |
| DebugTypeSignature |
A type signature as used in the |
| DebugTypes |
The |
| DebugTypesOffset |
An offset into the |
| DebuggingInformationEntry |
A Debugging Information Entry (DIE). |
| DwAccess | |
| DwAddr | |
| DwAt | |
| DwAte | |
| DwCc | |
| DwCfa | |
| DwChildren | |
| DwDs | |
| DwDsc | |
| DwEhPe | |
| DwEnd | |
| DwForm | |
| DwId | |
| DwInl | |
| DwLang | |
| DwLne | |
| DwLns | |
| DwOp | |
| DwOrd | |
| DwTag | |
| DwVirtuality | |
| DwVis | |
| EhFrame |
|
| EhFrameOffset |
An offset into the |
| EndianBuf |
A |
| EntriesCursor |
A cursor into the Debugging Information Entries tree for a compilation unit. |
| EntriesTree |
The state information for a tree view of the Debugging Information Entries. |
| EntriesTreeIter |
An iterator that allows recursive traversal of the Debugging Information Entry tree. |
| Evaluation |
A DWARF expression evaluator. |
| FileEntry |
An entry in the |
| FrameDescriptionEntry |
A |
| IncompleteLineNumberProgram |
A line number program that has not been run to completion. |
| InitializedUnwindContext |
An initialized unwinding context. |
| LineNumberProgramHeader |
A header for a line number program in the |
| LineNumberRow |
A row in the line number program's resulting matrix. |
| LineNumberSequence |
A sequence within a line number program. A sequence, as defined in section 6.2.5 of the standard, is a linear subset of a line number program within which addresses are monotonically increasing. |
| LocationListEntry |
A location list entry from the |
| LocationListIter |
An iterator over a location list. |
| OpcodesIter |
An iterator yielding parsed opcodes. |
| PartialFrameDescriptionEntry |
A partially parsed |
| Piece |
The description of a single piece of the result of a DWARF expression. |
| PubNamesEntry |
A single parsed pubname. |
| PubTypesEntry |
A single parsed pubtype. |
| Range |
An address range from the |
| RangesIter |
An iterator over an address range list. |
| RawLocationListIter |
A raw iterator over a location list. |
| RawRangesIter |
A raw iterator over an address range list. |
| RegisterRuleIter |
An unordered iterator for register rules. |
| StateMachine |
Executes a |
| TypeUnitHeader |
The header of a type unit's debugging information. |
| TypeUnitHeadersIter |
An iterator over the type-units of this |
| UninitializedUnwindContext |
Common context needed when evaluating the call frame unwinding information. |
| UnitOffset |
An offset into the current compilation or type unit. |
| UnwindTable |
The |
| UnwindTableRow |
A row in the virtual unwind table that describes how to find the values of the registers in the previous frame for a range of PC addresses. |
Enums
| AttributeValue |
The value of an attribute in a |
| BigEndian |
Big endian byte order. |
| CallFrameInstruction |
A parsed call frame instruction. |
| CfaRule |
The canonical frame address (CFA) recovery rules. |
| CieOrFde |
Either a |
| ColumnType |
The type of column that a row is referring to. |
| DieReference |
A reference to a DIE, either relative to the current CU or relative to the section. |
| Error |
An error that occurred when parsing. |
| EvaluationResult |
The state of an |
| Format |
Whether the format of a compilation unit is 32- or 64-bit. |
| LittleEndian |
Little endian byte order. |
| Location |
A single location of a piece of the result of a DWARF expression. |
| Opcode |
A parsed line number program opcode. |
| Operation |
A single decoded DWARF expression operation. |
| RegisterRule |
An entry in the abstract CFI table that describes how to find the value of a register. |
Constants
Traits
| Endianity |
A trait describing the endianity of some buffer. |
| LineNumberProgram |
A |
| Section |
A convenience trait for loading DWARF sections from object files. To be used like: |
| UnwindSection |
A section holding unwind information: either |
Type Definitions
| ArangeEntryIter |
An iterator over the aranges from a |
| DebugAranges |
The |
| DebugPubNames |
The |
| DebugPubTypes |
The |
| NativeEndian |
The native endianity for the target platform. |
| PubNamesEntryIter |
An iterator over the pubnames from a |
| PubTypesEntryIter |
An iterator over the pubtypes from a |
| Result |
The result of a parse. |