Pro.PDB — API for parsing Microsoft debug files

Overview

The Pro.PDB module contains the API for parsing Microsoft debug files.

Enumerating Symbols

The following code example demonstrates how to enumerate symbols in a PDB file:

from Pro.Core import *
from Pro.PDB import *

def parsePDBSymbols(fname):
    c = createContainerFromFile(fname)
    if c.isNull():
        return
    obj = PDBObject()
    if not obj.Load(c) or not obj.ParseRootDirectory():
        return
    dbi = obj.GetStreamObject(PDB_STREAM_ID_DBI)
    class visitor(PDBSymbolVisitor):
        def __init__(self):
            super().__init__()
        def visit(self, rtype):
            print("address:", hex(self.getAddress()))
            print("name:", self.getName())
            print()
            return True
    obj.VisitSymbols(dbi, visitor())

Module API

Pro.PDB module API.

Attributes:

DBI_SUBSTREAM_ID_EC_SUBSTREAM	Identifier for the Edit and Continue (EC) substream in the DBI stream.
DBI_SUBSTREAM_ID_MODULE_INFO	Identifier for the Module Info substream in the DBI stream.
DBI_SUBSTREAM_ID_OPTIONAL_DBG_HEADER	Identifier for the Optional Debug Header substream in the DBI stream.
DBI_SUBSTREAM_ID_SECTION_CONTRIBUTION	Identifier for the Section Contribution substream in the DBI stream.
DBI_SUBSTREAM_ID_SECTION_MAP	Identifier for the Section Map substream in the DBI stream.
DBI_SUBSTREAM_ID_SOURCE_INFO	Identifier for the Source Info substream in the DBI stream.
DBI_SUBSTREAM_ID_TYPE_SERVER_MAP	Identifier for the Type Server Map substream in the DBI stream.
PDBError_InvalidStreams	Error code indicating invalid streams in the PDB file.
PDBFormat_2	Represents PDB format version 2.
PDBFormat_7	Represents PDB format version 7.
PDB_STREAM_ID_DBI	Stream ID for the DBI stream in the PDB file.
PDB_STREAM_ID_INVALID	Invalid stream ID, indicates an error or non-existent stream.
PDB_STREAM_ID_PDB	Stream ID for the PDB stream in the PDB file.
PDB_STREAM_ID_TPI	Stream ID for the TPI (Type Info) stream in the PDB file.

Classes:

PDBObject()	Represents a PDB (Program Database) file object.
PDBSymbolVisitor()	Interface for visiting symbols within a PDB file.
PDBTypeContext()	Provides context for parsing and interpreting type information from the TPI stream.

DBI_SUBSTREAM_ID_EC_SUBSTREAM: Final[int]

Identifier for the Edit and Continue (EC) substream in the DBI stream.

See also PDBObject.GetDBISubStreamRanges().

DBI_SUBSTREAM_ID_MODULE_INFO: Final[int]

Identifier for the Module Info substream in the DBI stream.

See also PDBObject.GetDBISubStreamRanges().

DBI_SUBSTREAM_ID_OPTIONAL_DBG_HEADER: Final[int]

Identifier for the Optional Debug Header substream in the DBI stream.

See also PDBObject.GetDBISubStreamRanges().

DBI_SUBSTREAM_ID_SECTION_CONTRIBUTION: Final[int]

Identifier for the Section Contribution substream in the DBI stream.

See also PDBObject.GetDBISubStreamRanges().

DBI_SUBSTREAM_ID_SECTION_MAP: Final[int]

Identifier for the Section Map substream in the DBI stream.

See also PDBObject.GetDBISubStreamRanges().

DBI_SUBSTREAM_ID_SOURCE_INFO: Final[int]

Identifier for the Source Info substream in the DBI stream.

See also PDBObject.GetDBISubStreamRanges().

DBI_SUBSTREAM_ID_TYPE_SERVER_MAP: Final[int]

Identifier for the Type Server Map substream in the DBI stream.

See also PDBObject.GetDBISubStreamRanges().

PDBError_InvalidStreams: Final[int]

Error code indicating invalid streams in the PDB file.

See also PDBObject.ParseRootDirectory().

PDBFormat_2: Final[int]

Represents PDB format version 2.

See also PDBObject.GetFormat().

PDBFormat_7: Final[int]

Represents PDB format version 7.

See also PDBObject.GetFormat().

class PDBObject

Bases: Pro.Core.CFFObject

Represents a PDB (Program Database) file object.

Methods:

