Using Symbols

For an overview of symbols, including using symbol files and symbol servers, see Symbols.

Symbol Names and Locations

To find the location of a symbol given its name, use GetOffsetByName. For details on the syntax used to specify symbol names, see Symbol Syntax and Symbol Matching.

If the exact name of a symbol is not known, or multiple symbols have the same name, StartSymbolMatch will begin a search for symbols whose names match a given pattern. For details on the syntax, see String Wildcard Syntax.

To find the name of a symbol given its location, use GetNameByOffset. To find the names of symbols in a module near a given location, use GetNearNamebyOffset.

Note   Whenever possible, qualify the symbol with the module name -- for example mymodule!main. Otherwise, if the symbol does not exist (for example, because of a typographical error) the engine will have to load and search the symbols for every module; this can be a slow process, especially for kernel-mode debugging. If the symbol name was qualified with a module name, the engine will only need to search the symbols for that module.

A symbol is uniquely identified using the structure DEBUG_MODULE_AND_ID. This structure is returned by the methods GetSymbolEntriesByName and GetSymbolEntriesByOffset, which search for symbols based on their name and location, respectively.

The method GetSymbolEntryInformation returns a description of a symbol using the DEBUG_SYMBOL_ENTRY structure.

To find the offset of a field within a structure, use GetFieldOffset. To find the name of a field given its index within a structure, use GetFieldName. To find the name of an enumeration constant given its value, use GetConstantName.

The method GetSymbolInformation can perform several requests for information about symbols.

Symbol Options

A number of options control how the symbols are loaded and unloaded. For a description of these options, see Setting Symbol Options.

Symbol options may be turned on by using AddSymbolOptions, and turned off by using RemoveSymbolOptions.

GetSymbolOptions returns the current symbol options. To set all the symbol options at once, use SetSymbolOptions.

Reloading Symbols

After loading symbol files, the engine stores the symbol information in an internal cache. To flush this cache, use Reload. These symbols will have to be loaded again now or at a later time.

Synthetic Symbols

Synthetic symbols are a way to label an arbitrary address for easy reference. Synthetic symbols can be created in any existing module. The method AddSyntheticSymbol creates a new synthetic symbol. Synthetic symbols can be removed using RemoveSyntheticSymbol. Reloading the symbols for the module deletes all synthetic symbols associated with that module.

Symbol Path

To add a directory or symbol server to the symbol path, use the method AppendSymbolPath. The whole symbol path is returned by GetSymbolPath and can be changed using SetSymbolPath.