Description of the .PDB files and of the .DBG files

This article was previously published under Q121366
This article has been archived. It is offered "as is" and will no longer be updated.
The .PDB extension stands for "program database." It holds the new formatfor storing debugging information that was introduced in Visual C++version 1.0. In the future, the .PDB file will also hold other projectstate information. One of the most important motivations for the change informat was to allow incremental linking of debug versions of programs, achange first introduced in Visual C++ version 2.0.

The .DBG extension stands for "debug." The .DBG files created with the32-bit NT toolset are in the Portable Executable (PE) file format.They contain sections with COFF, FPO, and in some cases Codeviewinformation. The Visual C++ integrated debugger can read .DBG files inthis format, however it ignores the COFF symbol sections and looks forCodeview information.

If you need to determine what symbol information is contained in a .DBGfile, you can type the following at the command prompt:
Dumpbin sample.dbg/symbol.				
Note The path might need to include directories for Dumpbin.exe andMSdis100.dll:
Path=%Path%;C:\Program Files\DevStudio\VC\bin;C:\Msssdk\bin				
For more information about DUMPBIN, click the following article number to view the article in the Microsoft Knowledge Base:
177429 Examples of DUMPBIN output

The .PDB files

While earlier, 16-bit versions of Visual C++ used .PDB files, thedebugging information stored in them was appended to the end of the .EXE or.DLL file by the linker. In the versions of Visual C++ mentioned above,both the linker and the integrated debugger were modified to allow .PDBfiles to be used directly during the debugging process, thereby eliminatingsubstantial amounts of work for the linker and also bypassing thecumbersome CVPACK limit of 64K types.

For more information about CVPACK limitations, click the following article number to view the article in the Microsoft Knowledge Base:
112335 BUG: CK1020 or CK4009 encountered when type info exceeds 64K
By default, when you build projects generated by the Visual Workbench, thecompiler switch /Fd is used to rename the .PDB file to <project>.PDB.Therefore, you will have only one .PDB file for the entire project.

When you run makefiles that were not generated by the Visual Workbench, andthe /Fd is not used with /Zi, you will end up with two .PDB files:
  • VCx0.PDB (where "x" refers to the major version of the corresponding Visual C++, either "2" or "4"), which stores all debugging information for the individual .OBJ files. It resides in the directory where the project makefile resides.
  • <project>.PDB, which stores all debugging information for the resulting .EXE file. It resides in the \WINDEBUG subdirectory.
Why two files? When the compiler is run, it doesn't know the name of the.EXE file into which the .OBJ files will be linked, so the compiler can'tput the information into <project>.PDB. The two files store differentinformation. Each time you compile an .OBJ file, the compiler merges thedebugging information into VCX0.PDB. It does not put in symbol informationsuch as function definitions. It only puts in information concerning types.One benefit of this is that when every source file includes common headerfiles such as <windows.h>, all the typedefs from these headers are onlystored once, rather than in every .OBJ file.

When you run the linker, it creates <project>.PDB, which holds thedebugging information for the project's .EXE file. All debugginginformation, including function prototypes and everything else, is placedinto <project>.PDB, not just the type information found in VCX0.PDB. Thetwo kinds of .PDB files share the same extension because they arearchitecturally similar; they both allow incremental updates. Nevertheless,they actually store different information.

The new Visual C++ debugger uses the <project>.PDB file created by thelinker directly, and embeds the absolute path to the .PDB in the .EXE or.DLL file. If the debugger can't find the .PDB file at that location or ifthe path is invalid (if, for example, the project was moved to anothercomputer), the debugger looks for it in the current directory.

The .DBG files

The Visual C++ integrated debugger can also use .DBG files as long asthey are made from a binary containing Codeview format debugging output.These are useful for debugging when the source code is not available. Evenwithout the source, .DBG files allow you to set breakpoints on functions,watch variables, and see the functions in the call stack. They are alsorequired for OLE RPC debugging.

One caveat needs to be pointed out: when working with symbols from a .DBGfile, you must use the fully decorated names. For example, to set abreakpoint on a call to the Windows sndPlaySound function, you wouldspecify _sndPlaySoundA@8 as the location.

