Module read

Read DWARF debugging information.

• Example Usage
• API Structure
• Using with FallibleIterator

Example Usage

Print out all of the functions in the debuggee program:

# fn example() -> Result<(), gimli::Error> {
# type R = gimli::EndianSlice<'static, gimli::LittleEndian>;
# let get_file_section_reader = |name| -> Result<R, gimli::Error> { unimplemented!() };
# let get_sup_file_section_reader = |name| -> Result<R, gimli::Error> { unimplemented!() };
// Read the DWARF sections with whatever object loader you're using.
// These closures should return a `Reader` instance (e.g. `EndianSlice`).
let loader = |section: gimli::SectionId| { get_file_section_reader(section.name()) };
let sup_loader = |section: gimli::SectionId| { get_sup_file_section_reader(section.name()) };
let mut dwarf = gimli::Dwarf::load(loader)?;
dwarf.load_sup(sup_loader)?;

// Iterate over all compilation units.
let mut iter = dwarf.units();
while let Some(header) = iter.next()? {
    // Parse the abbreviations and other information for this compilation unit.
    let unit = dwarf.unit(header)?;

    // Iterate over all of this compilation unit's entries.
    let mut entries = unit.entries();
    while let Some((_, entry)) = 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);
        }
    }
}
# unreachable!()
# }

Full example programs:

• A simple parser

• A dwarfdump clone

• An addr2line clone

• ddbug, a utility giving insight into code generation by making debugging information readable

• dwprod, a tiny utility to list the compilers used to create each compilation unit within a shared library or executable (via DW_AT_producer)

• dwarf-validate, a program to validate the integrity of some DWARF and its references between sections and compilation units.

API Structure

• Basic familiarity with DWARF is assumed.

• The Dwarf type contains the commonly used DWARF sections. It has methods that simplify access to debugging data that spans multiple sections. Use of this type is optional, but recommended.

• The DwarfPackage type contains the DWARF package (DWP) sections. It has methods to find a DWARF object (DWO) within the package.

• Each section gets its own type. Consider these types the entry points to the library:

  • DebugAbbrev: The .debug_abbrev section.

  • DebugAddr: The .debug_addr section.

  • DebugAranges: The .debug_aranges section.

  • DebugFrame: The .debug_frame section.

  • DebugInfo: The .debug_info section.

  • DebugLine: The .debug_line section.

  • DebugLineStr: The .debug_line_str section.

  • DebugLoc: The .debug_loc section.

  • DebugLocLists: The .debug_loclists section.

  • DebugPubNames: The .debug_pubnames section.

  • DebugPubTypes: The .debug_pubtypes section.

  • DebugRanges: The .debug_ranges section.

  • DebugRngLists: The .debug_rnglists section.

  • DebugStr: The .debug_str section.

  • DebugStrOffsets: The .debug_str_offsets section.

  • DebugTypes: The .debug_types section.

  • DebugCuIndex: The .debug_cu_index section.

  • DebugTuIndex: The .debug_tu_index section.

  • EhFrame: The .eh_frame section.

  • EhFrameHdr: The .eh_frame_hdr section.

• Each section type exposes methods for accessing the debugging data encoded in that section. For example, the DebugInfo struct has the units method for iterating over the compilation units defined within it.

• Offsets into a section are strongly typed: an offset into .debug_info is the DebugInfoOffset type. It cannot be used to index into the DebugLine type because DebugLine represents the .debug_line section. 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:

# #[cfg(feature = "fallible-iterator")]
# fn foo() {
// Use the `FallibleIterator` trait so its methods are in scope!
use fallible_iterator::FallibleIterator;
use gimli::{DebugAranges, EndianSlice, LittleEndian};

fn find_sum_of_address_range_lengths(aranges: DebugAranges<EndianSlice<LittleEndian>>)
    -> gimli::Result<u64>
{
    // `DebugAranges::headers` returns a `FallibleIterator`!
    aranges.headers()
        // `flat_map` is provided by `FallibleIterator`!
        .flat_map(|header| Ok(header.entries()))
        // `map` is provided by `FallibleIterator`!
        .map(|arange| Ok(arange.length()))
        // `fold` is provided by `FallibleIterator`!
        .fold(0, |sum, len| Ok(sum + len))
}
# }
# fn main() {}