Crate gimli[−][src]
gimli
is a blazing fast library for consuming the
DWARF debugging format.
Example Usage
Print out all of the functions in the debuggee program:
extern crate gimli; // Read the .debug_info and .debug_abbrev sections with whatever object // loader you're using. let endian = gimli::LittleEndian; let debug_info = gimli::DebugInfo::new(read_debug_info(), endian); let debug_abbrev = gimli::DebugAbbrev::new(read_debug_abbrev(), endian); // Iterate over all compilation units. let mut iter = debug_info.units(); while let Some(unit) = try!(iter.next()) { // Parse the abbreviations for this compilation unit. let abbrevs = try!(unit.abbreviations(&debug_abbrev)); // Iterate over all of this compilation unit's entries. let mut entries = unit.entries(&abbrevs); while let Some((_, entry)) = try!(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:
-
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 (viaDW_AT_producer
) -
dwarf-validate
, a program to validate the integrity of some DWARF and its references between sections and ocmpilation units.
API Structure
-
Basic familiarity with DWARF is assumed.
-
Each section gets its own type. Consider these types the entry points to the library:
-
DebugAbbrev
: The.debug_abbrev
section. -
DebugAranges
: The.debug_aranges
section. -
DebugFrame
: The.debug_frame
section. -
DebugInfo
: The.debug_info
section. -
DebugLine
: The.debug_line
section. -
DebugLoc
: The.debug_loc
section. -
DebugPubNames
: The.debug_pubnames
section. -
DebugPubTypes
: The.debug_pubtypes
section. -
DebugRanges
: The.debug_ranges
section. -
DebugStr
: The.debug_str
section. -
DebugTypes
: The.debug_types
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 theunits
method for iterating over the compilation units defined within it. -
Offsets into a section are strongly typed: an offset into
.debug_info
is theDebugInfoOffset
type. It cannot be used to index into theDebugLine
type becauseDebugLine
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:
// Add the `fallible-iterator` crate. Don't forget to add it to your // `Cargo.toml`, too! extern crate fallible_iterator; extern crate gimli; // Use the `FallibleIterator` trait so its methods are in scope! use fallible_iterator::FallibleIterator; use gimli::{DebugAranges, EndianBuf, LittleEndian}; fn find_sum_of_address_range_lengths(aranges: DebugAranges<EndianBuf<LittleEndian>>) -> gimli::Result<u64> { // `DebugAranges::items` returns a `FallibleIterator`! aranges.items() // `map` is provided by `FallibleIterator`! .map(|arange| arange.length()) // `fold` is provided by `FallibleIterator`! .fold(0, |sum, len| sum + len) }
Cargo Features
Cargo features that can be enabled with gimli
:
-
std
: Enabled by default. Use thestd
library. Disabling this feature allows usinggimli
in embedded environments that do not have access tostd
. Note that even whenstd
is disabled,gimli
still requires an implementation of thealloc
crate, and you must enable thenightly
feature. -
alloc
: Nightly only. Enables usage of the unstable, nightly-only#![feature(alloc)]
Rust feature that allowsgimli
to use boxes and collection types in a#[no_std]
environment.
Modules
leb128 |
Read and write DWARF's "Little Endian Base 128" (LEB128) variable length integer encoding. |
Structs
Abbreviation |
An abbreviation describes the shape of a |
Abbreviations |
A set of type abbreviations. |
ArangeEntry |
A single parsed arange. |
ArangeEntryIter |
An iterator over the aranges from a |
Attribute |
An attribute in a |
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 |
BaseAddresses |
Optional base addresses for the relative |
BigEndian |
Big endian byte order. |
CallFrameInstructionIter |
A lazy iterator parsing call frame instructions. |
CfiEntriesIter |
An iterator over CIE and FDE entries in a |
CommonInformationEntry |
|
CompilationUnitHeader |
The header of a compilation unit's debugging information. |
CompilationUnitHeadersIter |
An iterator over the compilation- and partial-units of a section. |
CompleteLineNumberProgram |
A line number program that has previously been run to completion. |
DebugAbbrev |
The |
DebugAbbrevOffset |
An offset into the |
DebugAranges |
The |
DebugFrame |
|
DebugFrameOffset |
An offset into the |
DebugInfo |
The |
DebugInfoOffset |
An offset into the |
DebugLine |
The |
DebugLineOffset |
An offset into the |
DebugLoc |
The |
DebugLocLists |
The |
DebugMacinfoOffset |
An offset into the |
DebugPubNames |
The |
DebugPubTypes |
The |
DebugRanges |
The |
DebugRngLists |
The |
DebugStr |
The |
DebugStrOffset |
An offset into the |
DebugTypeSignature |
A type signature as used in the |
DebugTypes |
The |
DebugTypesOffset |
An offset into the |
DebuggingInformationEntry |
A Debugging Information Entry (DIE). |
DwAccess | |
DwAddr | |
DwAt | |
DwAte | |
DwCc | |
DwCfa | |
DwChildren | |
DwDefaulted | |
DwDs | |
DwDsc | |
DwEhPe | |
DwEnd | |
DwForm | |
DwId | |
DwIdx | |
DwInl | |
DwLang | |
DwLle | |
DwLnct | |
DwLne | |
DwLns | |
DwMacro | |
DwOp | |
DwOrd | |
DwRle | |
DwTag | |
DwUt | |
DwVirtuality | |
DwVis | |
EhFrame |
|
EhFrameHdr |
|
EhFrameOffset |
An offset into the |
EhHdrTable |
The CFI binary search table that is an optional part of the |
EndianReader |
An easy way to define a custom |
EndianSlice |
A |
EntriesCursor |
A cursor into the Debugging Information Entries tree for a compilation unit. |
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 |
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 |
FrameDescriptionEntry |
A |
IncompleteLineNumberProgram |
A line number program that has not been run to completion. |
InitializedUnwindContext |
An initialized unwinding context. |
LineNumberProgramHeader |
A header for a line number program in the |
LineNumberRow |
A row in the line number program's resulting matrix. |
LineNumberSequence |
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. |
LittleEndian |
Little endian byte order. |
LocListIter |
An iterator over a location list. |
LocationListEntry |
A location list entry from the |
LocationLists |
The DWARF data found in |
LocationListsOffset |
An offset into either the |
OpcodesIter |
An iterator yielding parsed opcodes. |
ParsedEhFrameHdr |
|
PartialFrameDescriptionEntry |
A partially parsed |
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 |
PubTypesEntry |
A single parsed pubtype. |
PubTypesEntryIter |
An iterator over the pubtypes from a |
Range |
An address range from the |
RangeLists |
The DWARF data found in |
RangeListsOffset |
An offset into either the |
RawLocListIter |
A raw iterator over a location list. |
RegisterRuleIter |
An unordered iterator for register rules. |
RngListIter |
An iterator over an address range list. |
StateMachine |
Executes a |
TypeUnitHeader |
The header of a type unit's debugging information. |
TypeUnitHeadersIter |
An iterator over the type-units of this |
UninitializedUnwindContext |
Common context needed when evaluating the call frame unwinding information. |
UnitOffset |
An offset into the current compilation or type unit. |
UnwindTable |
The |
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
AttributeValue |
The value of an attribute in a |
CallFrameInstruction |
A parsed call frame instruction. |
CfaRule |
The canonical frame address (CFA) recovery rules. |
CieOrFde |
Either a |
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 |
Format |
Whether the format of a compilation unit is 32- or 64-bit. |
Location |
A single location of a piece of the result of a DWARF expression. |
Opcode |
A parsed line number program opcode. |
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. |
RunTimeEndian |
Byte order that is selectable at runtime. |
Value |
The value of an entry on the DWARF stack. |
ValueType |
The type of an entry on the DWARF stack. |
Constants
Traits
CloneStableDeref |
An unsafe marker trait for types where clones deref to the same address. This has all the requirements of StableDeref, and additionally requires that after calling clone(), both the old and new value deref to the same address. For example, Rc and Arc implement CloneStableDeref, but Box and Vec do not. |
Endianity |
A trait describing the endianity of some buffer. |
LineNumberProgram |
A |
Reader |
A trait for reading the data from a DWARF section. |
ReaderOffset |
A trait for offsets with a DWARF section. |
Section |
A convenience trait for loading DWARF sections from object files. To be used like: |
StableDeref |
An unsafe marker trait for types that deref to a stable address, even when moved. For example, this is implemented by Box, Vec, Rc, Arc and String, among others. Even when a Box is moved, the underlying storage remains at a fixed location. |
UnwindOffset |
An offset into an |
UnwindSection |
A section holding unwind information: either |
Type Definitions
EndianArcSlice |
An atomically reference counted, thread-safe slice of bytes and associated endianity. |
EndianBuf |
[ Deprecated ]
|
EndianRcSlice |
A reference counted, non-thread-safe slice of bytes and associated endianity. |
NativeEndian |
The native endianity for the target platform. |
Result |
The result of a parse. |
UnwindResult |
Either a value of |