There are actually two .DBG file formats. The old format has existed forquite a while in the 16-bit world. For example, because the format of .COMfiles is a simple binary image loaded into memory, the Codeview debugginginformation could not be appended to the end of the file because the filesize might exceed the 64K limit for a .COM file. Therefore the symbolicinformation was instead put into a separate .DBG file, which had onlyCodeview information in it. The .DBG files could also be generated byrunning CVPACK on an .EXE file using the /strip option.

For 32-bit .EXEs, the Visual C++ version 2.x and 4.x debugger's symbolhandler does not read the old format. Instead, it reads the format used inthe Windows NT .DBG files, supplied for use with its system .DLL files.These .DBG files are in the Portable Executable (PE) file format andcontain sections with COFF, FPO, and in some cases Codeview symbolicinformation. The new Visual C++ debugger reads .DBG files in this formatonly. Furthermore, it only uses the Codeview information, ignoring theother symbol sections.

It is possible to strip debug information from a PE file and store it in a.DBG file for use by debuggers. For this to work, the debugger needs toknow whether to find the debug information in a separate file or not andwhether the information has been stripped from the file or not. One methodwould be for the debugger to search through the executable file looking fordebug information. However, to save the debugger from having to search thefile, a file characteristic field (IMAGE_FILE_DEBUG_STRIPPED) was inventedthat indicates that the file has been stripped. Debuggers can look for thisfield in the PE file header to quickly determine whether the debuginformation is present in the file or not.

To generate a .DBG file in this format, you can use REBASE.EXE, which isprovided with the Win32 SDK. Please see the Win32 SDK documentation formore details.

During the Windows NT retail builds, debug symbols are stripped from thesystem binaries and drivers and stored in separate .DBG files. This is donebecause the Windows NT kernel debugger can use these .DBG files and providedebugging symbols even for optimized drivers. Remember, however, that theVisual C++ integrated debugger is not designed to debug protected modekernel code.

The Windows NT symbol files can be found in a debug subdirectory of the\SUPPORT directory on the Windows NT retail CD-ROM. These files must becopied from the CD-ROM to your hard drive. For user mode debugging on thetarget debugger machine, .DBG symbols must be present in the Windows NT\<winnt>\SYMBOLS directory of the target system (<winnt> is the directorywhere Windows NT is installed). The new Visual C++ setup program installsan "NT System Symbols Setup" icon in your program group. You can use it toautomatically copy the .DBG files from your Windows NT Workstation CD-ROMdisk to the correct directory structure on your hard drive. This methoddoes not work for the Windows NT Server 4.0 CD-ROM because the .DBG filesare stored in compressed format.

For kernel debugging, place .DBG files into a symbols tree underneath thedirectory specified by the _NT_SYMBOL_PATH environment variable (forexample, C:\DEBUG\SYMBOLS). Kernel debugging is possible with a minimal setof symbols consisting of symbols for all the drivers (*.SYS) in theSYMBOLS\SYS directory, and symbols for NTOSKRNL.EXE and HAL.DLL in theSYMBOLS\EXE and SYMBOLS\DLL directories, respectively. For more informationon kernel debugging, refer to the discussion regarding kernel debugging inthe Windows NT DDK Programmer's Guide.

While it is theoretically possible to convert from a .PDB file back to a.DBG file, it is not a trivial task. At this time, we know of no such tool.If we hear of such a tool, we will update this article in the MicrosoftKnowledge Base.
kbDebug kbTools kbVC200 kbVC210 kbVC400 kbVC500

Article ID: 121366 - Last Review: 12/04/2015 10:35:01 - Revision: 3.1

Microsoft Visual C++ 2.0 Professional Edition, Microsoft Visual C++ 2.1, Microsoft Visual C++ 4.0 Standard Edition, Microsoft Visual C++ 6.0 Service Pack 5, Microsoft Visual C++ 5.0 Standard Edition, Microsoft Visual C++ 6.1

  • kbnosurvey kbarchive kbbug kbdebug kbide kbinfo KB121366