Module gimli::read

Read DWARF debugging information.

• Example Usage
• API Structure
• Using with FallibleIterator

Example Usage

Print out all of the functions in the debuggee program:

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

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:

// 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))
}

Structs

• Abbreviation
  An abbreviation describes the shape of a DebuggingInformationEntry’s type: its code, tag type, whether it has children, and its set of attributes.
• Abbreviations
  A set of type abbreviations.
• AbbreviationsCache
  A cache of previously parsed Abbreviations.
• ArangeEntry
  A single parsed arange.
• ArangeEntryIter
  An iterator over the aranges from a .debug_aranges section.
• ArangeHeader
  A header for a set of entries in the .debug_arange section.
• ArangeHeaderIter
  An iterator over the headers of a .debug_aranges section.
• Attribute
  An attribute in a DebuggingInformationEntry, consisting of a name and associated value.
• 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.
• Augmentation
  We support the z-style augmentation defined by .eh_frame.
• BaseAddresses
  Optional base addresses for the relative DW_EH_PE_* encoded pointers.
• CallFrameInstructionIter
  A lazy iterator parsing call frame instructions.
• CfiEntriesIter
  An iterator over CIE and FDE entries in a .debug_frame or .eh_frame section.
• CommonInformationEntry

  A Common Information Entry holds information that is shared among many Frame Description Entries. There is at least one CIE in every non-empty .debug_frame section.

• CompleteLineProgram
  A line number program that has previously been run to completion.
• DebugAbbrev
  The DebugAbbrev struct represents the abbreviations describing DebuggingInformationEntrys’ attribute names and forms found in the .debug_abbrev section.
• DebugAddr
  The raw contents of the .debug_addr section.
• DebugAranges
  The DebugAranges struct represents the DWARF address range information found in the .debug_aranges section.
• DebugCuIndex
  The data in the .debug_cu_index section of a .dwp file.
• DebugFrame
  DebugFrame contains the .debug_frame section’s frame unwinding information required to unwind to and recover registers from older frames on the stack. For example, this is useful for a debugger that wants to print locals in a backtrace.
• DebugInfo
  The DebugInfo struct represents the DWARF debugging information found in the .debug_info section.
• DebugInfoUnitHeadersIter
  An iterator over the units of a .debug_info section.
• DebugLine
  The DebugLine struct contains the source location to instruction mapping found in the .debug_line section.
• DebugLineStr
  The DebugLineStr struct represents the DWARF strings found in the .debug_line_str section.
• DebugLoc
  The raw contents of the .debug_loc section.
• DebugLocLists
  The DebugLocLists struct represents the DWARF data found in the .debug_loclists section.
• DebugPubNames
  The DebugPubNames struct represents the DWARF public names information found in the .debug_pubnames section.
• DebugPubTypes
  The DebugPubTypes struct represents the DWARF public types information found in the .debug_info section.
• DebugRanges
  The raw contents of the .debug_ranges section.
• DebugRngLists
  The DebugRngLists struct represents the contents of the .debug_rnglists section.
• DebugStr
  The DebugStr struct represents the DWARF strings found in the .debug_str section.
• DebugStrOffsets
  The raw contents of the .debug_str_offsets section.
• DebugTuIndex
  The data in the .debug_tu_index section of a .dwp file.
• DebugTypes
  The DebugTypes struct represents the DWARF type information found in the .debug_types section.
• DebugTypesUnitHeadersIter
  An iterator over the type-units of this .debug_types section.
• DebuggingInformationEntry
  A Debugging Information Entry (DIE).
• Dwarf
  All of the commonly used DWARF sections, and other common information.
• DwarfPackage
  The sections from a .dwp file, with parsed indices.
• DwarfPackageSections
  The sections from a .dwp file.
• DwarfSections
  All of the commonly used DWARF sections.
• EhFrame
  EhFrame contains the frame unwinding information needed during exception handling found in the .eh_frame section.
