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.