CreateTypeContext(tpiobj)	Creates a type context for parsing type information from the TPI stream.
DBIHeader(dbiobj)	Retrieves the header structure of the DBI stream.
DumpLeaf(out, tpiobj, offs)	Dumps a type leaf from the TPI stream to the provided text stream.
GetDBISubStreamRanges(dbiobj)	Retrieves the ranges of the substreams within the DBI stream.
GetFormat()	Retrieves the PDB format version.
GetLeafDescription(tpiobj, lh_or_offs)	Retrieves a textual description of a type leaf from the TPI stream.
GetPDBAssociationInfo([pdbhdr, dbihdr])	Retrieves information about the association between the PDB file and the executable or object files it corresponds to.
GetStreamCount()	Retrieves the number of streams in the PDB file.
GetStreamData(i)	Retrieves the data of the specified stream.
GetStreamObject(i)	Retrieves the stream object at the specified index.
Header()	Retrieves the header of the PDB file.
LeafHeader(tpiobj, offs)	Retrieves the leaf header at the specified offset in the TPI stream.
LeafTypeName(leaf)	Retrieves the name of the leaf type corresponding to the given leaf code.
MethodValue(tpiobj, offs, mprop)	Retrieves the method value for a given method property in a method list.
OffsetValue(tpiobj, offs)	Retrieves an offset value from the TPI stream at the specified position.
OffsetValuePad(tpiobj, offs)	Retrieves an offset value from the TPI stream with padding, at the specified position.
OptionalDbgHeader(dbiobj_or_obj[, offset])	Retrieves the optional debug header from the DBI stream.
PDBHeader(pdbobj)	Retrieves the PDB header from the PDB stream.
ParseRootDirectory()	Parses the root directory of the PDB file.
RecordName(tpiobj, offs)	Retrieves the record name from the TPI stream at the specified offset.
RecordValue(tpiobj, offs)	Retrieves the record value from the TPI stream at the specified offset.
RootDirectoryData()	Retrieves the data of the root directory of the PDB file.
SectionHeaders(obj)	Retrieves the section headers from the given object.
TPIHeader(tpiobj)	Retrieves the header of the TPI stream.
TPITypeForwards(tpiobj, tpioffs)	Retrieves the type forward hash from the TPI stream.
TPITypeOffsets(tpiobj)	Retrieves the list of type offsets from the TPI stream.
VisitSymbols(dbiobj, visitor)	Visits symbols in the PDB file using the provided symbol visitor.

CreateTypeContext(tpiobj: Pro.Core.CFFObject) → Pro.PDB.PDBTypeContext

Creates a type context for parsing type information from the TPI stream.

Parameters

tpiobj (CFFObject) – The TPI stream object obtained from the PDB file.

Returns

Returns a new PDBTypeContext for parsing type information.

Return type

PDBTypeContext

See also GetStreamObject().

DBIHeader(dbiobj: Pro.Core.CFFObject) → Pro.Core.CFFStruct

Retrieves the header structure of the DBI stream.

Parameters

dbiobj (CFFObject) – The DBI stream object obtained from the PDB file.

Returns

Returns the DBI header as a CFFStruct.

Return type

CFFStruct

See also GetStreamObject().

DumpLeaf(out: Pro.Core.NTTextStream, tpiobj: Pro.Core.CFFObject, offs: int) → None

Dumps a type leaf from the TPI stream to the provided text stream.

Parameters

• out (NTTextStream) – The text stream to output the leaf information.

• tpiobj (CFFObject) – The TPI stream object containing the type leaf.

• offs (int) – The offset within the TPI stream where the leaf starts.

See also LeafHeader().

GetDBISubStreamRanges(dbiobj: Pro.Core.CFFObject) → Pro.Core.NTOffsetRangeList

Retrieves the ranges of the substreams within the DBI stream.

Parameters

dbiobj (CFFObject) – The DBI stream object from which to get the substream ranges.

Returns

Returns a list of offset ranges for each substream in the DBI stream.

Return type

NTOffsetRangeList

See also DBI_SUBSTREAM_ID_MODULE_INFO, DBI_SUBSTREAM_ID_SECTION_CONTRIBUTION.

GetFormat() → int

Retrieves the PDB format version.

Returns

Returns the format version, either PDBFormat_2 or PDBFormat_7.

Return type

int

GetLeafDescription(tpiobj: Pro.Core.CFFObject, lh_or_offs: Union[Pro.Core.CFFStruct, int]) → str

Retrieves a textual description of a type leaf from the TPI stream.

Parameters

• tpiobj (CFFObject) – The TPI stream object containing the type leaf.

• lh_or_offs (Union[CFFStruct, int]) – The leaf header or the offset within the TPI stream.

Returns

Returns a string description of the type leaf.

Return type

str

See also LeafHeader().

GetPDBAssociationInfo(pdbhdr: Optional[Pro.Core.CFFStruct] = None, dbihdr: Optional[Pro.Core.CFFStruct] = None) → Pro.Core.PDBAssociationInfo

