Struct Dwarf

pub struct Dwarf<R> {

    pub debug_abbrev: DebugAbbrev<R>,
    pub debug_addr: DebugAddr<R>,
    pub debug_aranges: DebugAranges<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_types: DebugTypes<R>,
    pub locations: LocationLists<R>,
    pub ranges: RangeLists<R>,
    pub file_type: DwarfFileType,
    pub sup: Option<Arc<Dwarf<R>>>,
    pub abbreviations_cache: AbbreviationsCache,
}

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_aranges: DebugAranges<R>

The .debug_aranges 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_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.

file_type: DwarfFileType

The type of this file.

sup: Option<Arc<Dwarf<R>>>

The DWARF sections for a supplementary object file.

abbreviations_cache: AbbreviationsCache

A cache of previously parsed abbreviations for units in this file.

Implementations

impl<T> Dwarf<T>

pub fn load<F, E>(section: F) -> Result<Self, E>

where F: FnMut(SectionId) -> Result<T, E>,

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

section loads a DWARF section from the object file. It should return an empty section if the section does not exist.

After loading, the user should set the file_type field and call load_sup if required.

pub fn load_sup<F, E>(&mut self, section: F) -> Result<(), E>

where F: FnMut(SectionId) -> Result<T, E>,

Load the DWARF sections from the supplementary object file.

section operates the same as for load.

Sets self.sup, replacing any previous value.

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

where F: FnMut(&'a T) -> R,

👎Deprecated: use DwarfSections::borrow instead

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 mut owned_dwarf: gimli::Dwarf<Vec<u8>> = gimli::Dwarf::load(loader)?;
owned_dwarf.load_sup(sup_loader)?;
// Create references to the DWARF sections.
let dwarf = owned_dwarf.borrow(|section| {
    gimli::EndianSlice::new(&section, gimli::LittleEndian)
});

pub fn set_sup(&mut self, sup: Dwarf<T>)

Store the DWARF sections for the supplementary object file.

pub fn sup(&self) -> Option<&Dwarf<T>>

Return a reference to the DWARF sections for the supplementary object file.

impl<R: Reader> Dwarf<R>

pub fn populate_abbreviations_cache( &mut self, strategy: AbbreviationsCacheStrategy, )

Parse abbreviations and store them in the cache.

This will iterate over the units in self.debug_info to determine the abbreviations offsets.

Errors during parsing abbreviations are also stored in the cache. Errors during iterating over the units are ignored.

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

Iterate the unit headers in the .debug_info section.

Can be used with FallibleIterator.

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

Construct a new Unit from the given unit header.

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

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

Can be used with FallibleIterator.

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

Parse the abbreviations for a compilation 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 sup_string(&self, offset: DebugStrOffset<R::Offset>) -> Result<R>

Return the string at the given offset in the .debug_str in the supplementary object file.

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 attr_address( &self, unit: &Unit<R>, attr: AttributeValue<R>, ) -> Result<Option<u64>>

Try to return an attribute value as an address.

If the attribute value is one of:

• a DW_FORM_addr
• a DW_FORM_addrx index into the .debug_addr entries for the unit

then return the address. Returns None for other forms.

pub fn ranges_offset_from_raw( &self, unit: &Unit<R>, offset: RawRangeListsOffset<R::Offset>, ) -> RangeListsOffset<R::Offset>

Return the range list offset for the given raw offset.

This handles adding DW_AT_GNU_ranges_base if required.

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 raw_ranges( &self, unit: &Unit<R>, offset: RangeListsOffset<R::Offset>, ) -> Result<RawRngListIter<R>>

Iterate over the RawRngListEntryies 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 raw_locations( &self, unit: &Unit<R>, offset: LocationListsOffset<R::Offset>, ) -> Result<RawLocListIter<R>>

Iterate over the raw 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.

impl<R: Clone> Dwarf<R>

pub fn make_dwo(&mut self, parent: &Dwarf<R>)

Assuming self was loaded from a .dwo, take the appropriate sections from parent (which contains the skeleton unit for this dwo) such as .debug_addr and merge them into this Dwarf.

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.