Advanced SymSrv Use
SymSrv can deliver 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 minidumps).
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 be used to 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. For more information, see HTTP Symbol Stores.
To use this symbol server, symsrv.dll must be installed in the same directory as the debugger. The symbol path must be set in one of the following ways:
set _NT_SYMBOL_PATH = symsrv*ServerDLL*DownstreamStore*\\Server\Share set _NT_SYMBOL_PATH = symsrv*ServerDLL*\\Server\Share set _NT_SYMBOL_PATH = srv*DownstreamStore*\\Server\Share set _NT_SYMBOL_PATH = srv*\\Server\Share
The parts of this syntax are explained as follows:
This keyword must always appear first. It indicates to the debugger that this item is a symbol server, not just a normal symbol directory.
Specifies the name of the symbol server DLL. If you are using the SymSrv symbol server, this will always be symsrv.dll.
This is shorthand for symsrv*symsrv.dll.
Specifies the downstream store. This is a local directory or network share that will be used to cache individual symbol files.
You can specify more than one downstream store, separated by asterisks. Multiple downstream stores are explained in Cascading Downstream Stores further down on this page.
If you include two asterisks in a row where a downstream store would normally be specified, then the default downstream store is used. This store will be located in the sym subdirectory of the home directory. The home directory defaults to the debugger installation directory; this can be changed by using the !homedir extension or by setting the DBGHELP_HOMEDIR environment variable.
If DownstreamStore specifies a directory that does not exist, SymStore will attempt to create it.
If the DownstreamStore parameter is omitted and no extra asterisk is included -- in other words, if you use srv with exactly one asterisk or symsrv with exactly two asterisks -- then no downstream store will be created. The debugger will load all symbol files directly from the server, without caching them locally.
Note If you are accessing symbols from an HTTP or HTTPS site, or if the symbol store uses compressed files, a downstream store is always used. If no downstream store is specified, one will be created in the sym subdirectory of the home directory.
Specifies the server and share of the remote symbol store.
If a downstream store is used, the debugger will first look for a symbol file in this store. If the symbol file is not found, the debugger will locate the symbol file from the specified Server and Share, and then cache a copy of this file in 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.
The symbol server does not have to be the only entry in the symbol path. If the symbol path consists of multiple entries, the debugger checks each entry for the needed symbol files, in order (from left to right), regardless of whether a symbol server or an actual directory is named.
Here are some examples. To use SymSrv as the symbol server with a symbol store on \\mybuilds\mysymbols, set the following symbol path:
set _NT_SYMBOL_PATH= symsrv*symsrv.dll*\\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:
To set the symbol path so that the debugger will copy symbol files from the HTTP site www.company.com/manysymbols to a local network directory \\localserver\myshare\mycache, use:
This last example can also be shortened as such:
In addition, the symbol path can contain several directories or symbol servers, separated by semicolons. This allows you to locate symbols from multiple locations (or even multiple symbol servers). If a binary has a mismatched symbol file, the debugger cannot locate it using the symbol server because it checks only for the exact parameters. However, the debugger may find a mismatched symbol file with the correct name, using the traditional symbol path, and successfully load it. Even though the file is technically not the correct symbol file, it might provide useful information.
SymSrv is compatible with symbol stores that contain compressed files, as long as this compression has been done with the compress.exe tool, which is available here. Compressed files should have an underscore as the last character in their file extensions (for example, module1.pd_ or module2.db_). For details, see SymStore.
If the files on the store are compressed, you must use a downstream store. SymSrv will uncompress all files before caching them on the downstream store.
If you are using a DownstreamStore 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.
You can specify any number of downstream stores, separated by asterisks. These stores are known as cascading symbol stores.
After the initial srv* or symsrv*ServerDLL*, each subsequent token represents a symbol location. The token furthest left is checked first. An empty token -- indicated by two asterisks in a row, or by an asterisk at the end of the string -- represents the default downstream store.
Here is an example of a symbol path that uses two downstream stores to hold information from the main symbol store being accessed. These could be called the master store, the mid-level store, and the local cache:
In this scenario, SymSrv will first look in c:\localcache for a symbol file. If it is found there, it will return a path to it. If it is not found there, it will look in \\interim\store. If the symbol file is found there, SymSrv will copy it to c:\localcache and return the path. If it is not found there, SymSrv will look in the Microsoft public symbol store at http://msdl.microsoft.com/download/symbols; if the file is found there, SymSrv will copy it to both \\interim\store and c:\localcache.
A similar behavior would be obtained by using the following path:
In this case, the local cache is the default downstream store and the master store is an internet site. A mid-level store of \\interim\store has been specified for use in between the other two.
When SymSrv processes a path that contains cascading stores, it will skip any store that it cannot read or write to. So if a share goes down, it will copy the file to the store downstream from the missing store without any error. A nice side effect of this error is that the user can specify more than one master store that feeds a single stream of downstream stores as long as the master stores are not writable.
When a compressed symbol file is retrieved from the master store, it will be stored in compressed form in any mid-level store. The file will be uncompressed in the bottom-most store in the path.
Another way to create a local cache of symbols is by using the cache*localsymbolcache string in your symbol path. This is not part of the symbol server element, but a separate element in your symbol path. The debugger will use the specified directory localsymbolcache 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, the following symbol path will not cache symbols taken from \\someshare. It will use c:\mysymbols to cache symbols taken from \\anothershare, because the element beginning with \\anothershare appears to the right of the cache*c:\mysymbols element. It will also use c:\mysymbols to cache symbols taken from the Microsoft public symbol store, because of the usual syntax used by the symbol server (srv with two or more asterisks). Moreover, if you subsequently use the .sympath+ command to add additional locations to this path, these new elements will also be cached, since they will be appended to the right side of the path.
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 is zero, they are omitted.
The resulting directory is searched for the symbol file, or a symbol store pointer file.
If this search is successful, SymbolServer passes the path to the caller and returns TRUE. If the file is not found, SymbolServer returns FALSE.
The AgeStore tool can be used to delete cached files that are older than a specified date, or to reduce the contents of the cache below a specified size. This can be useful if your downstream store is too large. For details, see AgeStore.
Build date: 11/16/2013