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.
Bring your own object file parser:
gimliisn't coupled to any platform or object file format. Use your own ELF parser on Linux or a Mach-O parser on OSX.
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 a compilation unit.
use 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()); // Grab the first compilation unit. let unit = debug_info.units().next() .expect("Should have at least one unit") .expect("and it should parse OK"); // Parse the abbreviations for this compilation unit. let abbrevs = unit.abbreviations(debug_abbrev) .expect("Should parse the abbreviations OK"); // Get a cursor for iterating over this unit's entries. let mut entries = unit.entries(&abbrevs); // Keep iterating entries while the cursor is not exhausted. while let Some((_, entry)) = entries.next_dfs().expect("Should parse next entry") { // 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.
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 `fallinle-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, ParseResult}; fn find_sum_of_address_range_lengths(aranges: DebugAranges<LittleEndian>) -> ParseResult<u64> { // `DebugAranges::items` returns a `FallibleIterator`! aranges.items() // `map` is provided by `FallibleIterator`! .map(|arange| arange.len()) // `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. |
| DebugAbbrev |
The |
| DebugAbbrevOffset |
An offset into the |
| DebugInfo |
The |
| DebugInfoOffset |
An offset into the |
| DebugLine |
The |
| DebugLineOffset |
An offset into the |
| DebugLocOffset |
An offset into the |
| DebugMacinfoOffset |
An offset into the |
| DebugStr |
The |
| DebugStrOffset |
An offset into the |
| DebugTypes |
The |
| DebugTypesOffset |
An offset into the |
| DebuggingInformationEntry |
A Debugging Information Entry (DIE). |
| DwAt | |
| DwChildren | |
| DwForm | |
| DwLne | |
| DwLns | |
| DwTag | |
| EndianBuf |
A |
| EntriesCursor |
A cursor into the Debugging Information Entries tree for a compilation unit. |
| FileEntry |
An entry in the |
| LineNumberProgramHeader |
A header for a line number program in the |
| LineNumberRow |
A row in the line number program's resulting matrix. |
| OpcodesIter |
An iterator yielding parsed opcodes. |
| PubNamesEntry |
A single parsed pubname. |
| PubTypesEntry |
A single parsed pubtype. |
| StateMachine |
Executes a |
| TypeUnitHeader |
The header of a type unit's debugging information. |
| TypeUnitHeadersIter |
An iterator over the type-units of this |
| UnitHeader |
The header of a compilation unit's debugging information. |
| UnitHeadersIter |
An iterator over the compilation- and partial-units of a section. |
| UnitOffset |
An offset into the current compilation or type unit. |
Enums
| AttributeValue |
The value of an attribute in a |
| BigEndian |
Big endian byte order. |
| ColumnType |
The type of column that a row is referring to. |
| Error |
An error that occurred when parsing. |
| Format |
Whether the format of a compilation unit is 32- or 64-bit. |
| LittleEndian |
Little endian byte order. |
| Opcode |
A parsed line number program opcode. |
Constants
Traits
| Endianity |
A trait describing the endianity of some buffer. |
Type Definitions
| ArangeEntryIter |
An iterator over the aranges from a .debug_aranges section. |
| DebugAranges |
The |
| DebugPubNames |
The |
| DebugPubTypes |
The |
| ParseResult |
The result of a parse. |
| PubNamesEntryIter |
An iterator over the pubnames from a .debug_pubnames section. |
| PubTypesEntryIter |
An iterator over the pubtypes from a .debug_pubtypes section. |