Installing Windows Symbol Files

Before you debug the Windows kernel, a driver or app, you need access to the proper symbol files. The official way to get Windows symbols is to use the Microsoft Symbol Server. The symbol server makes symbols available to your debugging tools as needed. After a symbol file is downloaded from the symbol server it is cached on the local computer for quick access.

You can connect to the Microsoft Symbol Server with one simple use of the .symfix (Set Symbol Store Path) command. For full details, see Microsoft Public Symbols.

We are no longer publishing the offline symbol packages for Windows. The faster Windows update cadence means the Windows debugging symbols are quickly made out of date. We have made significant improvements to the online Microsoft Symbol Server where symbols for all Windows versions and updates are available. You can find more about this in this blog entry.

For information on how to retrieve symbols for a machine that is not connected to the Internet, see Using a Manifest File with SymChk.

If you are going to debug a user-mode app, you need to install the symbols for this app as well.

You can debug an app if you have its symbols but not Windows symbols. However, your results will be much more limited. You will still be able to step through the app code, but any debugger activity which requires analysis of the kernel (such as getting a stack trace) is likely to fail.

Symbol path for Windows debuggers

The symbol path specifies locations where the Windows debuggers (WinDbg, KD, CDB, NTST) look for symbol files. For more information about symbols and symbol files, see Symbols.

Some compilers (such as Microsoft Visual Studio) put symbol files in the same directory as the binary files. The symbol files and the checked binary files contain path and file name information. This information frequently enables the debugger to find the symbol files automatically. If you are debugging a user-mode process on the computer where the executable was built, and if the symbol files are still in their original location, the debugger can locate the symbol files without you setting the symbol path.

In most other situations, you have to set the symbol path to point to your symbol file locations.

Symbol path syntax

The debugger’s symbol path is a string that consists of multiple directory paths, separated by semicolons.

Relative paths are supported. However, unless you always start the debugger from the same directory, you should add a drive letter or a network share before each path. Network shares are also supported.

For each directory in the symbol path, the debugger looks in three directories. For example, if the symbol path includes the c:\MyDir directory, and the debugger is looking for symbol information for a DLL, the debugger first looks in c:\MyDir\symbols\dll , then in c:\MyDir\dll , and finally in c:\MyDir . The debugger then repeats this process for each directory in the symbol path. Finally, the debugger looks in the current directory and then in the current directory with ..\dll appended to it. (The debugger appends ..\dll , ..\exe , or ..\sys , depending on which binaries it is debugging.)

Symbol files have date and time stamps. You do not have to worry that the debugger will use the wrong symbols that it may find first in this sequence. It always looks for the symbols that match the time stamp on the binary files that it is debugging. For more information about responses when symbols files are not available, see Compensating for Symbol-Matching Problems.

One way to set the symbol path is by entering the .sympath command. For other ways to set the symbol path, see Controlling the Symbol Path later in this topic.

Caching symbols locally

We strongly recommend that you always cache your symbols locally. One way to cache symbols locally is to include cache*; or cache*localsymbolcache;* in your symbol path.

If you include the string cache*; in your symbol path, symbols loaded from any element that appears to the right of this string are stored in the default symbol cache directory on the local computer. For example, the following command tells the debugger to get symbols from the network share \\someshare and cache the symbols in the default location on the local computer.

If you include the string cache*localsymbolcache; in your symbol path, symbols loaded from any element that appears to the right of this string are stored in the localsymbolcache directory.

For example, the following command tells the debugger to obtain symbols from the network share \\someshare and cache the symbols in the c:\MySymbols directory.

Using a symbol server

If you are connected to the Internet or a corporate network, the most efficient way to access symbols is to use a symbol server. You can use a symbol server by using the srv* , srv*symbolstore , or srv*localsymbolcache*symbolstore string in your symbol path.

If you include the string srv* in your symbol path, the debugger uses a symbol server to get symbols from the default symbol store. For example, the following command tells the debugger to use a symbol server to get symbols from the default symbol store. These symbols are not cached on the local computer.

If you include the string srv*symbolstore in your symbol path, the debugger uses a symbol server to get symbols from the symbolstore store. For example, the following command tells the debugger to use a symbol server to get symbols from the symbol store at https://msdl.microsoft.com/download/symbols. These symbols are not cached on the local computer.

If you include the string srv*localcache*symbolstore in your symbol path, the debugger uses a symbol server to get symbols from the symbolstore store and caches them in the localcache directory. For example, the following command tells the debugger to use a symbol server to get symbols from the symbol store at https://msdl.microsoft.com/download/symbols and cache the symbols in c:\MyServerSymbols .

If you have a directory on your computer where you manually place symbols, do not use that directory as the cache for symbols obtained from a symbol server. Instead, use two separate directories. For example, you can manually place symbols in c:\MyRegularSymbols and then designate c:\MyServerSymbols as a cache for symbols obtained from a server. The following example shows how to specify both directories in your symbol path.

