AddressSanitizer

Overview

The C & C++ languages are powerful, but can suffer from a class of bugs that affect program correctness and program security. Starting in Visual Studio 2019 version 16.9, the Microsoft C/C++ compiler (MSVC) and IDE supports the AddressSanitizer. AddressSanitizer (ASan) is a compiler and runtime technology that exposes many hard-to-find bugs with zero false positives:

Use AddressSanitizer to reduce your time spent on:

  • Basic correctness
  • Cross platform portability
  • Security
  • Stress testing
  • Integrating new code

AddressSanitizer, originally introduced by Google, is a powerful alternative to both /RTC (Runtime error checks) and /analyze (Static analysis). It provides run-time bug-finding technologies that use your existing build systems and existing test assets directly.

AddressSanitizer is integrated with the Visual Studio project system, the CMake build system, and the IDE. Projects can enable AddressSanitizer by setting a project property, or by using one extra compiler option: /fsanitize=address. The new option is compatible with all levels of optimization and configurations of x86 and x64. However, it's incompatible with edit-and-continue, incremental linking, and /RTC.

Starting in Visual Studio 2019 version 16.9, Microsoft's AddressSanitizer technology enables integration with the Visual Studio IDE. The functionality can optionally create a crash dump file when the sanitizer finds a bug at runtime. If you set the ASAN_SAVE_DUMPS=MyFileName.dmp environment variable before you run your program, a crash dump file gets created with extra metadata for efficient post-mortem debugging of precisely diagnosed bugs. These dump files make extended use of the AddressSanitizer easier for:

  • Local machine testing,
  • On-premise distributed testing, and
  • Cloud-based workflows for testing.

Install the AddressSanitizer

The AddressSanitizer IDE integration and libraries get installed by default with C++ workloads in the Visual Studio Installer. However, if you're upgrading from an older version of Visual Studio 2019, use the Installer to enable ASan support after the upgrade:

Visual Studio Installer screenshot highlighting the C++ AddressSanitizer component

You can choose Modify on your existing Visual Studio installation from the Visual Studio Installer to get to the screen above.

Note

If you run Visual Studio on the new update but haven't installed ASan, you'll get an error when you run your code:

LNK1356: cannot find library 'clang_rt.asan_dynamic-i386.lib'

Use the AddressSanitizer

Start building your executables with the /fsanitize=address compiler option using any of these common development methods:

  • Command line builds
  • Visual Studio project system
  • Visual Studio CMake integration

Recompile, then run your program normally. This code generation exposes many types of precisely diagnosed bugs. These errors get reported in three ways: in the debugger IDE, on the command line, or stored in a new type of dump file for precise off-line processing.

Microsoft recommends using the AddressSanitizer in these three standard workflows:

This article covers the information you require to enable the three workflows listed above. The information is specific to the platform-dependent Windows 10 implementation of the AddressSanitizer. This documentation supplements the excellent documentation from Google, Apple, and GCC already published.

Note

Current support is limited to x86 and x64 on Windows 10. Send us feedback on what you'd like to see in future releases. Your feedback helps us prioritize other sanitizers for the future, such as /fsanitize=thread, /fsanitize=leak, /fsanitize=memory, /fsanitize=undefined, or /fsanitize=hwaddress. You can report bugs here if you run into issues.

Use the AddressSanitizer from a developer command prompt

Use the /fsanitize=address compiler option in a developer command prompt to enable compiling for the AddressSanitizer runtime. The /fsanitize=address option is compatible with all existing C++ or C optimization levels (for example, /Od, /O1, /O2, /O2 /GL, and PGO). The option works with static and dynamic CRTs (for example, /MD, /MDd, /MT, and /MTd). It works whether you create an EXE or a DLL. Debug information is required for optimal formatting of call stacks. In the example below, cl /fsanitize=address /Zi is passed on the command line.

The AddressSanitizer libraries (.lib files) get linked for you automatically. For more information, see AddressSanitizer language, build, and debugging reference.

Example - basic global buffer overflow

// basic-global-overflow.cpp
#include <stdio.h>
int x[100];
int main() {
    printf("Hello!\n");
    x[100] = 5; // Boom!
    return 0;
}

Using a developer command prompt for Visual Studio 2019, compile main.cpp using /fsanitize=address /Zi

