What's inside a PDB File?

February 8th, 2016

Background

We have all used the Visual Studio Debugger to step through code, in the hunt for bugs. For C or C++ code, that Debugger relies upon a file, with the extension “.pdb”, called the “Program DataBase”, or simply “the PDB”. The PDB is written by the Linker when you build your program; it contains line-number and symbols information. But what lies inside these PDBs, exactly? Most C/C++ developers need never worry about the answer. But for those few, working on tools such compilers, linkers, analyzers and verifiers, knowing the details can be useful. Especially where you want these tools to work within the broader Windows ecosystem: for example, enabling your own compiler to write PDBs so that Apps, built with your compiler, can be executed under existing Windows debuggers. To answer the needs of those few, and/or for readers who are simply interested, we have recently created a GitHub repo where you can browse the actual Linker code that creates PDBs.

Prior APIs and Documentation

We have published outline information on PDB content in years past. This includes an API for reading and writing PDBs. For example:

Description of PDB files: https://support.microsoft.com/en-us/kb/121366

Querying the PDB: https://msdn.microsoft.com/en-us/library/eee38t3h.aspx

Debug Interface Access SDK: https://msdn.microsoft.com/en-us/library/x93ctkx8(VS.80).aspx

If you want to read or write PDBs on Windows, we strongly recommend you use the already-published APIs. This abstracts away the nitty-gritty details and gets the job done. However, for those who want to dig deeper . . .

Source Code

Please browse the content in the GitHub repo at: https://github.com/Microsoft/microsoft-pdb The repo includes 7 folders. A good place to start your exploration would be in /cvdump. This holds .h and .cpp files for a tool that dumps the contents of a PDB. Look for other useful header files in the folders /include and /langapi/include. Whilst /pdbtest holds a small .cpp file that sanity-checks a PDB. Finally, the docs folder provides a list of links to related information. Note that the repo does not include build files, so the intention is that you can browse the code to help understand the PDB. Note too that the code is published under the liberal MIT License.

Next?

We will try to keep this GitHub repo up-to-date with any changes in PDB formats. The format is long-established, so ongoing changes are infrequent, and usually small. The PDB format is complicated. We’re not sure whether the files uploaded so far provide all the details you might need. If you have brief questions, please post them as comments to this blog. But for issues (eg: I need to view the header that defines the XXX struct), please file them directly on the GitHub project so we can track and respond. The link, once again: https://github.com/Microsoft/microsoft-pdb