Skip to content

Symbol Server For Windows Debuggers#

Symbol Paths#

dbghelp.dll takes a ; delimited path list to locate symbol files

Default Search Paths#

  • _NT_SYMBOL_PATH environment variable
  • _NT_ALT_SYMBOL_PATH environment variable
  • directory that contains the corresponding module

Standard Directory Path#

  • syntax: [DirPath]
  • points to standard windows path; can be on a share/remote
  • search order is:
  • [DirPath]: looks for symbol file in immediate path
  • [DirPath]/[moduleExtension]: then path subdirectory based on module's file extension e.g. [DirPath]/dll, [DirPath]/exe, [DirPath]/sys
  • [DirPath]/symbols/[moduleExtension]: finally attempts hardcoded lookup in [DirPath]/symbols subdirectory e.g. [DirPath]/symbols/dll, [DirPath]/symbols/exe, [DirPath]/symbols/sys
  • Ex: [DirPath] := C:\foo\app, Module := bar.dll results in these lookups
  • C:\foo\app
  • C:\foo\app\dll
  • C:\foo\app\symbols\dll

Symbol Cache Path#

  • syntax: CACHE*[CachePath]
  • points to standard windows path but treated as a cache repository
  • searched like normal directory
  • if symbol's not found in cache but found in subsequent path in the chain, then symbol is copied and stored at in the cache location

Symbol Server Path#

  • Symbol Server: coordinates with debugger to deliver symbol files for specific binary from symbol stores; SymSrv is default MS implementation

  • Symbol Stores: centralized symbol file collection uniquely indexed w.r.t module binary; SymStore is default MS implementation

  • can contain any number of symbol files, corresponding to any number of programs or operating systems

  • can also contain binary files, which are particularly useful when debugging minidump files.

  • SRV*[SymStore]*SRV*[SymStore1]*SRV*[SymStoreN]: list of symbol store locations delimited by * that symbol server uses to locate symbol

  • Text Only
     > 
 > \[!note\] `SRV*` prefix is assumed if path points to symbol store
 > If `SRV*` prefix is missing but path points to a symbol server store, path is still treated as Symbol Server Path and `SRV*` is assumed
 > Symbol handler uses `pingme.txt` file in path's root directory to demarcate _symbol servers_ from normal folders

  • max 10 symbol stores after the "SRV*" prefix

  • precedence is from left/downstream stores to right/upstream stores

  • SymSrv searches from leftmost to rightmost symbol store until it finds a match

  • on match, SymSrv copies the file to every downstream store and opens always it from the leftmost store

Symbol Store Types#

  • C:\local\cache store: path to a directory on the client machine

  • <blank> store: two asterisks without text in-between (**) indicate default downstream store; default value is [CallingAppDir]\sym

  • \\server\share store: fully qualified UNC path to a share on a remote server

  • http://foo.app store: url to HTTP-based symbol hosting server

  • Text Only
     > 
 > \[!danger\] HTTP stores must be rightmost in a store list
 > HTTP-based stores are read-only; this means `SymSrv` can't copy symbols located an upstream store downstream to the HTTP store
 > This usually results in silent errors because the because of the broken symbol store chain
  • Text Only
     > 
 > \[!danger\] HTTP-based store cannot be the only store on the list
 > Symbol handler can't open a file on a website; if `SymSrv` encounters this, it attempts recovery by force copying to the default downstream store and opening from there
 > This may cause performance issues or silent failures if the `SymSrv` the downstream copy to the default store failes

SymSrv Examples#

  • use symbols from remote share
Batchfile
set _NT_SYMBOL_PATH=SRV*\\buildsShare\fooSymbols
  • copy symbols from remote to local folder
Batchfile
set _NT_SYMBOL_PATH=SRV*C:\localSymbols*\\buildsShare\fooSymbols
  • copy symbols from remote to default downstream store (usually C:\debuggers\sym)
Batchfile
set _NT_SYMBOL_PATH=SRV**\\buildsShare\fooSymbols
  • use multiple stores with cascading downstream copy
Batchfile
set _NT_SYMBOL_PATH=SRV*C:\localSymbols*\\nearbyServer\store*https://DistantServer
  • SymSrv searches C:\localSymbols; if found, return local file path
  • SymSrv searches \\nearbyServer\store; if found, copy file to C:\localSymbols, return local file path e.g. C:\localSymbols\bar.pdbg
  • SymSrv searches https://DistantServer; if found, copy file to \\nearbyServer\store and C:\localSymbols
  • multiple HTTP stores, caching, and local uncached symbols
Batchfile
set _NT_SYMBOL_PATH=CACHE*D:\scratch\symbols;SRV*https://msdl.microsoft.com/download/symbols;SRV*https://driver-symbols.nvidia.com;SRV*https://download.amd.com/dir/bin

set _NT_SYMBOL_PATH=SRV*C:\Symbols*\\Machine1\Symbols*https://SymProxyName/Symbols;SRV*C:\WebSymbols*https://msdl.microsoft.com/download/symbols
set _NT_SYMBOL_PATH=\\notCached\share;SRV*C:\cached\localSymbolDir*https://msdl.microsoft.com/download/symbols;CACHE*C:\cached\localSymbolDir;\\alsoCached\share
  • symchk.exe: use to download/verify symbols

[!example]- symchk.exe /r C:WindowsSystem32 /s %_NT_SYMBOL_PATH%

  • downloads symbols for every component in C:\Windows\System32
  • /r C:\Windows\System32: recursive symbol search for all files in the System32 and its subfolders
  • /s %_NT_SYMBOL_PATH%: specifies the symbol path to use for symbol resolution