For more information about symbol servers, see Symbol Stores and Symbol Servers.

Combining cache* and srv*

If you include the string cache*; in your symbol path, symbols loaded from any element that appears to the right of this string are stored in the default symbol cache directory on the local computer. For example, the following command tells the debugger to use a symbol server to get symbols from the store at https://msdl.microsoft.com/download/symbols and cache them in the default symbol cache directory.

If you include the string cache*localsymbolcache; in your symbol path, symbols loaded from any element that appears to the right of this string are stored in the localsymbolcache directory.

For example, the following command tells the debugger to use a symbol server to get symbols from the store at https://msdl.microsoft.com/download/symbols and cache the symbols in the c:\MySymbols directory.

Using AgeStore to reduce the cache size

You can use the AgeStore tool to delete cached files that are older than a specified date, or to delete enough old files that the resulting size of the cache is less than a specified amount. This can be useful if your downstream store is too large. For details, see AgeStore.

For more information about symbol servers and symbol stores, see Symbol Stores and Symbol Servers.

Lazy symbol loading

The debugger’s default behavior is to use lazy symbol loading (also known as deferred symbol loading). This kind of loading means that symbols are not loaded until they are required.

When the symbol path is changed, for example by using the .sympath command, all loaded modules with export symbols are lazily reloaded.

Symbols of modules with full PDB symbols will be lazily reloaded if the new path no longer includes the original path that was used to load the PDB symbols. If the new path still includes the original path to the PDB symbol file, those symbols will not be lazily reloaded.

For more information about lazy symbol loading, see Deferred Symbol Loading.

You can turn off lazy symbol loading in CDB and KD by using the -s command-line option. You can also force symbol loading by using the ld (Load Symbols) command or by using the .reload (Reload Module) command together with the /f option.

Azure DevOps Services Artifacts

A symbol server is available with Azure Artifacts in Azure DevOps Services. For information on working with Azure Artifacts in WinDbg, see Debug with symbols in WinDbg. For general information about Azure generated symbols, see Symbol files (PDBs).

Controlling the symbol path

To control the symbol path, you can do one of the following:

Use the .sympath command to display, set, change, or append to the path. The .symfix (Set Symbol Store Path) command is similar to .sympath but saves you some typing.

Before you start the debugger, use the _NT_SYMBOL_PATH and _NT_ALT_SYMBOL_PATH environment variables to set the path. The symbol path is created by appending _NT_SYMBOL_PATH after _NT_ALT_SYMBOL_PATH . (Typically, the path is set through the _NT_SYMBOL_PATH . However, you might want to use _NT_ALT_SYMBOL_PATH to override these settings in special cases, such as if you have private versions of shared symbol files.) If you try to add an invalid directory through these environment variables, the debugger ignores this directory.

When you start the debugger, use the -y command-line option to set the path.

(WinDbg only) Use the File | Symbol File Path command or press CTRL+S to display, set, change, or append to the path.

If you use the -sins command-line option, the debugger ignores the symbol path environment variable.

Offline Symbols for Windows Update

This topic describes how you can work with offline symbols for Windows Update. It describes a procedure that can be used to decode Windows Update logs on machines that don’t have access to the Microsoft symbol server.

If you find yourself needing to do this often, you should see if setting up a Symbol Proxy Server is viable for your networking configuration. For more information see SymProxy.

All the options below require you to have one machine that can connect to Microsoft’s symbol server, and have the ability to copy files to or from the machine that has the logs. The machine that doesn’t have access to the symbol server will be referred to as the offline machine, and the machine that does have access as the online machine.

We recommend using a single online machine per OS build version so the WU symbol cache will build month-by-month and contain the WU symbols from multiple update releases.

If you have access to an online machine with the same exact patch level as the offline machine, you have two options:

Verify the online and offline PCs the same version level by running winver or ver on both machines.

If you don’t have access to an online machine with the same version, you’ll need to go through some extra steps to create a SymChk manifest file, described later in this topic in Option 3: Create a SymChk manifest file.

Option 1: Copy the ETL event log to the online machine

Copy all the WindowsUpdate ETL files from C:\Windows\logs\WindowsUpdate\ to your online machine.

On the online machine, open a PowerShell prompt and run the following Get-WindowsUpdateLog PowerShell command.

This will download the symbols needed for log analysis.

Option 2: Copy the symbols to the offline machine

On the online machine, open a PowerShell prompt and run “Get-WindowsUpdateLog”. This will cache the symbols needed for log analysis.

Copy all the files in %temp%\WindowsUpdateLog\SymCache from the online machine to %temp%\WindowsUpdateLog\SymCache on the offline machine.

On the offline machine, open a PowerShell prompt and run “Get-WindowsUpdateLog” to analyze the logs.

Option 3: Create a SymChk manifest file

On the offline machine, follow steps at Using a Manifest File with SymChk to create a manifest for these files in the system32 directory:

Copy the manifest to your online machine.

