Use the Microsoft Symbol Server to obtain debug symbol files (311503)

SUMMARY

This article describes how to reference the Microsoft Symbol Server to obtain symbol debugging information.

Click the Play button to view this streaming media demonstration. Note To view this video, Windows Media Player 7.0 or later must be installed on your computer.For additional information, click the article number below to view the article in the Microsoft Knowledge Base:

299321 Description and Availability of Windows Media Player 7.1

You must have symbol information when you debug applications with various Microsoft tools. Symbol files provide a footprint of the functions that are contained in executable files and dynamic-link libraries (DLLs). Additionally, symbol files can present a roadmap of the function calls that lead to the point of failure. For example, you must have the symbols when you dump call stacks inside a debugger. This article discusses how to use the Microsoft Symbol Server by specifying the following URL to various debugging tools:

http://msdl.microsoft.com/download/symbols

Note http://msdl.microsoft.com/download/symbols is not browseable and is only intended for access by the debugger.

MORE INFORMATION

Using the Symbol Server technology

The Microsoft Symbol Server is built by using the SymSrv technology (SymSrv.dll) that is provided with the Debugging Tools for Windows package. SymSrv builds a local symbol cache for fast, automatic symbol resolution.

It is as simple to use the Symbol Server as it is to use the appropriate syntax in your symbol path. Typically, the syntax takes the following format:

SRV*your local symbol folder*http://msdl.microsoft.com/download/symbols

where your local symbol folder is any drive or share that is used as a symbol destination.

For example, to set the symbol path in the WinDbg debugger, type the following command in the command window of the debugger:

.sympath SRV*f:\localsymbols*http://msdl.microsoft.com/download/symbols

To obtain the latest SymSrv functionality, you must install the latest debugging package. To obtain the latest version of the Debugging Tools for Windows package, visit the following Microsoft Web site:

Microsoft debugging tools
http://www.microsoft.com/whdc/devtools/ddk/default.mspx

For more information about the Symbol Server technology, see the Debuggers.chm help file that is included with the Debugging Tools for Windows package.

Setting the _NT_SYMBOL_PATH environment variable

The common Microsoft debugging tools use the SymSrv technology if you provide the correct symsrv syntax in the _NT_SYMBOL_PATH environment variable. These tools automatically include whatever you provide in the variable as the symbol path.

You can set this variable as a system variable or as a user environment variable. To do this from the desktop, right-click My Computer, and then click Properties. On the Advanced tab, click Environment Variables.

You can also set this variable temporarily at a command prompt. In this way, all applications that you start through the command prompt inherit this setting. For example:

Set _NT_SYMBOL_PATH = symsrv*symsrv.dll*f:\localsymbols*http://msdl.microsoft.com/download/symbols

Using the Microsoft Symbol Server with WinDbg

To use the Symbol Server Web site from within WinDbg, follow these steps:

Start the Windows Debugger (WinDbg.exe).
On the File menu, click Symbol File Path.
In the Symbol path box, type the following command:
SRV*your local folder for symbols*http://msdl.microsoft.com/download/symbols
where your local folder for symbols is the folder in which you copy your local symbol cache. The debug symbols are downloaded to this location.

Note You can point to any local path or share that your computer can reach; it does not have to be a location on the computer's hard disk.

Alternatively, you can also use the .sympath command at a command prompt to set the symbol path.

You can combine the symsrv syntax with other symbol paths. For example, use the following syntax to specify two or more symbol paths:

f:\BusObjSymbols;SRV*f:\localsymbols*http://msdl.microsoft.com/download/symbols

This syntax separates the symbol paths with a semicolon.

When you start to debug a crash dump file or an application, the Windows Debugger checks whether the symbol information for a module that it loads is in the local folder. If the symbol information of the module is not located in the local folder, WinDbg tries to download the appropriate symbol file or files from the Symbol Server.

If you use the same local cache when you debug an application on a computer that has different file versions, symbols for the different versions are downloaded and stored with the first symbols. The SymStore format stores files according to the time stamp and the size of the image (or checksum). As a result, symbols from different product versions can coexist side by side. (SymStore.exe is a utility from the Debugging Tools for Windows package that generates a symbol server. For more information, see the product documentation.)

Because it may take time to download symbol files, keep in mind that the debugger may appear to stop responding (hang) the first time that you debug an application. This occurs because most of the symbol files for the system DLLs (such as Ntdll.dll, Kernel32.dll, and others) must be downloaded.

Using the SymChk.exe utility to download symbols

You can use the SymChk.exe utility to verify symbols and to build a local symbol cache in a convenient, noninvasive way. The SymChk.exe utility is included with the Debugging Tools for Windows package. SymChk.exe is a command-line tool. You may want to add the folder of the Debugging Tools for Windows package to the PATH environment variable on your system so that you can access this tool easily from any command prompt.

To use the SymChk.exe utility to download symbol files for all of the components in the Windows\System32 folder, use the following command-line command:

symchk /r c:\windows\system32 /s SRV*c:\symbols\*http://msdl.microsoft.com/download/symbols

In this example:

/r c:\windows\system32 finds all symbols for files in the System32 folder and any subfolders.
/s SRV*c:\symbols*http://msdl.microsoft.com/download/symbols specifies the symbol path to use for symbol resolution. In this case, c:\symbols is the local folder where the symbols will be copied from the symbol server.

To obtain more information about the command-line options for SymChk.exe, type symchk /? at a command prompt. Other options include the ability to specify the name or the process ID (PID) of an executable file that is running.