Understanding and Using Symbols

Symbol files are data files that contain information about the program files with which they're associated. This information includes

This information exists for two reasons. The first reason is for the compiler (i.e., a program that turns source code into an application, such as an .exe or .dll file) to use when it builds the application. The second reason is for people to use when debugging an application. The symbolic information is generated as part of the compilation of an application (if you set the compiler to generate symbolic information). This information can reside directly in the application files, or it can be written to separate symbol files. Where the symbols reside depends on your development application and the settings you choose. For example, Microsoft Visual Basic (VB) builds symbols right into the program files. Visual C++ (VC++) usually builds one or two separate files.

As I mentioned in the article, symbol files have two file types—.dbg and .pdb. The .dbg files are in Common Object File Format (COFF), which is a generic symbol file description that doesn't include source line information; many debuggers can read these files. The .pdb files are a Microsoft format and contain a lot more information than the .dbg files. For example, source line information is available only in .pdb symbols. Symbol files that include source-code line information let you use the source code for debugging. The debugging tools locate symbols by referencing the SYMPATH environment variable or by explicitly telling each tool where to get symbols.

Symbol trees. Because debuggers let you specify the location of the symbols you need, and because several different versions of software are usually installed on the different production servers, common practice is to use a symbol tree in the development or support environment. A symbol tree is a server with a share point that contains the symbols for several different software versions. In this way, when you start debugging a problem or reading a memory dump file, you can simply point to the software version you need without having to load symbols on your debugging machine. Note that many administrators use symbol trees primarily for offline debugging or development debugging. Keeping the proper symbol files on your production servers is still a good practice. Figure A shows a typical symbol tree.

Symbol locations. The location of symbols depends on how they're built. If the symbols are built into an application's .dll or .exe file, symbol placement is moot. If the symbols are built as COFF, they can reside either in the directory that your symbol path environment variable points to or in the directory in which your program resides. If the symbols are in Microsoft format, they should reside in the directory in which the program file resides. The exception to this rule is the symbols for Windows and other Microsoft applications. The .dbg symbol files that Microsoft generates are built so that they point the debugger to find the .pdb files in the symbol path directory.

Export Symbols
Often, when you're debugging an application, you encounter the message Using Export symbols for XXX. This message should raise a flag to you. The message means that either the debugger couldn't locate the symbols or the symbols weren't the right version for a given file. In either case, the debugger will revert to using built-in information called an export table. An export table is a list of all functions in a DLL that are available for other .dll or .exe files to call (i.e., all the functions the DLL exports to other programs). The debugger reads the information from the export table and builds the symbolic information from that information, which might be fine in some cases.

However, here's where you run into trouble. Assume that you have a DLL with five exported functions and six more functions that are just for this DLL to use. The order in which the functions are written in the code is random, so you have export and private functions mixed up. As far as the debugger is concerned, all the memory between Export Function 1 and Export Function 2 belongs to Export Function 1. However, halfway through this code is Private Function 1. If you're in this code, the debugger reports that you're still in the export function. If you have messages stating that you're using export symbols, take the information you get from the debug with a grain of salt, because it might not be correct. Get the proper symbols for the file in question.

Downloading Symbols
Use these links to download symbols for some of Microsoft's core products. Note that Microsoft is likely to update and change these links as it updates its Web site with new information and options for debugging.

Windows NT Server 4.0, Terminal Server Edition

NT Server 4.0

Windows 2000 Server