Crate symsrv

symsrv

This crate lets you download and cache symbol files from symbol servers, according to the rules from the _NT_SYMBOL_PATH environment variable.

It exposes an async API. Internally it uses reqwest and tokio.

The downloaded symbols are stored on the file system. No automatic expiration or eviction is performed. If you want to enforce a cache size limit or expire old files, you can observe cache file creations and accesses with the SymsrvObserver trait, and then write your own implementation for automatic file cleanup.

Microsoft Documentation

• Advanced SymSrv Use

Example

use symsrv::SymsrvDownloader;

// Parse the _NT_SYMBOL_PATH environment variable.
let symbol_path_env = symsrv::get_symbol_path_from_environment();
let symbol_path = symbol_path_env.as_deref().unwrap_or("srv**https://msdl.microsoft.com/download/symbols");
let parsed_symbol_path = symsrv::parse_nt_symbol_path(symbol_path);

// Create a downloader which follows the _NT_SYMBOL_PATH recipe.
let mut downloader = SymsrvDownloader::new(parsed_symbol_path);
downloader.set_default_downstream_store(symsrv::get_home_sym_dir());

// Download and cache a PDB file.
let local_path = downloader.get_file("dcomp.pdb", "648B8DD0780A4E22FA7FA89B84633C231").await?;

// Use the PDB file.
open_pdb_at_path(&local_path);

Structs

• SymsrvDownloader
  Obtains symbol files (PDBs + binary files) according to the instructions in the symbol path.

Enums

• CabExtractionError
  The error type used in the observer notification SymsrvObserver::on_cab_extraction_failed.
• CachePath
  A regular cache directory or a marker for the “default downstream store”.
• DownloadError
  The error type used in the observer notification SymsrvObserver::on_download_failed.
• Error
  The error type used for results returned from SymsrvDownloader::get_file.
• NtSymbolPathEntry
  The parsed representation of one entry in the (semicolon-separated list of entries in the) _NT_SYMBOL_PATH environment variable. The syntax of this string is documented at https://docs.microsoft.com/en-us/windows-hardware/drivers/debugger/advanced-symsrv-use.

Traits

• SymsrvObserver
  A trait for observing the behavior of a SymsrvDownloader. This can be used for logging, displaying progress bars, expiring cached files, etc.

Functions

• get_home_sym_dir
  Returns the absolute path to the ~/sym directory. This is a reasonable default for the “default downstream store”. The return value can be directly passed to SymsrvDownloader::set_default_downstream_store.
• get_symbol_path_from_environment
  Reads the _NT_SYMBOL_PATH environment variable into a string.
• parse_nt_symbol_path
  Parse the value of the _NT_SYMBOL_PATH variable. The format of this variable is a semicolon-separated list of entries, where each entry is an asterisk-separated hierarchy of symbol locations which can be either directories or server URLs.