• EhFrameHdr
  EhFrameHdr contains the information about the .eh_frame_hdr section.
• EhHdrTable
  The CFI binary search table that is an optional part of the .eh_frame_hdr section.
• EhHdrTableIter
  An iterator for .eh_frame_hdr section’s binary search table.
• EndianSlice
  A &[u8] slice with endianity metadata.
• EntriesCursor
  A cursor into the Debugging Information Entries tree for a compilation unit.
• EntriesRaw
  A raw reader of the data that defines the Debugging Information Entries.
• EntriesTree
  The state information for a tree view of the Debugging Information Entries.
• EntriesTreeIter
  An iterator that allows traversal of the children of an EntriesTreeNode.
• EntriesTreeNode
  A node in the Debugging Information Entry tree.
• Evaluation
  A DWARF expression evaluator.
• Expression
  The bytecode for a DWARF expression or location description.
• FileEntry
  An entry in the LineProgramHeader’s file_names set.
• FileEntryFormat
  The format of a component of an include directory or file name entry.
• FrameDescriptionEntry
  A FrameDescriptionEntry is a set of CFA instructions for an address range.
• IncompleteLineProgram
  A line number program that has not been run to completion.
• LineInstructions
  An iterator yielding parsed instructions.
• LineProgramHeader
  A header for a line number program in the .debug_line section, as defined in section 6.2.4 of the standard.
• LineRow
  A row in the line number program’s resulting matrix.
• LineRows
  Executes a LineProgram to iterate over the rows in the matrix of line number information.
• LineSequence
  A sequence within a line number program. A sequence, as defined in section 6.2.5 of the standard, is a linear subset of a line number program within which addresses are monotonically increasing.
• LocListIter
  An iterator over a location list.
• LocationListEntry
  A location list entry from the .debug_loc or .debug_loclists sections.
• LocationLists
  The DWARF data found in .debug_loc and .debug_loclists sections.
• OperationIter
  An iterator for the operations in an expression.
• ParsedEhFrameHdr
  ParsedEhFrameHdr contains the parsed information from the .eh_frame_hdr section.
• PartialFrameDescriptionEntry
  A partially parsed FrameDescriptionEntry.
• Piece
  The description of a single piece of the result of a DWARF expression.
• PubNamesEntry
  A single parsed pubname.
• PubNamesEntryIter
  An iterator over the pubnames from a .debug_pubnames section.
• PubTypesEntry
  A single parsed pubtype.
• PubTypesEntryIter
  An iterator over the pubtypes from a .debug_pubtypes section.
• Range
  An address range from the .debug_ranges, .debug_rnglists, or .debug_aranges sections.
• RangeIter
  An iterator for the address ranges of a DebuggingInformationEntry.
• RangeLists
  The DWARF data found in .debug_ranges and .debug_rnglists sections.
• RawLocListIter
  A raw iterator over a location list.
• RawRngListIter
  A raw iterator over an address range list.
• ReaderOffsetId
  An identifier for an offset within a section reader.
• RegisterRuleIter
  An unordered iterator for register rules.
• RelocateReader
  A Reader which applies relocations to addresses and offsets.
• RngListIter
  An iterator over an address range list.
• SectionBaseAddresses
  Optional base addresses for the relative DW_EH_PE_* encoded pointers in a particular section.
• StoreOnHeap
  Indicates that storage should be allocated on heap.
• Unit
  All of the commonly used information for a unit in the .debug_info or .debug_types sections.
• UnitHeader
  The common fields for the headers of compilation units and type units.
• UnitIndex
  The partially parsed index from a DebugCuIndex or DebugTuIndex.
• UnitIndexSection
  Information about a unit’s contribution to a section in a .dwp file.
• UnitIndexSectionIterator
  An iterator over the section offsets and sizes for a row in a UnitIndex.
• UnitOffset
  An offset into the current compilation or type unit.