With the manifest file, use SymChk to download the symbols locally to your online PC.

Copy the folder and symbols you passed to SymChk to %temp%\WindowsUpdateLog\SymCache on your offline PC.

On the offline machine, open a PowerShell prompt and run “Get-WindowsUpdateLog” to analyze the logs.

x (Examine Symbols)

The x command displays the symbols in all contexts that match the specified pattern.

Parameters

Options
Specifies symbol searching options. You can use one or more of the following options:

/0
Displays only the address of each symbol.

/1
Displays only the name of each symbol.

/2
Displays only the address and name of each symbol (not the data type).

/D
Displays the output using Debugger Markup Language.

/t
Displays the data type of each symbol, if the data type is known.

/v
Displays the symbol type (local, global, parameter, function, or unknown) of each symbol. This option also displays the size of each symbol. The size of a function symbol is the size of the function in memory. The size of other symbols is the size of the data type that the symbol represents. Size is always measured in bytes and displayed in hexadecimal format.

/s Size
Display only those symbols whose size, in bytes, equals the value of Size. The Size of a function symbol is the size of the function in memory. The Size of other symbols is the size of the data type that the symbol represents. Symbols whose size cannot be determined are always displayed. Size must be a nonzero integer.

/q
Displays symbol names in quoted format.

/p
Omits the space before the opening parenthesis when the debugger displays a function name and its arguments. This kind of display can make it easier if you are copying function names and arguments from the x display to another location.

/f
Displays the data size of a function.

/d
Displays the data size of data.

/a
Sorts the display by address, in ascending order.

/A
Sorts the display by address, in descending order.

/n
Sorts the display by name, in ascending order.

/N
Sorts the display by name, in descending order.

/z
Sorts the display by size, in ascending order.

/Z
Sorts the display by size, in descending order.

Module
Specifies the module to search. This module can be an .exe, .dll, or .sys file. Module can contain a variety of wildcard characters and specifiers. For more information about the syntax, see String Wildcard Syntax.

Symbol
Specifies a pattern that the symbol must contain. Symbol can contain a variety of wildcard characters and specifiers. For more information about the syntax, see String Wildcard Syntax.

Because this pattern is matched to a symbol, the match is not case sensitive, and a single leading underscore (_) represents any quantity of leading underscores. You can add spaces within Symbol, so that you can specify symbol names that contain spaces (such as «operator new» or «Template») without using wildcard characters.

Environment

User mode, kernel mode

Live, crash dump

Remarks

The following command finds all of the symbols in MyModule that contain the string «spin».

The following command quickly locates the «DownloadMinor» and «DownloadMajor» symbols in MyModule.

You can also show all symbols in the MyModule by using the following command.

The preceding commands also force the debugger to reload symbol information from MyModule. If you want to reload the symbols in the module with a minimal display, use the following command.

A few symbols always contain the string «start». Therefore, the preceding command always displays some output to verify that the command works. But the preceding command avoids the excessive display length of x mymodule!*.

The display shows the starting address of each symbol and the full symbol name. If the symbol is a function name, the display also includes a list of its argument types. If the symbol is a global variable, its current value is displayed.

There is one other special case of the x command. To display the addresses and names of all local variables for the current context, use the following command.

NoteВ В In most cases, you cannot access local variables unless private symbols have been loaded. For more information about this situation, see dbgerr005: Private Symbols Required. To display the values of local variables, use the dv (Display Local Variables) command.

The following example illustrates the /0, /1, and /2 options.

The /0, /1, and /2 options are useful if you want to use the output of the x command as input to the .foreach command.

The following example demonstrates the switch /f when used to filter functions on the module notepad.exe.

When you use the /v option, the first column of the display shows the symbol type (local, global, parameter, function, or unknown). The second column is the address of the symbol. The third column is the size of the symbol, in bytes. The fourth column shows the module name and symbol name. In some cases, this display is followed by an equal sign (=) and then the data type of the symbol. The source of the symbol (public or full symbol information) is also displayed.

In the preceding example, the size is given in hexadecimal format, while the data type is given in decimal format. Therefore, in the last line of the preceding example, the data type is an array of 42 pointers to unsigned short integers. The size of this array is 42*4 = 168, and 168 is displayed in hexadecimal format as 0xA8.

You can use the /sSize option to display only those symbols whose size, in bytes, is a certain value. For example, you can restrict the command in the preceding example to symbols that represent objects whose size is 0xA8.

Working With Data Types

The /t option causes the debugger to display information about each symbol’s data type. Note that for many symbols, this information is displayed even without the /t option. When you use /t, such symbols have their data type information displayed twice.

The x command will display an instance of a type.

The x command does not display anything based on just the name of a type.

To display type information using the name of a type, consider using dt (Display Type), it provides information for both types and instances of types:

Working With Templates

You can use wild cards with the x command to display template classes as shown in this sample.

Consider using the dt (Display Type) command when working with templates, as the x command does not display individual template class items.