Visual Studio AddressSanitizer extended functionality library (VCAsan)

The VCAsan*.lib libraries implement extended debugger IDE features in Visual Studio. These features allow the IDE to show AddressSanitizer errors in live debug sessions, or offline by saving a crash dump file with metadata. The library is linked any time AddressSanitizer is enabled by the MSVC compiler.

VCAsan library inventory

Runtime option VCAsan link library
/MT libvcasan.lib
/MD vcasan.lib
/MTd libvcasand.lib
/MDd vcasand.lib

VCAsan library features

Rich AddressSanitizer error report window in Visual Studio IDE

The VCAsan library registers a callback within the AddressSanitizer runtime by using the interface function __asan_set_error_report_callback. If an AddressSanitizer report is generated, this callback gets used to throw an exception that's caught by Visual Studio. Visual Studio uses the exception data to generate the message that's displayed to the user in the IDE.

Note

The VCAsan library registers a callback function in the AddressSanitizer runtime. If your code calls this registration function a second time, it overwrites the VCAsan library callback registration. This results in the loss of all Visual Studio IDE integration. You'll revert back to the default IDE user experience. It's also possible for a user's call that registers their callback to be lost. If you encounter either problem, file a bug.

Save AddressSanitizer errors in a new type of crash dump file

When you link the VCAsan library to your executable, users can enable it to generate a crash dump at runtime. Then the AddressSanitizer runtime produces a dump file when a diagnosed error occurs. To enable this feature, the user sets the ASAN_SAVE_DUMPS environment variable by using a command such as this one:

set ASAN_SAVE_DUMPS=MyFileName.dmp

The file must have a .dmp suffix to follow the Visual Studio IDE conventions.

Here's what happens when a dump file is specified for ASAN_SAVE_DUMPS: If an error gets caught by the AddressSanitizer runtime, it saves a crash dump file that has the metadata associated with the error. The debugger in Visual Studio version 16.9 and later can parse the metadata that's saved in the dump file. You can set ASAN_SAVE_DUMPS on a per-test basis, store these binary artifacts, and then view them in the IDE with proper source indexing.

See also

AddressSanitizer overview
AddressSanitizer known issues
AddressSanitizer build and language reference
AddressSanitizer runtime reference
AddressSanitizer shadow bytes
AddressSanitizer cloud or distributed testing
AddressSanitizer error examples