Module gimli::write

Write DWARF debugging information.

API Structure

This module works by building up a representation of the debugging information in memory, and then writing it all at once. It supports two major use cases:

• Use the DwarfUnit type when writing DWARF for a single compilation unit.

• Use the Dwarf type when writing DWARF for multiple compilation units.

The module also supports reading in DWARF debugging information and writing it out again, possibly after modifying it. Create a read::Dwarf instance, and then use Dwarf::from to convert it to a writable instance.

Example Usage

Write a compilation unit containing only the top level DIE.

use gimli::write::{
    Address, AttributeValue, DwarfUnit, EndianVec, Error, Range, RangeList, Sections,
};

fn example() -> Result<(), Error> {
    // Choose the encoding parameters.
    let encoding = gimli::Encoding {
        format: gimli::Format::Dwarf32,
        version: 5,
        address_size: 8,
    };
    // Create a container for a single compilation unit.
    let mut dwarf = DwarfUnit::new(encoding);
    // Set a range attribute on the root DIE.
    let range_list = RangeList(vec![Range::StartLength {
        begin: Address::Constant(0x100),
        length: 42,
    }]);
    let range_list_id = dwarf.unit.ranges.add(range_list);
    let root = dwarf.unit.root();
    dwarf.unit.get_mut(root).set(
        gimli::DW_AT_ranges,
        AttributeValue::RangeListRef(range_list_id),
    );
    // Create a `Vec` for each DWARF section.
    let mut sections = Sections::new(EndianVec::new(gimli::LittleEndian));
    // Finally, write the DWARF data to the sections.
    dwarf.write(&mut sections)?;
    sections.for_each(|id, data| {
        // Here you can add the data to the output object file.
        Ok(())
    })
}

Structs

• Attribute
  An attribute in a DebuggingInformationEntry, consisting of a name and associated value.
• CieId
  An identifier for a CIE in a FrameTable.
• CommonInformationEntry
  A common information entry. This contains information that is shared between FDEs.
• DebugAbbrev
  A writable .debug_abbrev section.
• DebugFrame
  A writable .debug_frame section.
• DebugInfo
  A writable .debug_info section.
• DebugInfoOffsets
  The section offsets of all elements within a .debug_info section.
• DebugLine
  A writable .debug_line section.
• DebugLineStr
  A writable .debug_line_str section.
• DebugLineStrOffsets
  The section offsets of all strings within a .debug_line_str section.
• DebugLoc
  A writable .debug_loc section.
• DebugLocLists
  A writable .debug_loclists section.
• DebugRanges
  A writable .debug_ranges section.
• DebugRngLists
  A writable .debug_rnglists section.
• DebugStr
  A writable .debug_str section.
• DebugStrOffsets
  The section offsets of all strings within a .debug_str section.
• DebuggingInformationEntry
  A Debugging Information Entry (DIE).
• DirectoryId
  An identifier for a directory in a LineProgram.
• Dwarf
  Writable DWARF information for more than one unit.
• DwarfUnit
  Writable DWARF information for a single unit.
• EhFrame
  A writable .eh_frame section.
• EndianVec
  A Vec<u8> with endianity metadata.
• Expression
  The bytecode for a DWARF expression or location description.
• FileId
  An identifier for a file in a LineProgram.
• FileInfo
  Extra information for file in a LineProgram.
• FrameDescriptionEntry
  A frame description entry. There should be one FDE per function.
• FrameTable
  A table of frame description entries.
• InitialLengthOffset
  The offset at which an initial length should be written.
• LineProgram
  A line number program.
• LineRow
  A row in the line number table that corresponds to a machine instruction.
• LineStringId
  An identifier for a string in a LineStringTable.
• LineStringTable
  A table of strings that will be stored in a .debug_line_str section.
• LocationList
  A locations list that will be stored in a .debug_loc or .debug_loclists section.
• LocationListId
  An identifier for a location list in a LocationListTable.
• LocationListOffsets
  The section offsets of a series of location lists within the .debug_loc or .debug_loclists sections.
• LocationListTable
  A table of location lists that will be stored in a .debug_loc or .debug_loclists section.
• RangeList
  A range list that will be stored in a .debug_ranges or .debug_rnglists section.
• RangeListId
  An identifier for a range list in a RangeListTable.
• RangeListOffsets
  The section offsets of a series of range lists within the .debug_ranges or .debug_rnglists sections.
• RangeListTable
  A table of range lists that will be stored in a .debug_ranges or .debug_rnglists section.
• Relocation
  A relocation to be applied to a section.
• Sections
  All of the writable DWARF sections.
• StringId
  An identifier for a string in a StringTable.
• StringTable
  A table of strings that will be stored in a .debug_str section.
• Unit
  A unit’s debugging information.
• UnitEntryId
  An identifier for an entry in a Unit.
• UnitId
  An identifier for a unit in a UnitTable.
• UnitTable
  A table of units that will be stored in the .debug_info section.

Enums

• Address
  An address.
• AttributeValue
  The value of an attribute in a DebuggingInformationEntry.
• CallFrameInstruction
  An instruction in a frame description entry.
• ConvertError
  An error that occurred when converting a read value into a write value.
• Error
  An error that occurred when writing.
• LineString
  A string value for use in defining paths in line number programs.
• Location
  A single location.
• Range
  A single range.
• Reference
  A reference to a .debug_info entry.
• RelocationTarget
  The target of a relocation.

Traits

• RelocateWriter
  A Writer which also records relocations.
• Section
  Functionality common to all writable DWARF sections.
• Writer
  A trait for writing the data to a DWARF section.

Type Aliases

• ConvertResult
  The result of a conversion.
• Result
  The result of a write.