pdb Rust Library

A FrameTable contains FrameData entries that describe the stack layout of functions in a PDB. These entries are ordered by their internal PDB Relative Virtual Address (PdbInternalRva).

Key behaviors:

• Multiple Entries: A single function might be described by multiple entries; the entry where is_function_start is true marks the beginning of the function.
• Missing Data: Not all functions have frame data. If no data is present, functions are assumed to have normal stack frames.
• Address Conversion: FrameData uses PdbInternalRva. To convert these to actual Rva values, use PdbInternalRva::to_rva.

To retrieve information for a specific function, use iter_at_rva(rva). This returns an iterator starting at the entry covering that RVA (or the closest preceding element).

# use pdb::{PDB, Rva, FallibleIterator};
#
# fn test() -> pdb::Result<()> {
# let source = std::fs::File::open("fixtures/self/foo.pdb")?;
# let mut pdb = PDB::open(source)?;
#
// Read the frame table once and reuse it
let frame_table = pdb.frame_table()?;
let mut frames = frame_table.iter();

// Iterate frame data in RVA order
while let Some(frame) = frames.next()? {
    println!("{:#?}", frame);
}
# Ok(())
# }

The SymbolData<'t> enum is the primary way to interact with parsed PDB symbols. It contains the structured representation of various symbol types found in the stream.

Common variants include:

• Procedure(ProcedureSymbol<'t>): Represents functions or methods.
• Data(DataSymbol<'t>): Represents static data like global variables.
• Public(PublicSymbol<'t>): Represents public symbols with mangled names.
• Constant(ConstantSymbol<'t>): Represents constant values.
• UserDefinedType(UserDefinedTypeSymbol<'t>): Represents UDTs.
• InlineSite(InlineSiteSymbol<'t>): Represents the callsite of an inlined function.
• ScopeEnd: A marker for the end of a scope.

You can use the .name() method on any SymbolData variant to attempt to retrieve a RawString<'t> name if the symbol type supports it.

#[non_exhaustive]
#[derive(Clone, Debug, Eq, PartialEq)]
pub enum SymbolData<'t> {
    ScopeEnd,
    ObjName(ObjNameSymbol<'t>),
    RegisterVariable(RegisterVariableSymbol<'t>),
    Constant(ConstantSymbol<'t>),
    UserDefinedType(UserDefinedTypeSymbol<'t>),
    MultiRegisterVariable(MultiRegisterVariableSymbol<'t>),
    Data(DataSymbol<'t>),
    Public(PublicSymbol<'t>),
    Procedure(ProcedureSymbol<'t>),
    ThreadStorage(ThreadStorageSymbol<'t>),
    CompileFlags(CompileFlagsSymbol<'t>),
    UsingNamespace(UsingNamespaceSymbol<'t>),
    ProcedureReference(ProcedureReferenceSymbol<'t>),
    DataReference(DataReferenceSymbol<'t>),
    AnnotationReference(AnnotationReferenceSymbol<'t>),
    Trampoline(TrampolineSymbol),
    Export(ExportSymbol<'t>),
    Local(LocalSymbol<'t>),
    BuildInfo(BuildInfoSymbol),
    InlineSite(InlineSiteSymbol<'t>),
    InlineSiteEnd,
    ProcedureEnd,
    Label(LabelSymbol<'t>),
    Block(BlockSymbol<'t>),
    RegisterRelative(RegisterRelativeSymbol<'t>),
    Thunk(ThunkSymbol<'t>),
    SeparatedCode(SeparatedCodeSymbol),
}

An AddressMap is a helper used to translate between different types of addresses and offsets in a PDB and its corresponding PE binary. This is necessary because some Windows binaries are optimized (reordered) for paging reduction, meaning the addresses used in the PDB (internal) may not match the actual addresses in the executable (RVA).

The AddressMap handles four primary address types:

1. Rva: A Relative Virtual Address in the actual binary. These correspond to instruction pointers in stack traces and symbol addresses used by debuggers.
2. PdbInternalRva: An RVA as it would have appeared in the binary before optimization. These are used within the PDB and must be converted to an actual Rva to be useful for debugging.
3. SectionOffset: An offset into a section of the actual binary. It uses a 1-based section index (where 0 is a null pointer).
4. PdbInternalSectionOffset: An offset into a section of the original (unoptimized) binary, used throughout the PDB.

To use it, obtain an instance via PDB::address_map(). Once obtained, you can call conversion methods (like .to_rva() or .to_internal_offset()) on any of these types, passing the AddressMap as the translator.

// Compute the address map once and reuse it
let address_map = pdb.address_map()?;

// Example: Converting a symbol offset to an RVA
match pubsym.offset.to_rva(&address_map) {
    Some(rva) => println!("symbol is at {}", rva),
    None => println!("symbol refers to eliminated code"),
}

The SymbolTable provides access to the names, locations, and metadata of functions, data, and types within a PDB file. You can traverse the table sequentially using an iterator. Because the table is structured as a series of records with varying lengths, iteration is similar to traversing a linked list.

To find specific information, you can iterate through all symbols and use symbol.parse() to convert the raw data into structured SymbolData variants (like Public, Procedure, or Data).

# use pdb::FallibleIterator;
# fn test() -> pdb::Result<usize> {
# let file = std::fs::File::open("fixtures/self/foo.pdb")?;
# let mut pdb = pdb::PDB::open(file)?;

let symbol_table = pdb.global_symbols()?;
let address_map = pdb.address_map()?;

let mut count: usize = 0;
let mut symbols = symbol_table.iter();
while let Some(symbol) = symbols.next()? {
    match symbol.parse() {
        Ok(pdb::SymbolData::Public(data)) if data.function => {
            // Found a function location
            let rva = data.offset.to_rva(&address_map).unwrap_or_default();
            println!("{} is {}", rva, data.name);
            count += 1;
        }
        _ => {}
    }
}
# Ok(count)
# }