Retrieves information about the association between the PDB file and the executable or object files it corresponds to.

Parameters

• pdbhdr (Optional[CFFStruct]) – Optional PDB header structure.

• dbihdr (Optional[CFFStruct]) – Optional DBI header structure.

Returns

Returns a PDBAssociationInfo object containing association information.

Return type

PDBAssociationInfo

GetStreamCount() → int

Retrieves the number of streams in the PDB file.

Returns

Returns the total number of streams.

Return type

int

See also GetStreamObject().

GetStreamData(i: int) → Pro.Core.NTContainer

Retrieves the data of the specified stream.

Parameters

i (int) – The index of the stream to retrieve.

Returns

Returns the stream data as an NTContainer.

Return type

NTContainer

See also GetStreamCount().

GetStreamObject(i: int) → Pro.Core.CFFObject

Retrieves the stream object at the specified index.

Parameters

i (int) – The index of the stream to retrieve.

Returns

Returns the stream as a CFFObject.

Return type

CFFObject

See also GetStreamCount().

Header() → Pro.Core.CFFStruct

Retrieves the header of the PDB file.

Returns

Returns the PDB header as a CFFStruct.

Return type

CFFStruct

LeafHeader(tpiobj: Pro.Core.CFFObject, offs: int) → Pro.Core.CFFStruct

Retrieves the leaf header at the specified offset in the TPI stream.

Parameters

• tpiobj (CFFObject) – The TPI stream object.

• offs (int) – The offset within the TPI stream.

Returns

Returns the leaf header as a CFFStruct.

Return type

CFFStruct

See also DumpLeaf().

LeafTypeName(leaf: int) → str

Retrieves the name of the leaf type corresponding to the given leaf code.

Parameters

leaf (int) – The leaf code.

Returns

Returns the name of the leaf type.

Return type

str

MethodValue(tpiobj: Pro.Core.CFFObject, offs: int, mprop: int) → int

Retrieves the method value for a given method property in a method list.

Parameters

• tpiobj (CFFObject) – The TPI stream object.

• offs (int) – The offset within the TPI stream where the method list starts.

• mprop (int) – The method property.

Returns

Returns the method value.

Return type

int

OffsetValue(tpiobj: Pro.Core.CFFObject, offs: int) → int

Retrieves an offset value from the TPI stream at the specified position.

Parameters

• tpiobj (CFFObject) – The TPI stream object.

• offs (int) – The offset within the TPI stream.

Returns

Returns the offset value.

Return type

int

OffsetValuePad(tpiobj: Pro.Core.CFFObject, offs: int) → int

Retrieves an offset value from the TPI stream with padding, at the specified position.

Parameters

• tpiobj (CFFObject) – The TPI stream object.

• offs (int) – The offset within the TPI stream.

Returns

Returns the padded offset value.

Return type

int

OptionalDbgHeader(dbiobj_or_obj: Pro.Core.CFFObject, offset: Optional[int] = None) → Pro.Core.CFFStruct

Retrieves the optional debug header from the DBI stream.

Parameters

• dbiobj_or_obj (CFFObject) – The DBI stream object or the PDB object.

• offset (Optional[int]) – Optional offset where the debug header starts.

Returns

Returns the optional debug header as a CFFStruct.

Return type

CFFStruct

PDBHeader(pdbobj: Pro.Core.CFFObject) → Pro.Core.CFFStruct

Retrieves the PDB header from the PDB stream.

Parameters

pdbobj (CFFObject) – The PDB stream object.

Returns

Returns the PDB header as a CFFStruct.

Return type

CFFStruct

ParseRootDirectory() → bool

Parses the root directory of the PDB file.

Returns

Returns True if parsing was successful; otherwise False.

Return type

bool

RecordName(tpiobj: Pro.Core.CFFObject, offs: int) → tuple

Retrieves the record name from the TPI stream at the specified offset.

Parameters

• tpiobj (CFFObject) – The TPI stream object.

• offs (int) – The offset within the TPI stream.

Returns

Returns a tuple containing the record length and the name as bytes.

Return type

tuple[int, bytes]

RecordValue(tpiobj: Pro.Core.CFFObject, offs: int) → tuple

Retrieves the record value from the TPI stream at the specified offset.

Parameters

• tpiobj (CFFObject) – The TPI stream object.

• offs (int) – The offset within the TPI stream.

Returns

Returns a tuple containing the record length, the leaf type, and the data as bytes.

Return type

tuple[int, int, bytes]

RootDirectoryData() → Pro.Core.NTContainer

Retrieves the data of the root directory of the PDB file.

Returns

Returns the root directory data as an NTContainer.

Return type

NTContainer

