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
asan-top-level: Fix typos, a few phrasing items, fixing page links, and fixing images (#3)
* first batch of changes, and trying to get pictures to show up
* picture again
* Rest of pictures
* fixing example links
* fixing all links
* extra period
The C & C++ languages are powerful, but can suffer from a class of bugs which affect **program correctness** and **program security**. Starting with Visual Studio 2019 16.9, the Microsoft Visual C++ compiler and IDE, support the Address Sanitizer technology which will light up [hard-to-find bugs](#error-types) with **zero false positives**.
13
+
The C & C++ languages are powerful, but can suffer from a class of bugs which affect **program correctness** and **program security**. Starting with Visual Studio 2019 16.9 the Microsoft Visual C++ compiler and IDE support the Address Sanitizer technology which will light up [hard-to-find bugs](#error-types) with **zero false positives**.
14
14
15
-
Using this flag can reduce your time spent on:
15
+
Use this flag to reduce your time spent on:
16
16
17
17
- Basic correctness
18
18
- Cross platform portability
19
19
- Security
20
20
- Stress testing
21
21
- Integrating new code
22
22
23
-
The Address Sanitizer is a compiler and runtime [introduced by Google](https://www.usenix.org/conference/atc12/technical-sessions/presentation/serebryany). Compiling with `cl -fsanitize=addres` is a powerful alternative to both [/RTC](..\..\build\reference\rtc-run-time-error-checks.md), and [/analyze](../..\code-quality/code-analysis-for-c-cpp-overview.md). It provides run-time bug-finding technologies which directly leverage your existing build systems and existing test assets.
23
+
The Address Sanitizer is a compiler and runtime [introduced by Google](https://www.usenix.org/conference/atc12/technical-sessions/presentation/serebryany). Compiling with `-fsanitize=address` is a powerful alternative to both [/RTC](https://docs.microsoft.com/en-us/cpp/build/reference/rtc-run-time-error-checks?view=msvc-160), and [/analyze](https://docs.microsoft.com/en-us/cpp/build/reference/analyze-code-analysis?view=msvc-160). It provides run-time bug-finding technologies which directly leverage your existing build systems and existing test assets.
24
24
25
-
Projects can enable the Address Sanitizer with a project setting, or a single additional compiler switch: **-fanitize=address**. The new flag is compatible with all levels of optimization but it is not compatible with three compilation modes: [edit-and-continue](), [incremental linking](..\..\build\reference\incremental-link-incrementally.md), and [/RTC](..\..\build\reference\rtc-run-time-error-checks.md). Apart from those three modes, all other configurations are supported when targeting x86 and x64.
25
+
Projects can enable the Address Sanitizer with a project setting, or a single additional compiler switch: **-fanitize=address**. The new flag is compatible with all levels of optimization and configurations of x86 and x64, with several incompatibilities: [edit-and-continue](https://docs.microsoft.com/en-us/visualstudio/debugger/edit-and-continue-visual-cpp?view=vs-2019), [incremental linking](https://docs.microsoft.com/en-us/cpp/build/reference/incremental-link-incrementally?view=msvc-160), and [/RTC](https://docs.microsoft.com/en-us/cpp/build/reference/rtc-run-time-error-checks?view=msvc-160).
26
26
27
27
The Address Sanitizer is integrated with the Visual Studio the project system, CMake system and the IDE.
28
28
29
-
Using the flag -fsanitize=address, the driver (cl.exe) will link a new library with your executable. This library enables integration with the IDE and it can optionally create a new crash dump file. Setting an environment variable via `set ASAN_SAVE_DUMPS=”MyFileName.dmpx”`your program can automatically create a new type of crash dump file that will contain extra meta-data for efficient, post-mortem debugging of **precisely diagnosed bugs**. These files facilitate using the Address Sanitizer in:
29
+
Microsoft's Address Sanitizer technology enables integration with the Visual Studio IDE and it can optionally create a crash dump file when the sanitizer finds a bug at runtime. Set the `ASAN_SAVE_DUMPS="MyFileName.dmpx"` environment variable prior to running your program, and a crash dump file will be created with extra meta-data for efficient, post-mortem debugging of **precisely diagnosed bugs**. These files facilitate using the Address Sanitizer in:
30
30
31
31
- On-premise single machine or distributed testing
32
32
- Cloud based workflows for testing
@@ -35,13 +35,13 @@ Using the flag -fsanitize=address, the driver (cl.exe) will link a new library w
35
35
36
36
Simply [**install the Address Sanitizer functionality**]().
37
37
38
-
After installing, you can build your executables with the `-fsanitize=address`compiler switch using any of the following:
38
+
After installing, you can build your executables with the `-fsanitize=address`compiler switch using any of the following:
39
39
40
40
- Command line
41
41
- Visual Studio project system
42
42
- Visual Studio CMake integration
43
43
44
-
You simply run your program normally. This will light up [many types of precisely diagnosed bugs](#errors). These [errors can be reported three (3) ways](#TBD): in the debugger IDE, on the command line or stored in a new type of dump file for precise off-line processing.
44
+
Recompile, then simply run your program normally. This will light up [many types of precisely diagnosed bugs](#errors). These [errors can be reported in three ways](#TBD): in the debugger IDE, on the command line or stored in a new type of dump file for precise off-line processing.
45
45
46
46
### Using the Address Sanitizer
47
47
@@ -66,79 +66,68 @@ This article will cover the information needed to enable the three workflows lis
66
66
67
67
## Using the Address Sanitizer from a Developer Command Prompt
68
68
69
-
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 an .EXE or .DLL. Debug information is required for optimal formatting of call stacks. In this example we explicitly pass `-/Zi`.
69
+
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 an .EXE or .DLL. Debug information is required for optimal formatting of call stacks. In this example we explicitly pass `/Zi`.
70
70
71
-
The Address Sanitizer libraries (.lib files) will be linked for you. For more detail, and for guidelines on partitioned build systems, see [building to target the Address Sanitizer runtime.](.\asan-building.md).
71
+
The Address Sanitizer libraries (.lib files) will be linked for you. For more detail, and for guidelines on partitioned build systems, see [building to target the Address Sanitizer runtime](./asan-building.md).
72
72
73
73
### Example - basic global buffer overflow:
74
74
75
-
76
75
```cpp
77
-
//main.cpp
76
+
//basic-global-overflow.cpp
78
77
#include<stdio.h>
79
-
80
78
int x[100];
81
-
82
79
intmain() {
83
-
printf("Hello!\n");
80
+
printf("Hello!\n");
84
81
x[100] = 5; // Boom!
85
82
return 0;
86
83
}
87
84
```
88
85
89
86
Using a Developer Command Prompt for VS 2019, compile main.cpp using `-fsanitize=address -Zi`
2.) A write of 4 bytes (32-bits) was outside any user defined variable.
104
-
105
-
3.) The store took place in function `main()` defined in file `basic-global-overflow.cpp` on line 7.
106
-
107
-
4.) The variable, named `"x"`, defined in basic-global-overflow.cpp on line 3 starting at column 8
108
-
109
-
5.) This global variable `"x"` is of size 400 bytes
110
-
111
-
6.) The exact [shadow byte](.\asan-shadowbytes.md) describing the address targeted by the store had a value of `0xf9`
112
-
113
-
7.) The shadow byte legend says `0xf9` is an area of padding to the right of `int x[100]`
98
+
1. This is a global-buffer-overflow
99
+
2. A write of 4 bytes (32-bits) was outside any user defined variable.
100
+
3. The store took place in function `main()` defined in file `basic-global-overflow.cpp` on line 7.
101
+
4. The variable, named `x`, defined in basic-global-overflow.cpp on line 3 starting at column 8
102
+
5. This global variable `x` is of size 400 bytes
103
+
6. The exact [shadow byte](./asan-shadowbytes.md) describing the address targeted by the store had a value of `0xf9`
104
+
7. The shadow byte legend says `0xf9` is an area of padding to the right of `int x[100]`
114
105
115
106
**Note:** The function names in the call stack are produced through the [LLVM symbolizer](https://llvm.org/docs/CommandGuide/llvm-symbolizer.html) which is invoked by the runtime upon error.
116
107
117
108
## Using the Address Sanitizer from Visual Studio
118
109
119
-
We've integrated the Address Sanitizer with the [Visual Studio IDE](https://docs.microsoft.com/en-us/visualstudio/get-started/visual-studio-ide?view=vs-2019). We simply augment the MSDN section on creating a C++ console application seen in the [quick start guide](https://docs.microsoft.com/en-us/cpp/get-started/tutorial-console-cpp?view=msvc-160&viewFallbackFrom=vs-2019).
120
-
121
-
You can turn on the Address Sanitizer for an MSBuild project by right-clicking on the project in Solution Explorer, choosing Properties, navigating under C/C++ > General, and changing the **Enable Address Sanitizer**
110
+
Address Sanitizer is integrated with the Visual Studio IDE. You can turn on the Address Sanitizer for an MSBuild project by right-clicking on the project in Solution Explorer, choosing Properties, navigating under C/C++ > General, and changing the **Enable Address Sanitizer**
## Using the Address Sanitizer from Visual Studio: CMake
136
125
137
126
To enable ASan for [a CMake project created to target Windows](https://docs.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio?view=msvc-160), do the following:
138
127
139
128
Open the Configurations dropdown at the top of the IDE and click on Manage Configurations.
0 commit comments