• UnwindContext
  Common context needed when evaluating the call frame unwinding information.
• UnwindExpression
  The location of a DWARF expression within an unwind section.
• UnwindTable
  The UnwindTable iteratively evaluates a FrameDescriptionEntry’s CallFrameInstruction program, yielding the each row one at a time.
• UnwindTableRow
  A row in the virtual unwind table that describes how to find the values of the registers in the previous frame for a range of PC addresses.

Enums

• AbbreviationsCacheStrategy
  The strategy to use for caching abbreviations.
• AttributeValue
  The value of an attribute in a DebuggingInformationEntry.
• CallFrameInstruction
  A parsed call frame instruction.
• CfaRule
  The canonical frame address (CFA) recovery rules.
• CieOrFde
  Either a CommonInformationEntry (CIE) or a FrameDescriptionEntry (FDE).
• ColumnType
  The type of column that a row is referring to.
• DieReference
  A reference to a DIE, either relative to the current CU or relative to the section.
• Error
  An error that occurred when parsing.
• EvaluationResult
  The state of an Evaluation after evaluating a DWARF expression. The evaluation is either Complete, or it requires more data to continue, as described by the variant.
• LineInstruction
  A parsed line number program instruction.
• Location
  A single location of a piece of the result of a DWARF expression.
• Operation
  A single decoded DWARF expression operation.
• Pointer
  A decoded pointer.
• RawLocListEntry
  A raw entry in .debug_loclists.
• RawRngListEntry
  A raw entry in .debug_rnglists
• RegisterRule
  An entry in the abstract CFI table that describes how to find the value of a register.
• UnitType
  This enum specifies the type of the unit and any type specific data carried in the header (e.g. the type signature/type offset of a type unit).
• Value
  The value of an entry on the DWARF stack.
• ValueType
  The type of an entry on the DWARF stack.

Traits

• ArrayLike
  Marker trait for types that can be used as backing storage when a growable array type is needed.
• EvaluationStorage
  Specification of what storage should be used for Evaluation.
• LineProgram
  A LineProgram provides access to a LineProgramHeader and a way to add files to the files table if necessary. Gimli consumers should never need to use or see this trait.
• Reader
  A trait for reading the data from a DWARF section.
• ReaderOffset
  A trait for offsets with a DWARF section.
• Relocate
  Trait for relocating addresses and offsets while reading a section.
• Section
  A convenience trait for loading DWARF sections from object files. To be used like:
• UnwindContextStorage
  Specification of what storage should be used for UnwindContext.
• UnwindOffset
  An offset into an UnwindSection.
• UnwindSection
  A section holding unwind information: either .debug_frame or .eh_frame. See DebugFrame and EhFrame respectively.

Type Aliases

• CompleteLineNumberProgramDeprecated
  Deprecated. CompleteLineNumberProgram has been renamed to CompleteLineProgram.
• EndianBufDeprecated
  EndianBuf has been renamed to EndianSlice. For ease of upgrading across gimli versions, we export this type alias.
• IncompleteLineNumberProgramDeprecated
  Deprecated. IncompleteLineNumberProgram has been renamed to IncompleteLineProgram.
• LineNumberProgramDeprecated
  Deprecated. LineNumberProgram has been renamed to LineProgram.
• LineNumberProgramHeaderDeprecated
  Deprecated. LineNumberProgramHeader has been renamed to LineProgramHeader.
• LineNumberRowDeprecated
  Deprecated. LineNumberRow has been renamed to LineRow.
• LineNumberSequenceDeprecated
  Deprecated. LineNumberSequence has been renamed to LineSequence.
• OpcodeDeprecated
  Deprecated. Opcode has been renamed to LineInstruction.
• OpcodesIterDeprecated
  Deprecated. OpcodesIter has been renamed to LineInstructions.
• Result
  The result of a parse.
• StateMachineDeprecated
  Deprecated. StateMachine has been renamed to LineRows.