Struct gimli::read::Dwarf

pub struct Dwarf<R> {
    pub debug_abbrev: DebugAbbrev<R>,
    pub debug_addr: DebugAddr<R>,
    pub debug_info: DebugInfo<R>,
    pub debug_line: DebugLine<R>,
    pub debug_line_str: DebugLineStr<R>,
    pub debug_str: DebugStr<R>,
    pub debug_str_offsets: DebugStrOffsets<R>,
    pub debug_str_sup: DebugStr<R>,
    pub debug_types: DebugTypes<R>,
    pub locations: LocationLists<R>,
    pub ranges: RangeLists<R>,
}

All of the commonly used DWARF sections, and other common information.

Fields

debug_abbrev: DebugAbbrev<R>

The .debug_abbrev section.

debug_addr: DebugAddr<R>

The .debug_addr section.

debug_info: DebugInfo<R>

The .debug_info section.

debug_line: DebugLine<R>

The .debug_line section.

debug_line_str: DebugLineStr<R>

The .debug_line_str section.

debug_str: DebugStr<R>

The .debug_str section.

debug_str_offsets: DebugStrOffsets<R>

The .debug_str_offsets section.

debug_str_sup: DebugStr<R>

The .debug_str section for a supplementary object file.

debug_types: DebugTypes<R>

The .debug_types section.

locations: LocationLists<R>

The location lists in the .debug_loc and .debug_loclists sections.

ranges: RangeLists<R>

The range lists in the .debug_ranges and .debug_rnglists sections.

Implementations

impl<T> Dwarf<T>

pub fn load<F1, F2, E>(section: F1, sup: F2) -> Result<Self, E> where
    F1: FnMut(SectionId) -> Result<T, E>,
    F2: FnMut(SectionId) -> Result<T, E>, 

Try to load the DWARF sections using the given loader functions.

section loads a DWARF section from the main object file. sup loads a DWARF sections from the supplementary object file. These functions should return an empty section if the section does not exist.

The provided callback functions may either directly return a Reader instance (such as EndianSlice), or they may return some other type and then convert that type into a Reader using Dwarf::borrow.

