You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
C & C++ are powerful languages, but they can suffer from different types of bugs which affect program correctness and program security. Starting with Visual Studio 2019 16.9, the Microsoft Visual C++ compiler and IDE support Address Sanitizer technology to help light up hard-to-find bugs.
12
12
13
-
We describe a new compiler flag `-fsanitize=address` which may result in exposing hidden [errors](#errors) in your code, not exposed by current testing.
13
+
After choosing the (!!!asan installer option!!!), simply select the Address Sanitizer dropdown in your project properties, or set the `-fsanitize=address` compiler switch on the command line, or use Visual Studio cmake integration, recompile, and then run your program as normal to light up [bugs](#errors) right in the debugger.
14
+
15
+
For CI/CD systems use the ASAN_SAVE_DUMPS environment variable to store ASAN crash dumps for post-mortem debugging.
14
16
15
17
Using this flag can reduce your time spent on:
16
18
@@ -20,19 +22,19 @@ Using this flag can reduce your time spent on:
20
22
- Stress testing
21
23
- Integrating new source code
22
24
23
-
Building with `-fsanitize=address`and using your existing test assets, is a highly recommended step in properly testing your software. With just a [simple recompile](#Simple-command-line-interface), you can expose difficult to find, errors with **no false positives**. This class of errors is not found with [/RTC](https://docs.microsoft.com/en-us/cpp/build/reference/rtc-run-time-error-checks?view=msvc-160)or [/analyze](https://docs.microsoft.com/en-us/cpp/code-quality/code-analysis-for-c-cpp-overview?view=msvc-160).
25
+
The Address Sanitizer is a compiler and runtime runtime [introduced by Google](https://www.usenix.org/conference/atc12/technical-sessions/presentation/serebryany). Starting with Visual Studio 2019 16.9 this technology is offered in the Visual C++ compiler toolchain. Many projects can enable Address Sanitizer with a project setting, or a single additional compiler switch. There are known limitations in certain (!!! link !!!) compilation modes (incremental linking, or the [/RTC](https://docs.microsoft.com/en-us/cpp/build/reference/rtc-run-time-error-checks?view=msvc-160)switch, for example), but otherwise all configurations of x86 and x64 are supported.
24
26
27
+
`-fsanitize=address` is a powerful alternative to [/RTC](https://docs.microsoft.com/en-us/cpp/build/reference/rtc-run-time-error-checks?view=msvc-160), and in addition to [/analyze](https://docs.microsoft.com/en-us/cpp/code-quality/code-analysis-for-c-cpp-overview?view=msvc-160) provides compile-time and run-time bug-finding technologies which leverage your existing build systems and existing test assets.
25
28
26
-
## Developer Message
29
+
## Using the Address Sanitizer
27
30
28
-
The Address Sanitizer is a compiler based technology targeting a runtime [introduced by Google](https://www.usenix.org/conference/atc12/technical-sessions/presentation/serebryany). This [compiler](#Compiler) and [runtime](#address-sanitizer-runtimes) technology has become the "defacto" industry standard for finding memory safety issues. We now offer this technology as a fully supported feature in Visual Studio for the Windows platform. If your existing code compiles with our current Windows compiler, then it will compile with the extra flag -fsanitize=address under any level of optimization and all other compatible flags (e.g., /RTC is not compatible, yet).
31
+
!!! We need a picture of the installer option here and mention it's required first !!!
29
32
30
33
Microsoft recommends using the Address Sanitizer in these **three standard workflows**:
31
34
32
35
-**Developer inner loop**
33
36
- Visual Studio - Command line
34
-
- Visual Studio - Project system with integrated IDE error reporting support.
35
-
37
+
- Visual Studio - Project system with integrated IDE error reporting support
36
38
37
39
-**CI/CD** - continuous integration / continuous development
38
40
- CMake
@@ -42,34 +44,108 @@ Microsoft recommends using the Address Sanitizer in these **three standard workf
This MSDN article will cover all the information needed to enable your builds for any of the three workflows listed above. The information will be specific to the Microsoft Windows 10 platform and supplement existing documentation from [Google, Apple and GCC](#Google,-Apple-and-GCC-documentation). We start with a simple command line use of the compiler and linker.
47
+
This article will cover all the information needed to enable your builds for any of the three workflows listed above. The information will be specific to the Microsoft Windows 10 platform and supplement existing documentation from [Google, Apple and GCC](#Google,-Apple-and-GCC-documentation).
46
48
47
49
> [!NOTE] Current support is limited to x86 and AMD64 on Windows 10. **Customer feedback** would help us prioritize shipping these sanitizers in the future: -fsanitize=thread, -fsanitize=leak, -fsanitize=memory, -fsanitize=hwaddress or -fsanitize=undefined.
48
50
51
+
## Using the Address Sanitizer from a Developer Command Prompt
52
+
53
+
Compile with `-fsanitize=address` to enable Address Sanitizer. The compiler flag `-fsanitize=address` is compatible with all existing C++ or C optimization levels (e.g., /Od, /O1, /O2, /O2 /GL and PGO), works with static and dynamic CRTs (e.g. /MD, /MDd, /MT, /MTd) and can be used to create a .EXE or .DLL. Debug information is required for the Address Sanitizer runtime to print correct call stacks on errors; In this example we pass `-Zi`.
54
+
55
+
The Address Sanitizer libraries (.lib files) will be linked in for you. For more detail, and for guidelines on partitioned build systems, see [building to target the Address Sanitizer runtime.](.\ASan-building.md).
56
+
57
+
```cpp
58
+
#include<iostream>
59
+
int x[100];
60
+
intmain() {
61
+
std::cout << "Hello!" << std::endl;
62
+
x[100] = 5; // Boom!
63
+
return 0;
64
+
}
65
+
66
+
```
67
+
68
+
C:\> cl main.cpp -fsanitize=address /Zi
69
+
70
+
!!! Show media/something here !!! with the red boxes. And describe the red boxes, and the note about the symbolizer.
71
+
72
+
## Using the Address Sanitizer from Visual Studio
73
+
74
+
!!! todo, make a different example with a different error, animated gif of IDE, and list of instructions !!!
75
+
76
+
## Using the Address Sanitizer from Visual Studio: CMake
77
+
78
+
!!! todo, make a different example with a different error, animated gif of CMake, and list of instructions !!!
79
+
80
+
## Offline Address Sanitizer crash dumps
81
+
82
+
Address Sanitizer exceptions are triggered one of the many [errors](#errors) are detected at runtime. When run from the command line the Address Sanitizer runtime produces text output with error information. When run from the Visual Studio IDE the debugger displays the error information.
83
+
84
+
To produce a dump file of the error which can be debugged offline, set an environment variable which is consumed by the Address Sanitizer runtime.
85
+
86
+
`set ASAN_SAVE_DUMPS="MyFileName.dmpx"`
87
+
88
+
Upon error, your application will produce MyFileName.dmpx which is a [dump file](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/proc_snap/export-a-process-snapshot-to-a-file) that can be opened and debugged using Visual Studio.
89
+
90
+
**Note** that like all other dump files, [debugging symbols](https://docs.microsoft.com/en-us/windows/win32/dxtecharts/debugging-with-symbols) must be available and must match the version of the source compiled.
91
+
92
+
93
+
## Error types
94
+
95
+
The following list of runtime errors can be exposed when you run your binaries compiled Address Sanitizer:
- **stack-use-after-scope** - this is on by default and can't be turned off.
120
+
- **stack-use-after-return** - this is not available by just setting ASAN_OPTIONS
121
+
122
+
See [Building for the Address Sanitizer with MSVC](.\asan-building.md).These decisions were made to reduce the test matrix used to ship this first version.
49
123
50
-
## Simple command line interface
124
+
## Exiting industry documentation
51
125
52
-
Adding the flag -fsanitize=address to your command line (with /Zi to emit debug info.) is all you need to compile and automatically link all required libraries. This can be used to create an .EXE or DLL. The compiler flag `-fsanitize=address` is compatible with all existing C++ or C optimization levels (e.g., /Od, /O1, /O2, /O2 /GL and PGO).
126
+
Extensive documentation already exists for these language and platform dependent implementations of the Address Sanitizer technology.
This seminal paper on the [Address Sanitizer](https://www.usenix.org/system/files/conference/atc12/atc12-final39.pdf) describes the implementation.
57
133
58
-
The compiler will default to automatically linking main.exe with the static versions of the Address Sanitizer runtime binaries and the static [CRT](https://docs.microsoft.com/en-us/cpp/c-runtime-library/crt-library-features?view=msvc-160). Throwing [/MD](https://docs.microsoft.com/en-us/cpp/build/reference/md-mt-ld-use-run-time-library?view=msvc-160) flag will change the default link behavior and cause the dynamic versions of the libraries to be used instead.
134
+
!!! is this where we should mention that we don't implement the entire complete feature set? !!!
59
135
60
-
For more partitioned build systems, the following command lines show examples of the required compile and link lines to produce an "instrumented" main.exe.
136
+
## See also
61
137
62
-
**Creating a main.exe with an explicit link line.**
138
+
- [Building for the Address Sanitizer with MSVC](.\asan-building.md)
C:\> link -debug -incremental:no main.obj file2.obj file3.obj
142
+
These structure all further details into the tools and the run times they target.
67
143
68
-
The compiler requires opting into -Zi for debug information and the linker requires -debug to emit that debug information. One caveat is that `-debug` defaults to producing code for future incremental linking for rapid iterative development. which is not compatible with the stack walker used by the Address Sanitizer runtime. The Address Sanitizer requires `link -debug -incremental:no` and it will warn appropriately.
144
+
----
69
145
70
-
See the section on [building to target the Address Sanitizer runtime.](.\ASan-building.md) for more detail.
146
+
## STUFF TO KEEP -- remove later!!!!!
71
147
72
-
## Errors ##
148
+
## Viewing Address Saniziter Errors ##
73
149
74
150
There are three ways your code can generate error reports:
75
151
@@ -81,6 +157,7 @@ These types of reports can be generated for many types of [errors found at runti
81
157
82
158
### Example
83
159
160
+
!!! Jim, I think we need a simpler example here. !!!
84
161
The following source code is **safe by coincidence**. It will **not** fail at runtime. The Windows 10, 16.9 version of the C runtime, will pad the 13 bytes requested, in order to facilitate alignment for subsequent calls to alloca.
85
162
86
163
```cpp
@@ -134,71 +211,10 @@ Consider the following error found in our cached version of spec2k6\povray where
134
211
135
212
136
213
137
-
### Snapshot files
138
-
139
-
There's a powerful feature for workflows that need to retain detailed error information for processing errors off-line. If you **simply** set an environment variable, then your .EXE or .DLL will create a snap shot file.
140
-
141
-
`set ASAN_SAVE_DUMPS="MyFileName.dmpx"`
142
-
143
-
Upon error, your application will produce MyFileName.dmpx which is a [dump file](https://docs.microsoft.com/en-us/previous-versions/windows/desktop/proc_snap/export-a-process-snapshot-to-a-file) containing extra meta-data. This meta-data is used to formatting an Address Santiizer error in the IDE on top you your source code. This snapshot file can be displayed later (possibly on another machine), in a newer version of the Visual Studio IDE. The IDE will use the meta-data to display the exact error on the exact source line as it would be seen in a live debug session.
144
-
145
-
**Note** that this will require [symbols](https://docs.microsoft.com/en-us/windows/win32/dxtecharts/debugging-with-symbols) from a PDB. This PDB must be produced from the version of the source you compiled to produce the executable that contained the Address Sanitizer error. That insures the position of the error, and the call stack will be correct.
146
214
147
215
### VCASan library
148
216
149
217
The flag -fsanitize=address automatically links a new static library to your .EXE or .DLL. This static library will automatically produce:
150
218
151
219
- In memory meta-data for directly interfacing with the VS IDE, [while debugging](#Error-types).
152
220
- An optional [snap shot file](#Snapshot-files) with the same IDE meta-data.
153
-
154
-
These library features are detailed further in the section for [vcasan.lib](.\address-sanitizer-vcasan.md)
155
-
156
-
## Error types
157
-
158
-
The following list of runtime errors can be exposed when you run your binaries compiled -fsanitize=address. A drill down of each class of error, provides source code and Visual Stud screen shots. There are over 30 examples, with screen shots, within the following:
- **stack-use-after-scope** - this is on by default and can't be turned off.
183
-
- **stack-use-after-return** - this is not available by just setting ASAN_OPTIONS
184
-
185
-
See [Building for the Address Sanitizer with MSVC](.\asan-building.md).These decisions were made to reduce the test matrix used to ship this first version.
186
-
187
-
## Exiting industry documentation
188
-
189
-
Extensive documentation already exists for these language and platform dependent implementations of the Address Sanitizer technology.
0 commit comments