The symbol path specifies the directories where the symbol files are located. 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.)

However, because symbol files have date and time stamps, you do not have to worry that the debugger will use the wrong symbols because they are the symbols found first in this sequence. The debugger always looks for the symbols that match the time stamp on the binary files that it is debugging. For more information about responses in case the symbols files are not available, see Compensating for Symbol-Matching Problems.

Note  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* or symsrv* string within your symbol path. For more information about symbol servers, 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. However, if the symbol path is changed, all already-loaded symbols are immediately reloaded. For more information about lazy symbol loading and how to activate and deactivate it, 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.

Controlling the Symbol Path

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

• 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.
• Use the .sympath command to display, set, change, or append to the path. If you are using a source server, the .symfix (Set Symbol Store Path) command is similar to .sympath but saves you typing.
• (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.

cache*localsymbolcache

If you include the string cache*localsymbolcache in your symbol path, the specified directory localsymbolcache will be used to store any symbols loaded from any element that appears in your symbol path to the right of this string. This allows you to use a local cache for symbols downloaded from any location, not just those downloaded by a symbol server.

For example, if you set your symbol path with the following .sympath command, the directory c:\mysymbols will be used to store files from both of the \\private shares, but not from \\someshare:

.sympath \\someshare\that\cachestar\ignores;cache*c:\mysymbols;\\private\binary\symbol\location;\\private\test\build\symbol\share

This can be easily combined with the Microsoft public symbol store by using the following initial setting:

_NT_SYMBOL_PATH=srv*c:\mysymbols*http://msdl.microsoft.com/download/symbols;cache*c:\mysymbols

After this, you can expand the symbol path with the .sympath+ command, which will append additional locations to the right of the current path. Symbols from these new locations will be cached in c:\mysymbols because they are listed to the right of the cache* string in the path; symbols from the symbol server will be stored in c:\mysymbols because of the usual syntax used by the symbol server (see Using a Symbol Server).

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.