|
| 1 | +--- |
| 2 | +title: "AddressSanitizer: vcasan.lib" |
| 3 | +description: "Technical description of vcasan.lib." |
| 4 | +ms.date: 01/05/2021 |
| 5 | +f1_keywords: ["ASan","sanitizers","AddressSanitizer", "vcasan"] |
| 6 | +helpviewer_keywords: ["ASan","sanitizers","AddressSanitizer","vcasan.lib","vcasan","vcasand.lib","libvcasan.lib","libvcasand.lib"] |
| 7 | +--- |
| 8 | + |
| 9 | +# Visual Studio ASan extended functionality library (VCASan) |
| 10 | + |
| 11 | +The VCAsan libraries exist to enable extended Visual Studio features when debugging with ASan. The library is linked any time AddressSanitizer is enabled with MSVC. The library allows for Visual Studio to display AddressSanitizer-specific message pop-ups, as well as enabling the executable to generate crash dumps when an ASan report is created. |
| 12 | + |
| 13 | +## VCAsan library inventory |
| 14 | + |
| 15 | +| Runtime Flag | VCAsan Version | |
| 16 | +|--------------|----------------| |
| 17 | +| MT | libvcasan.lib | |
| 18 | +| MD | vcasan.lib | |
| 19 | +| MTd | libvcasand.lib | |
| 20 | +| MDd | vcasand.lib | |
| 21 | + |
| 22 | +## VCAsan library features |
| 23 | + |
| 24 | +### Rich ASan error report window in Visual Studio IDE |
| 25 | + |
| 26 | +VCAsan registers a callback within the ASan runtime with the [ASan interface function `__asan_set_error_report_callback`.](https://github.com/llvm/llvm-project/blob/1ba5ea67a30170053964a28f2f47aea4bb7f5ff1/compiler-rt/include/sanitizer/asan_interface.h#L256) If an ASan report is generated, this callback is used to throw an exception that will be caught by Visual Studio. The data in the exception is used to generate the Visual Studio message that is displayed to the user within the IDE. |
| 27 | +> [!NOTE] |
| 28 | +> Since VCAsan registers this callback function, if user code calls this function a second time it is possible for the user registered callback to overwrite the VCAsan callback registration. This would result in the loss of the ASan error message window in the Visual Studio IDE. Since the registration occurs in a race, it is also possible for the user's call to register the callback to be lost. If you encounter either problem please file a feedback ticket with the [Visual Studio developer community](https://developercommunity.visualstudio.com). |
| 29 | +
|
| 30 | +### Save crash dumps after ASan error report |
| 31 | + |
| 32 | +When a VCasan library is linked it is possible for the user to generate a crash dump when an ASan error report is generated. To enable this feature, the user must set an environment variable as follows: |
| 33 | + |
| 34 | +`set ASAN_SAVE_DUMPS="MyFileName.dmpx"` |
| 35 | + |
| 36 | +This will save a snapshot file when an error is caught by the AddressSanitizer. The meta-data that is saved in the dump file is parsed by the new Visual Studio IDE. You can set this variable on a per-test basis and store these binary artifacts and then view these in the IDE with proper source indexing. |
0 commit comments