Symbol Files

Creation of PDB files

In order to generate PDB files, cl needs to be invoked with either the /Zi or /ZI option and the linker with the /DEBUG option.

The PDB is created in the same directory as the created executable or dll.

The DLL that is used by a compiler or linked to prodcue the symbol file is mspdbcore.dll.

Content of a PDB file

The content of a symbol file is not needed to run an application. It is useful however for debugging purposes.

Particularly, a PDB file contains

Public symbols (functions, static and global variables)
The object files that were used to create the executable, and their respective section
Frame pointer optimization (FPO) information
Type information (variables, structs …)
Source file name and line numbers

Each piece of information is called a symbol, hence the name symbol files.

The format of a symbol files is not documented by Microsoft. Yet, it is possible to read the contents of a PDB file with the Debug Interface Access SDK.

Update 2022-03-03: I stumbled upon the microsoft-pdb github repository which contains information from Microsoft about the PDB (Program Database) Symbol File format. The repository's README.md is worth reading.

Symbol server

A symbol server allows a debugger to find the correct symbol files without knowing product names, build numbers or package names.

Symbol servers are (also?) available with Azure Artifacts.

TODO: tracerpt.exe has the option -pdb to specifiy a symbol server path.

_NT_SYMBOL_PATH

The _NT_SYMBOL_PATH environment variable is used by all Debugging Tools for Windows to find symbol servers and symbol files.

The format is:

srv*[local cache]*[private symbol server]*https://msdl.microsoft.com/download/symbols

or less abstract

srv*C:\ProgramData\Dbg*https://msdl.microsoft.com/download/symbols

With this value, the symbols are downloaded to C:\ProgramData\Dbg.

On a command line, the current symbol search paths can be displayed with dbh.exe:

C:\> dbh sympath

Symbol Search Path: srv*C:\ProgramData\Dbg*https://msdl.microsoft.com/download/symbols

Search locations

Debugging Tools for Windows and Visual Studio Debugger look in the following locations when trying to locate symbol files:

Directory in which the executable resised
Path of PDB as recorded in executable (usually during linking time)
Search paths configured (for example in VS IDE or WinDbg menu File -> Symbol File Path.
Paths of _NT_SYMBOL_PATH and _NT_ALT_SYMBOL_PATH
Windows directory C:\Windows\System32?

The PDBPATH command line option of dumpbin.exe displays the directories in which the debugger would search for the symbol files.

Windows Version

Symbol files must match the Windows version of the Windows installation where they're used.

Examining symbols

In Debugging Tools for Windows, symbols can be examined with the x (= examine) command.

On the command line, symbols can be queried from an executable (that has a symbol file) with dbh.exe.

Misc

These PDB files have nothing to do with Oracle's plugable databases which are also abbreviated with PDB.

TODO

Symbol files have fully qualified path references to the source files. If the source files are moved to different location, the .srcpath command of WinDbg needs to be used to specify the new location.

The WinDbg command .sympath seems to specify the location for symbol files.