Struct gimli::read::Dwarf

source ·
pub struct Dwarf<R> {
Show 14 fields 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,
}
Expand description

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§

source§

impl<T> Dwarf<T>

source

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.

section may either directly return a Reader instance (such as EndianSlice), or it may return some other type and then convert that type into a Reader using Dwarf::borrow.

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

source

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.

source

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 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)
});
source

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

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

source§

impl<R: Reader> Dwarf<R>

source

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.

source

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

Iterate the unit headers in the .debug_info section.

Can be used with FallibleIterator.

source

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

Construct a new Unit from the given unit header.

source

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

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

Can be used with FallibleIterator.

source

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

Parse the abbreviations for a compilation unit.

source

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

Return the string offset at the given index.

source

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

Return the string at the given offset in .debug_str.

source

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

Return the string at the given offset in .debug_line_str.

source

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.

source

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

Return the address at the given index.

source

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.

source

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.

source

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.

source

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

Iterate over the RangeListEntrys starting at the given offset.

source

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

Iterate over the RawRngListEntryies starting at the given offset.

source

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.

source

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.

source

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.

source

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.

source

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.

source

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

Iterate over the LocationListEntrys starting at the given offset.

source

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.

source

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.

source

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.

source

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.

source

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.

source§

impl<R: Clone> Dwarf<R>

source

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§

source§

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

source§

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

Formats the value using the given formatter. Read more
source§

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

source§

fn default() -> Dwarf<R>

Returns the “default value” for a type. Read more

Auto Trait Implementations§

§

impl<R> RefUnwindSafe for Dwarf<R>
where R: RefUnwindSafe,

§

impl<R> Send for Dwarf<R>
where R: Send + Sync,

§

impl<R> Sync for Dwarf<R>
where R: Send + Sync,

§

impl<R> Unpin for Dwarf<R>
where R: Unpin,

§

impl<R> UnwindSafe for Dwarf<R>

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.