Screenshot of a command prompt showing the command to compile with AddressSanitizer options.

When you run the resulting main.exe at the command line, it creates the formatted error report seen below.

Consider the overlaid, red boxes that highlight seven key pieces of information:

Screenshot of the debugger showing a basic global overflow error.

Red highlights, from top to bottom

  1. The memory safety bug is a global-buffer-overflow.
  2. There were 4 bytes (32 bits) stored outside any user-defined variable.
  3. The store took place in function main() defined in file basic-global-overflow.cpp on line 7.
  4. The variable named x gets defined in basic-global-overflow.cpp on line 3, starting at column 8
  5. This global variable x is of size 400 bytes
  6. The exact shadow byte describing the address targeted by the store had a value of 0xf9
  7. The shadow byte legend says 0xf9 is an area of padding to the right of int x[100]

Note

The function names in the call stack are produced through the LLVM symbolizer that's invoked by the runtime upon error.

Use the AddressSanitizer in Visual Studio

AddressSanitizer is integrated with the Visual Studio IDE. To turn on the AddressSanitizer for an MSBuild project, right-click on the project in Solution Explorer and choose Properties. In the Property Pages dialog, select Configuration Properties > C/C++ > General, then modify the Enable AddressSanitizer property. Choose OK to save your changes.

Screenshot of the Property Pages dialog showing the Enable AddressSanitizer property.

To build from the IDE, opt out of any incompatible options. For an existing project compiled by using /Od (or Debug mode), you may need to turn off these options:

To build and run the debugger, enter F5. You'll see this window in Visual Studio:

Screenshot of the debugger showing a global buffer overflow error.

Using the AddressSanitizer from Visual Studio: CMake

To enable the AddressSanitizer for a CMake project created to target Windows, take these steps:

  1. Open the Configurations dropdown in the toolbar at the top of the IDE and select Manage Configurations.

    Screenshot of the CMake configuration dropdown.

    That selection opens the CMake Project Settings editor, which is saved in a CMakeSettings.json file.

  2. Choose the Edit JSON link in the editor. This selection switches the view to raw JSON.

  3. Add the property: “addressSanitizerEnabled”: true

    This image is of CMakeSettings.json after that change:

    Screenshot of the text editor view of CMakeSettings.json.

  4. Enter Ctrl+S to save this JSON file, then enter F5 to recompile and run under the debugger.

This screenshot captures the error from the CMake build.

Screenshot of the CMake build error message.

AddressSanitizer crash dumps

We introduced new functionality in the AddressSanitizer for use with cloud and distributed workflows. This functionality allows offline viewing of an AddressSanitizer error in the IDE. The error gets overlaid on top of your source, just as you would experience in a live debug session.

These new dump files can lead to efficiencies when analyzing a bug. You don't need to rerun, or find remote data or look for a machine that went off-line.

To produce a new type of dump file that can be viewed in Visual Studio on another machine at a later date:

set ASAN_SAVE_DUMPS=MyFileName.dmp

Starting with Visual Studio 16.9 you can display a precisely diagnosed error, stored in your *.dmp file, on top of your source code.

This new crash dump functionality enables cloud-based workflows, or distributed testing. It can also be used to file a detailed, actionable bug in any scenario.

Example errors

AddressSanitizer can detect several kinds of memory misuse errors. Here are many of the runtime errors reported when you run your binaries compiled by using the AddressSanitizer (/fsanitize=address) compiler option:

For more information about the examples, see AddressSanitizer error examples.

Differences with Clang 12.0

MSVC currently differs from Clang 12.0 in two functional areas:

  • stack-use-after-scope - this setting is on by default and can't be turned off.
  • stack-use-after-return - this functionality requires an extra compiler option, and isn't available by only setting ASAN_OPTIONS.

These decisions were made to reduce the test matrix required to deliver this first version.

Features that could lead to false positives in Visual Studio 2019 16.9 weren't included. That discipline enforced the effective testing integrity necessary when considering interop with decades of existing code. More capabilities may be considered in later releases:

For more information, see Building for the AddressSanitizer with MSVC.

Existing industry documentation

Extensive documentation already exists for these language and platform-dependent implementations of the AddressSanitizer technology.

This seminal paper on the AddressSanitizer describes the implementation.

See also

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