pub fn borrow<'a, F, R>(&'a self, borrow: F) -> Dwarf<R> where
    F: FnMut(&'a T) -> R, 

Create a Dwarf structure that references the data in self.

This is useful when R implements Reader but T does not.

Example Usage

It can be useful to load DWARF sections into owned data structures, such as Vec. However, we do not implement the Reader trait for Vec, because it would be very inefficient, but this trait is required for all of the methods that parse the DWARF data. So we first load the DWARF sections into Vecs, and then use borrow to create Readers that reference the data.

// Read the DWARF sections into `Vec`s with whatever object loader you're using.
let owned_dwarf: gimli::Dwarf<Vec<u8>> = gimli::Dwarf::load(loader, sup_loader)?;
// Create references to the DWARF sections.
let dwarf = owned_dwarf.borrow(|section| {
    gimli::EndianSlice::new(&section, gimli::LittleEndian)
});

impl<R: Reader> Dwarf<R>

pub fn units(&self) -> CompilationUnitHeadersIter<R>

Iterate the compilation- and partial-unit headers in the .debug_info section.

Can be used with FallibleIterator.

pub fn unit(&self, header: CompilationUnitHeader<R>) -> Result<Unit<R>>

Construct a new Unit from the given compilation unit header.

pub fn type_units(&self) -> TypeUnitHeadersIter<R>

Iterate the type-unit headers in the .debug_types section.

Can be used with FallibleIterator.

pub fn type_unit(&self, header: TypeUnitHeader<R>) -> Result<Unit<R>>

Construct a new Unit from the given type unit header.

pub fn abbreviations(
    &self,
    unit: &CompilationUnitHeader<R>
) -> Result<Abbreviations>

Parse the abbreviations for a compilation unit.

pub fn type_abbreviations(
    &self,
    unit: &TypeUnitHeader<R>
) -> Result<Abbreviations>

Parse the abbreviations for a type unit.

pub fn string_offset(
    &self,
    unit: &Unit<R>,
    index: DebugStrOffsetsIndex<R::Offset>
) -> Result<DebugStrOffset<R::Offset>>

Return the string offset at the given index.

pub fn string(&self, offset: DebugStrOffset<R::Offset>) -> Result<R>

Return the string at the given offset in .debug_str.

pub fn line_string(&self, offset: DebugLineStrOffset<R::Offset>) -> Result<R>

Return the string at the given offset in .debug_line_str.

pub fn attr_string(&self, unit: &Unit<R>, attr: AttributeValue<R>) -> Result<R>

Return an attribute value as a string slice.

If the attribute value is one of:

• an inline DW_FORM_string string
• a DW_FORM_strp reference to an offset into the .debug_str section
• a DW_FORM_strp_sup reference to an offset into a supplementary object file
• a DW_FORM_line_strp reference to an offset into the .debug_line_str section
• a DW_FORM_strx index into the .debug_str_offsets entries for the unit

then return the attribute's string value. Returns an error if the attribute value does not have a string form, or if a string form has an invalid value.

pub fn address(
    &self,
    unit: &Unit<R>,
    index: DebugAddrIndex<R::Offset>
) -> Result<u64>

Return the address at the given index.

pub fn ranges_offset(
    &self,
    unit: &Unit<R>,
    index: DebugRngListsIndex<R::Offset>
) -> Result<RangeListsOffset<R::Offset>>

Return the range list offset at the given index.

pub fn ranges(
    &self,
    unit: &Unit<R>,
    offset: RangeListsOffset<R::Offset>
) -> Result<RngListIter<R>>

Iterate over the RangeListEntrys starting at the given offset.

pub fn attr_ranges_offset(
    &self,
    unit: &Unit<R>,
    attr: AttributeValue<R>
) -> Result<Option<RangeListsOffset<R::Offset>>>

Try to return an attribute value as a range list offset.

If the attribute value is one of:

• a DW_FORM_sec_offset reference to the .debug_ranges or .debug_rnglists sections
• a DW_FORM_rnglistx index into the .debug_rnglists entries for the unit

then return the range list offset of the range list. Returns None for other forms.

pub fn attr_ranges(
    &self,
    unit: &Unit<R>,
    attr: AttributeValue<R>
) -> Result<Option<RngListIter<R>>>

Try to return an attribute value as a range list entry iterator.

If the attribute value is one of:

• a DW_FORM_sec_offset reference to the .debug_ranges or .debug_rnglists sections
• a DW_FORM_rnglistx index into the .debug_rnglists entries for the unit

then return an iterator over the entries in the range list. Returns None for other forms.

pub fn die_ranges(
    &self,
    unit: &Unit<R>,
    entry: &DebuggingInformationEntry<'_, '_, R>
) -> Result<RangeIter<R>>

Return an iterator for the address ranges of a DebuggingInformationEntry.

This uses DW_AT_low_pc, DW_AT_high_pc and DW_AT_ranges.

pub fn unit_ranges(&self, unit: &Unit<R>) -> Result<RangeIter<R>>

Return an iterator for the address ranges of a Unit.

This uses DW_AT_low_pc, DW_AT_high_pc and DW_AT_ranges of the root DebuggingInformationEntry.

pub fn locations_offset(
    &self,
    unit: &Unit<R>,
    index: DebugLocListsIndex<R::Offset>
) -> Result<LocationListsOffset<R::Offset>>

Return the location list offset at the given index.

pub fn locations(
    &self,
    unit: &Unit<R>,
    offset: LocationListsOffset<R::Offset>
) -> Result<LocListIter<R>>

Iterate over the LocationListEntrys starting at the given offset.

pub fn attr_locations_offset(
    &self,
    unit: &Unit<R>,
    attr: AttributeValue<R>
) -> Result<Option<LocationListsOffset<R::Offset>>>

Try to return an attribute value as a location list offset.

If the attribute value is one of:

• a DW_FORM_sec_offset reference to the .debug_loc or .debug_loclists sections
• a DW_FORM_loclistx index into the .debug_loclists entries for the unit

then return the location list offset of the location list. Returns None for other forms.

pub fn attr_locations(
    &self,
    unit: &Unit<R>,
    attr: AttributeValue<R>
) -> Result<Option<LocListIter<R>>>

Try to return an attribute value as a location list entry iterator.

If the attribute value is one of:

• a DW_FORM_sec_offset reference to the .debug_loc or .debug_loclists sections
• a DW_FORM_loclistx index into the .debug_loclists entries for the unit

then return an iterator over the entries in the location list. Returns None for other forms.

pub fn lookup_offset_id(
    &self,
    id: ReaderOffsetId
) -> Option<(bool, SectionId, R::Offset)>

Call Reader::lookup_offset_id for each section, and return the first match.

The first element of the tuple is true for supplementary sections.

pub fn format_error(&self, err: Error) -> String

Returns a string representation of the given error.

This uses information from the DWARF sections to provide more information in some cases.

Trait Implementations

impl<R: Debug> Debug for Dwarf<R>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<R: Default> Default for Dwarf<R>

fn default() -> Dwarf<R>

Returns the "default value" for a type.