Using SymSrv

The SymSrv (symsrv.dll) symbol server is included in the Debugging Tools for Windows package. It must be installed in the same directory as the copy of Dbghelp.dll that you are loading. To ensure that you load the correct version of Dbghelp.dll, delay-load the DLL instead of having the operating system load it. Be sure to specify a full path to Dbghelp.dll when calling the LoadLibrary function.

SymSrv delivers symbol files from a centralized symbol store. This store can contain any number of symbol files, corresponding to any number of programs or operating systems. The store can also contain binary files (this is useful when debugging minidump files).

The store can contain the actual symbol and binary files, or it can simply contain pointers to symbol files. If the store contains pointers, SymSrv will retrieve the actual files directly from their sources.

SymSrv can also separate a large symbol store into a smaller subset that is appropriate for a specialized debugging task.

Finally, SymSrv can obtain symbol files from an HTTP or HTTPS source using the logon information provided by the operating system. SymSrv supports HTTPS sites protected by smartcards, certificates, and regular logins and passwords.

Setting the Symbol Path

The symbol path (_NT_SYMBOL_PATH environment variable) can include several directories separated by semicolons for SymSrv to use to locate symbol files. This path can also include symbol stores using the following syntax:

symsrv*ServerDLL*DownstreamStore*\\Server\Share

symsrv*ServerDLL*\\Server\Share

srv*DownstreamStore*\\Server\Share

srv*DownstreamStore1*DownstreamStoreN*\\Server\Share

srv*\\Server\Share

srv**\\Server\Share

srv**\\Server\Share*http://InternetSite

The following table describes elements of this syntax.

If a downstream store is not included, the debugger will load all symbol files from the specified server and share.

If a downstream store is included, the debugger will first look for a symbol file in this location. If the symbol file is not found, the debugger will locate the symbol file from the specified server and share and copy this file to the downstream store. The file will be copied to a subdirectory in the tree under DownstreamStore which corresponds to its location in the tree under \\Server\Share.

Instead of specifying the directory for the downstream store in the symbol path, you can call SymbolServerSetOptions with SSRVOPT_DOWNSTREAM_STORE to set the downstream store, then use the shortened syntax srv**\\Server\Share.

For example, to use SymSrv as the symbol server with a symbol store on \\mybuilds\mysymbols, set the following symbol path:

set _NT_SYMBOL_PATH= srv*\\mybuilds\mysymbols

To set the symbol path so that the debugger will copy symbol files from a symbol store on \\mybuilds\mysymbols to your local directory c:\localsymbols, use:

set _NT_SYMBOL_PATH=srv*c:\localsymbols*\\mybuilds\mysymbols

To use a cascading store, set the following symbol path:

set _NT_SYMBOL_PATH = srv*c:\localsymbols*\\server\store*\\mybuilds\mysymbols

In this example, SymSrv first looks for the file in c:\localsymbols. If it is found there, it will return a path to the file. Otherwise, SymSrv looks for the file in \\server\store. If it is found there, SymSrv copies the file to c:\localsymbols and returns a path to the file. Otherwise, SymSrv looks for the file in \\mybuilds\mysymbols. If it is found there, SymSrv copies the file to \\server\store, then to c:\localsymbols.

Compressed Files

SymSrv is compatible with symbol stores that contain compressed files, as long as this compression has been done with the Compress.exe tool that was distributed with the Windows Server 2003 Resource Kit. Compressed files should have an underscore as the last character in their file extensions (for example, module1.pd_ or module2.db_). For details, see Using SymStore.

Files are not uncompressed unless the target store is the bottom-most store in the path.

DbgHelp 6.1 and earlier.:  If the files in the master store are compressed, you must use a downstream store. SymSrv will uncompress all files before copying them to the downstream store.

Deleting the Cache

If you are using a downstream store as a cache, you can delete this directory at any time to save disk space.

It is possible to have a vast symbol store that includes symbol files for many different programs or Windows versions. If you upgrade the version of Windows used on your target computer, the cached symbol files will all match the earlier version. These cached files will not be of any further use, and therefore this might be a good time to delete the cache.

Downstream Stores

A downstream store can be useful in an environment where the symbols are located in a distant location on a potentially slow network. A group of users can create a common downstream store that is physically close to them, so that the slow file access occurs only the first time the symbol is accessed and copied to the downstream store. It is not necessary to specify a downstream store unless you are accessing symbols from an HTTP or HTTPS site or using compressed files on your store.

It is possible to declare the default downstream store as a flat directory, rather than a standard symbol tree structure. To do so, call the SymSetOptions function with SYMOPT_FLAT_DIRECTORY (this also sets the SSRVOPT_FLAT_DEFAULT_STORE option in SymSrv). Be sure to call SymSetHomeDirectory before doing so; otherwise, the symbol files can be written to the program directory.

Pointer Files

SymStore can create and use files that point to a target file rather than the target file itself. If a symbol store contains such a pointer file, the default is to copy the file from the location indicated in the pointer file to the store. To configure a store such that the pointer file is copied instead of the file it points to, create a file named Wantsptr.txt in the root of the target store. The contents of Wantsptr.txt are not important, only the presence of the file.

How SymSrv Locates Files

SymSrv creates a fully-qualified UNC path to the desired symbol file. This path begins with the path to the symbol store recorded in the _NT_SYMBOL_PATH environment variable. The SymbolServer routine is then used to identify the name of the desired file; this name is appended to the path as a directory name. Another directory name, consisting of the concatenation of the id, two, and three parameters passed to SymbolServer, is then appended; if any of these values are zero, they are omitted.

The resulting directory is searched for the symbol file, or a symbol store pointer file.

If this search is successful, the path is passed to the caller and TRUE is returned. If the file is not found, FALSE is returned.

Excluding Files from Symbols List

To exclude files from a symbols search, you can specify their names in Symsrv.ini or in the registry. To specify the files in Symsrv.ini, create a section named Exclusions and list the files. The file names can contain wildcards, as shown in the following example:

[Exclusions]
dbghelp.pdb
symsrv.*
mso*

Alternatively, you can store the files to be excluded in the registry. Create the following registry key: HKEY_LOCAL_MACHINE\Sofware\Microsoft\Symbol Server\Exclusions. Store each file name as a string value (REG_SZ) within this key. The name of the string value specifies the name of the file to be excluded. You can use the contents of the string value to store a comment describing why the file is being excluded.

Send comments about this topic to Microsoft

Build date: 9/25/2007