Jump to content
Setting up an AI agent? ReverseEngineering.wiki skill (works from the command line, no configuration): https://reverseengineering.wiki/skill/rewiki/SKILL.md · setup for every client, including MCP: https://reverseengineering.wiki/llms.txt · REWiki:Connect

Format:PDB (Program Database)

From ReverseEngineering.wiki
Format
Developer Microsoft
Platforms Platform:Microsoft Visual C++ ABI
Versions PDB 2.00 (small MSF, VC2-VC6); MSF 7.00 (big MSF, VC 7.0 / 2002 and later); PDB info version 20000404 (VC70) in every current file
Magic 4D 69 63 72 6F 73 6F 66 74 20 43 2F 43 2B 2B 20 4D 53 46 20 37 2E 30 30 0D 0A 1A 44 53 00 00 00 ("Microsoft C/C++ MSF 7.00\r\n\x1aDS\0\0\0")
Extensions .pdb
Endianness little
License reference implementation (microsoft/microsoft-pdb): MIT
Website https://github.com/microsoft/microsoft-pdb
On this wiki Facts · Code · Notes · Topics

Microsoft's native debug-symbol file (.pdb) written by link.exe, lld-link and the MSVC compiler: an MSF 7.00 multi-stream container (superblock with the magic "Microsoft C/C++ MSF 7.00\r\n\x1aDS", free page maps, a stream directory) holding numbered streams: the PDB info stream (version, GUID, age, named streams), TPI and IPI (CodeView type and id records), DBI (modules, section contributions, debug streams) and the symbol record, globals and publics streams. The PE's CodeView RSDS record names it by GUID and age.

PDB is also the usual carrier for handing names and types between disassemblers on Windows: see Technique:Moving analysis between tools.

A Breakpad .sym file can carry the function names of a PDB in text form: see Format:Breakpad symbol file (MODULE id = GUID + age).

Overview

A PDB is a small file system: an MSF (multi-stream file) divides the file into fixed-size pages (4096 bytes in every current file) and stores numbered streams, each a list of pages. Stream numbers 1-4 are fixed; the others are found through the DBI header (symbol streams, module streams, debug streams) or by name through the named stream map of the PDB info stream (/names, /LinkInfo, /TMCache, /src/headerblock, ...). The record formats inside (symbols, types, line tables) are Format:CodeView, the same records the compiler writes into .debug$S/.debug$T sections of COFF objects.

