Having the correct symbols for the operating system and your application makes debugging easier. Symbols provide symbolic information on function names, parameter names, and local variables. They also provide line number information for the source code and data to fix frame pointer omissions (FPOs). Without symbol files, little of this valuable information is available and debugging is less transparent. Symbols are contained in a symbol file, which has a .pdb extension.
Separate packages of symbol files are available for the different Windows operating systems. Windows 98, Windows 2000, Windows XP, Windows NT Server 2003, and Windows Vista require different symbols. In addition, individual service packs and builds might have some additional symbols. For these reasons, obtaining the correct symbols is sometimes a trial-and-error process. This is further complicated with dumps. You might open a dump on a machine that did not create the dump, and the machine that created the dump might have had a different operating system. Therefore, the local machine must have the symbols for the operating system where the dump was created, as well as symbols for its own operating system. All this makes having the correct symbols for debugging complicated at times. It would be nice if the required symbols could be downloaded to your local machine automatically. Well, they can. That is the purpose of a symbol server.
A symbol server is a database of symbol files. It can download to a local cache the correct symbols needed for debugging. For example, Microsoft offers a public symbol store that can download the operating system symbols that you need. It can download the correct symbols from all the Microsoft operating systems. You no longer have to invest a lot of time investigating this. The Web address for the Microsoft Public Symbol Store is http://msdl.microsoft.com/download/symbols.
Before using the Microsoft Public Symbol Store, install the correct symbol package for your operating system. You then can use the Microsoft symbol store to fine-tune the remaining symbols. Symbol packages for different Windows environments are downloadable from this location: http://www.microsoft.com/whdc/devtools/debugging/symbolpkg.mspx.
The file symsrv.dll is the symbol server engine distributed with Debugging Tools for Windows, and it must be installed in the same directory as the debugger. Symsrv manages downloading symbols from a symbol server to a local cache, which also is called a downstream store. Files can be transferred over http and https.
Here is the generic syntax to download symbol files from a symbol server to a downstream store. It will download only the necessary symbols:
Symsrv*ServerDLL*DownstreamStore*SymbolStore
In this syntax, ServerDLL identifies the symbol server engine. The following command uses the symsrv.dll symbol server engine. It will contact the Microsoft Public Symbol Store to download required symbol files. The symbols are transferred to c: symbols, which is specified as the downstream store in this example:
Symsrv*Symsrv*c:symbols*http://msdl.microsoft.com/download/symbols
Because symsrv.dll is the most prevalent symbol server, an abbreviated syntax is available:
srv*DownstreamStore*SymbolStore
The following command uses the abbreviated syntax and is identical to the previous expanded command that referenced the symsrv.dll symbol server explicitly and downloaded symbols from the Microsoft Public Symbol Store:
srv*c:symbols*http://msdl.microsoft.com/download/symbols
As shown in the following syntax, symbol servers can have multiple downstream servers. If the symbol file is not in DownstreamStore1, it is downloaded from DownstreamStore2. Furthermore, if the file is not in DownstreamStore2, DownstreamStore3 is contacted. If the file is found there, it is downloaded from DownstreamStore3 into DownstreamStore2 and then from DownstreamStore2 into DownstreamStore1. This pattern continues until the debug symbol is found or the symbol stores are exhausted. It is a best practice to list the downstream store in order of proximity. The nearest, such as a local cache, should be listed first:
srv*DownstreamStore1*DownstreamStore2*DownstreamStoren*SymbolStore
In most debuggers, you can set the symbol path, including symbol server and downstream stores. However, to avoid configuring the symbol path separately in each debugger, you can use the _NT_SYMBOL_PATH environment variable. Most debuggers automatically read the _NT_SYMBOL_PATH environment variable to set the default symbol path.
The Microsoft Public Symbol Store downloads the symbols for the environment. The symbols for your application also are required. You should build symbols for both the release and debug versions of your product. Building symbols for a release version of a product does not affect the performance of that application. Symbols also should be checked into source control to keep correct symbol packages with different versions of the product. Preserve symbols for all public versions of your product, so that when you are debugging a client problem, you are assured of having the correct symbols available.
Visual Studio .NET automatically creates a symbol file (PDB) for both debug and release versions of the product.
In WinDbg, the symbol path can be set via the user interface or via the command line. From the user interface, select the Symbol File Path command from the File menu. Alternatively, at the command line, use the .sympath directive to set or display the symbol path. The .sympath command without options will display the symbol path. Otherwise, the .sympath command will set the symbol path to the path provided. Whenever you change the symbol path, reload the symbols with the .reload command. In the Symbol File Path dialog box, there is a Reload check box.
For symbol problems, the !sym noisy command is helpful. It displays additional information when symbols are loaded to diagnose possible problems. The !sym quiet command, which is the default, suppresses the additional data.