SectionHeaders(obj: Pro.Core.CFFObject) → Pro.Core.CFFStruct

Retrieves the section headers from the given object.

Parameters

obj (CFFObject) – The object containing the section headers, typically the PDB or DBI stream.

Returns

Returns the section headers as a CFFStruct.

Return type

CFFStruct

TPIHeader(tpiobj: Pro.Core.CFFObject) → Pro.Core.CFFStruct

Retrieves the header of the TPI stream.

Parameters

tpiobj (CFFObject) – The TPI stream object.

Returns

Returns the TPI header as a CFFStruct.

Return type

CFFStruct

TPITypeForwards(tpiobj: CFFObject, tpioffs: NTUIntList) → TPITypeFwdHash

Retrieves the type forward hash from the TPI stream.

Parameters

• tpiobj (CFFObject) – The TPI stream object.

• tpioffs (NTUIntList) – A list of type indices (offsets) within the TPI stream.

Returns

Returns the type forward hash as a TPITypeFwdHash.

Return type

TPITypeFwdHash

TPITypeOffsets(tpiobj: Pro.Core.CFFObject) → Pro.Core.NTUIntList

Retrieves the list of type offsets from the TPI stream.

Parameters

tpiobj (CFFObject) – The TPI stream object.

Returns

Returns a list of type offsets.

Return type

NTUIntList

VisitSymbols(dbiobj: Pro.Core.CFFObject, visitor: Pro.PDB.PDBSymbolVisitor) → bool

Visits symbols in the PDB file using the provided symbol visitor.

Parameters

• dbiobj (CFFObject) – The DBI stream object.

• visitor (PDBSymbolVisitor) – The symbol visitor to use for visiting symbols.

Returns

Returns True if symbols were successfully visited; otherwise False.

Return type

bool

See also PDBSymbolVisitor.

class PDBSymbolVisitor

Interface for visiting symbols within a PDB file.

Implement this class to process symbol records during symbol visitation.

See also PDBObject.VisitSymbols().

Methods:

getAddress()	Retrieves the address of the current symbol.
getFlags()	Retrieves the flags associated with the current symbol.
getName()	Retrieves the name of the current symbol.
getProgress()	Retrieves the progress of the symbol visitation process.
isFunction()	Determines if the current symbol represents a function.
visit(rtype)	Called for each symbol encountered during visitation.

Attributes:

reader	The symbol reader used during visitation.
symobj	The symbol object currently being visited.

getAddress() → int

Retrieves the address of the current symbol.

Returns

Returns the address of the symbol.

Return type

int

getFlags() → int

Retrieves the flags associated with the current symbol.

Returns

Returns the symbol flags.

Return type

int

getName() → str

Retrieves the name of the current symbol.

Returns

Returns the symbol name.

Return type

str

getProgress() → int

Retrieves the progress of the symbol visitation process.

Returns

Returns the progress as a percentage.

Return type

int

isFunction() → bool

Determines if the current symbol represents a function.

Returns

Returns True if the symbol is a function; otherwise False.

Return type

bool

reader

The symbol reader used during visitation.

symobj

The symbol object currently being visited.

visit(rtype: int) → bool

Called for each symbol encountered during visitation.

Parameters

rtype (int) – The record type of the symbol.

Returns

Returns True to continue visitation; False to stop.

Return type

bool

class PDBTypeContext

Provides context for parsing and interpreting type information from the TPI stream.

See also PDBObject.CreateTypeContext().

Methods:

DumpAllToHeader(header)	Dumps all type information into the provided header object.
DumpType(out, ti)	Dumps type information for a specific type index to the provided text stream.

DumpAllToHeader(header: Pro.Core.CFFHeader) → bool

Dumps all type information into the provided header object.

Parameters

header (CFFHeader) – The header object to populate with type information.

Returns

Returns True if successful; otherwise False.

Return type

bool

DumpType(out: Pro.Core.NTTextStream, ti: int) → int

Dumps type information for a specific type index to the provided text stream.

Parameters

• out (NTTextStream) – The text stream to output the type information.

• ti (int) – The type index to dump.

Returns

Returns the size of the dumped type.

Return type

int

PDB_STREAM_ID_DBI: Final[int]

Stream ID for the DBI stream in the PDB file.

See also PDBObject.GetStreamObject().

PDB_STREAM_ID_INVALID: Final[int]

Invalid stream ID, indicates an error or non-existent stream.

See also PDBObject.GetStreamObject().

PDB_STREAM_ID_PDB: Final[int]

Stream ID for the PDB stream in the PDB file.

See also PDBObject.GetStreamObject().

PDB_STREAM_ID_TPI: Final[int]

Stream ID for the TPI (Type Info) stream in the PDB file.

See also PDBObject.GetStreamObject().