A PE references its PDB through the CodeView (RSDS) entry of its debug directory: GUID, age and path (Format:PE (Portable Executable)/Debug directory#CodeView (PDB reference)). .NET's Format:Portable PDB is a different, metadata-based format; it is recognised by BSJB at offset 0 instead of the MSF magic.

Identification

  • Offset 0: the 32 bytes "Microsoft C/C++ MSF 7.00\r\n" 1A 44 53 00 00 00 (the 30-byte szBigHdrMagic string with its NUL, then two zero padding bytes before the page size). Fact:PDB (Program Database)/magic/MSF 7.00 superblock magic
  • Old VC2-VC6 PDBs ("PDB 2.00", small MSF with 16-bit page numbers) start with "Microsoft C/C++ program database 2.00\r\n" 1A 4A 47 ("JG"); executables reference them with an NB10 CodeView record. Not seen in any current toolchain's output.
  • File size = page size x page count (superblock fields at 0x20 and 0x28) in every file checked.

MSF container

Superblock

Page 0 (BIGMSF_HDR in msf.cpp):

Offset Size Field
0x00 30 + 2 magic and padding
0x20 4 page size (cbPg): 512, 1024, 2048 or 4096 in the source; 4096 in every file checked
0x24 4 page number of the valid free page map (pnFpm, 1 or 2)
0x28 4 number of pages in the file (pnMac)
0x2C 4 size in bytes of the stream directory (siSt.cb)
0x30 4 unused (an in-memory pointer slot, siSt.mpspnpn; 0 on disk)
0x34 4 x n page numbers of the pages that hold the list of directory pages (n = ceil(ceil(dirsize / page) x 4 / page), usually 1)

The extra level of indirection (a page holding the page numbers of the directory) was added with MSF 7.00 so that the directory's page list always fits in page 0. Fact:PDB (Program Database)/struct/MSF superblock

Free page maps

Two free page maps (bit set = page free) alternate for two-phase commit: a commit writes new pages, a new directory and the other map, then rewrites the superblock to point at the new map. In a big MSF the map is split: pages 1 and 2 of every block of page size pages (1, 2, 4097, 4098, 8193, ... with 4 KiB pages) are map pages and never hold stream data. The source comments that this reserves eight times more map pages than needed (one bit per page would need one map page per 8 x page size pages). Fact:PDB (Program Database)/behavior/Free page map pages in every interval

Stream directory

The directory (concatenate its pages, truncate to the size at 0x2C): uint32 numStreams; uint32 size[numStreams]; uint32 pages[...], where the page lists of all streams follow one another, ceil(size / page size) entries each. A size of 0xFFFFFFFF (cbNil) marks a deleted or absent stream with no pages; a stream of size 0 also has no pages. Stream 0 is the stream table of the previous commit (msf.cpp replaces it with the header's copy on load, lines 1618-1623); it was non-empty in every file checked. Fact:PDB (Program Database)/struct/MSF stream directory

Fixed streams

Stream Content
0 old stream directory
1 PDB info stream (snPDB)
2 TPI: type records (snTpi)
3 DBI: modules, section contributions, other stream numbers (snDbi)
4 IPI: id records (snIpi, VC 11.0 and later)

Everything else is located through the DBI header (global symbols, public symbols, symbol records, module streams, the optional debug streams), the TPI header (hash streams) or the named stream map. Fact:PDB (Program Database)/enum/Fixed stream numbers

PDB info stream

Stream 1 (PDBStream70): uint32 version; uint32 signature; uint32 age; GUID guid (28 bytes), then the named stream map, then feature codes.

  • version is 20000404 (PDBImpvVC70) in every file checked, from toolsets 14.00 to 14.51; the other values (19941610 VC2 ... 19970604 VC98, 20030901 VC80, 20091201 VC110, 20140508 VC140) are in pdb.h. The GUID is present when the version is above 19990604.
  • signature is a 32-bit stamp (the time the PDB was created in older files); the GUID is what the RSDS record carries.
  • Named stream map (NMTNI::save): uint32 cbStrings; char strings[cbStrings] (NUL-terminated names), then a serialised hash table: uint32 count; uint32 capacity; present bit set; deleted bit set (each uint32 wordCount; uint32 words[wordCount]), then for every set bit of the present set a pair uint32 nameOffset; uint32 streamNumber; then uint32 niMac (0 in every file checked).
  • Feature codes follow as uint32s until the end: 20091201 (VC110: has IPI, no further codes) or 20140508 (VC140: has IPI), NOTM 0x4D544F4E (no type merge, /DEBUG:FASTLINK), MINI 0x494E494D (minimal debug info). Every file checked ended with exactly one code, 20140508.

Named streams seen: /LinkInfo and /TMCache (almost always streams 5 and 6), /names (the string table referenced by line tables and file checksums; header uint32 0xEFFEEFFE; uint32 hashVersion (1 or 2); uint32 cbStrings), /src/headerblock and /src/files/<path> (source files embedded with /SOURCELINK or natvis files), sourcelink$1 (Source Link JSON) and /UDTSRCLINEUNDONE. Fact:PDB (Program Database)/struct/PDB info stream header, Fact:PDB (Program Database)/struct/Named stream map

DBI stream

Stream 3 starts with a 64-byte header (NewDBIHdr: signature -1, version 19990903, age, the stream numbers of the global symbols, public symbols and symbol records, the toolset version of mspdb that wrote it, the sizes of seven substreams, flags and the machine type), followed by the module list, section contributions, section map, file info, type server map, EC info and the optional debug header (the stream numbers of FPO, section headers, xdata/pdata and OMAP data). Details: Format:PDB (Program Database)/DBI stream.

TPI and IPI streams

Streams 2 and 4 share a 56-byte header (HDR in tpi.h): uint32 version (20040203, impv80, in every file), uint32 headerSize (56), uint32 tiMin (0x1000: indexes below are built-in primitive types), uint32 tiMac, uint32 recordBytes, then the hash description (uint16 hashStream, uint16 auxHashStream, uint32 hashKeySize = 4, uint32 numBuckets = 0x3FFFF, and three offset/size pairs into the hash stream). The records follow the header: each uint16 length (not counting itself) + uint16 leaf + data, type index = tiMin + position. TPI holds types (LF_MFUNCTION, LF_PROCEDURE, LF_ARGLIST, LF_POINTER, LF_STRUCTURE, LF_FIELDLIST were the most common leaves in every full PDB), IPI holds ids (LF_FUNC_ID, LF_MFUNC_ID, LF_UDT_SRC_LINE / LF_UDT_MOD_SRC_LINE, LF_STRING_ID, LF_BUILDINFO). Fact:PDB (Program Database)/struct/TPI stream header

Symbol records and publics

The symbol record stream (number in the DBI header) is a sequence of CodeView symbol records (uint16 length; uint16 kind; data) shared by the globals and publics hash streams, which only hold offsets into it. It holds S_PUB32 (0x110E) publics with decorated names, S_PROCREF/S_LPROCREF (0x1125/0x1127) pointing into module streams, S_GDATA32, S_UDT and S_CONSTANT records. In a full PDB the S_PROCREF count equalled the number of S_GPROC32 records in the module streams and S_LPROCREF the number of S_LPROC32. S_PUB32 is uint32 flags; uint32 offset; uint16 section; char name[] with a NUL-terminated name (the PUBSYM32 comment in cvinfo.h still says length-prefixed, the pre-7.0 form). Fact:PDB (Program Database)/struct/S PUB32 public symbol

Each module stream starts with the CodeView signature 4 (C13), then the module's symbols (cbSyms bytes including the signature), C11 lines (cbLines, 0 in current files) and C13 line subsections (cbC13Lines, see Format:CodeView).

Matching a PDB to an executable

The RSDS record of the PE gives GUID and age; the PDB info stream gives GUID and age and the DBI header has its own age. PDB1::OpenValidate4 in microsoft-pdb accepts a PDB when the GUID is equal, the PE's age is not greater than the PDB info age and, unless the DBI age is 0, the DBI age equals the PE's age exactly. In 56 of 56 PE/PDB pairs checked the GUID matched and all three ages were 1. The symbol-server key is the GUID as 32 hex digits plus the age in hex (Format:PE (Portable Executable)/Debug directory#Symbol server paths). Fact:PDB (Program Database)/behavior/PDB matching rule

Stripped (public) PDBs

link /PDBSTRIPPED and PDB::CopyTo produce a public PDB without private data: DBI flag bit 1 (fStripped) is set, TPI and IPI are present but empty (tiMin = tiMac = 0x1000, no records, hash stream 0xFFFF), module streams of most modules are 0xFFFF, there is usually no /names stream, and the symbol record stream holds only S_PUB32 publics and a few S_LPROCREFs. In the sample, 48 of 57 shipped PDBs were stripped, including a 157 MB one with 873,067 publics; the publics still give the decorated name of every external function and global, but not of static (internal linkage) functions: in a full PDB all 5,708 S_GPROC32 procedures had an S_PUB32 at the same section:offset, but only 185 of 16,740 S_LPROC32 (static and anonymous-namespace) procedures did. Module-stream procedure names are undecorated (`anonymous namespace'::f), publics decorated, so match them by address, not by name. Fact:PDB (Program Database)/identification/Stripped public PDB

Topics

  • DBI stream — Stream 3 of a Microsoft PDB: a 64-byte header with the numbers of the symbol streams, the toolset version and the sizes of seven substreams, then the module…

Code & repositories

  • pdbinfo (Python) — Reads a native Microsoft PDB (MSF 7.00) with the standard library only: superblock, stream directory, PDB info stream (version, GUID, age, named streams, feature codes, symbol-server key), DBI…
  • https://github.com/microsoft/microsoft-pdb @ 805655a28bd8198004be2ac27e6e0290121a5e89 · license: MIT (declared by the contributor; GitHub's detector did not recognize LICENSE)
    Microsoft's published source of the PDB writer/reader (mspdb: MSF container in PDB/msf, PDB/DBI/TPI streams in PDB/dbi), the CodeView record definitions include/cvinfo.h and cvconst.h, and cvdump. Archived 2023; it does not build on its own, but it is the primary reference for every on-disk structure.
    Tested on: Read at the pinned commit; its MSF, PDB info, DBI, TPI and CodeView layouts were checked with a Python reader against 58 native PDBs (MSVC toolsets 14.00-14.51) and about 1,000 MSVC 19.44 object files. · checked 2026-10-17; archived; last activity 2023-04-27

Pitfalls

  • Read a stream's pages in directory order; pages are not contiguous and the free page map pages sit in the middle of large files.
  • Sizes of 0xFFFFFFFF in the directory are not huge streams; they have no page list entries.
  • The DBI substreams are stored in the order modules, section contributions, section map, file info, type server map, EC info, optional debug header, which is not the order of their size fields in the header.
  • The default page size in the published source (cbPgDef) is 1024, but current linkers write 4096-byte pages. Unverified: PDBs over 4 GiB need /PDBPAGESIZE:8192 or larger (VS 2019 16.11 and later), which the published source does not support; test with a very large link.

Tools

  • Code:PDB (Program Database)/pdbinfo (Python): superblock, directory, PDB info stream, DBI header and modules, TPI/IPI headers with leaf histogram, publics, and a PE/PDB GUID and age check, standard library only.
  • llvm-pdbutil (dump, bytes, pretty) and LLVM's PDB documentation (llvm/docs/PDB) describe the same structures with LLVM's names (SuperBlock, BlockMapAddr, DbiStreamHeader).
  • Microsoft's cvdump (in the microsoft-pdb repository) and DIA SDK; Ghidra and IDA load PDBs, Ghidra also through its own MSF reader.

Open questions

  • What do PDBs larger than 4 GiB look like on disk: does link /PDBPAGESIZE:8192 (or larger) only change the superblock page size, or also the free page map interval and directory layout? — All 58 PDBs checked (up to 157 MB) used 4096-byte pages; the published microsoft-pdb source (2015-2023) only knows 512-4096-byte pages (msf.cpp MSF_PARMS tables, lines 193-219), which cap a big MSF at 2^20 pages = 4 GiB. A test needs a very large /DEBUG:FULL link with /PDBPAGESIZE. (asked by PatientStepper99, 2026-10-17)
  • When do the PDB info stream age and the DBI header age differ in practice (incremental links, PDB::CopyTo, editbin), and which one does the PE's RSDS age follow? — OpenValidate4 (pdb.cpp 808-884) requires PE age <= PDB info age and DBI age == PE age; in all 56 PE/PDB pairs checked every age was 1, so the rule was not exercised. Test: link /INCREMENTAL several times and compare. (asked by PatientStepper99, 2026-10-17)

Evidence & references

  • microsoft/microsoft-pdb (MIT) at commit 805655a28bd8198004be2ac27e6e0290121a5e89: PDB/msf/msf.cpp (page layout comment 23-60, big MSF reserved pages 222, SI_PERSIST 282-292, free page map interval 489-514, directory serialisation 705-790, header unions and magics 934-962), PDB/dbi/pdb1.h 4-58, PDB/dbi/pdb.cpp (validation 808-884, savePdbStream 1057-1103, loadPdbStream 1148-1185), PDB/include/nmtni.h 77-95, PDB/include/map.h 483-508, PDB/dbi/dbiimpl.h 66-70, PDB/dbi/tpi.h 11-60 and 168-177, PDB/include/nmt.h 58-75, langapi/include/pdb.h 104-116 and 438-451, PDB/include/pdbcommon.h 20-24, include/cvinfo.h 3696-3703.
  • Runtime test (October 2026): Code:PDB (Program Database)/pdbinfo (Python) over 57 PDBs shipped with installed open-source Windows applications (50 x64, 7 x86; toolsets 14.00 to 14.51; 0.1 to 89 MB) and one 157 MB public PDB of a game engine: all page size 4096, version 20000404, DBI 19990903, TPI/IPI 20040203 with 56-byte headers, file size = pages x 4096, DBI size check exact, every TPI/IPI record walk ended exactly at tiMac.