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
{{ message }}
Repository navigation
Commit 13e0b05
Browse filesBrowse the repository at this point in the historyBrowse files
Copy file name to clipboardExpand all lines: docs/sanitizers/asan-building.md
+3-3Lines changed: 3 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -56,11 +56,11 @@ void test3() {
56
56
57
57
### `/fsanitize=address` compiler option
58
58
59
-
The [`/fsanitize=address`](../build/reference/fsanitize.md) compiler option instruments memory references in your code to catch memory safety errors at runtime. The instrumentation hooks loads, stores, scopes, alloca, and CRT functions. It can detect hidden bugs such as out-of-bounds, use-after-free, use-after-scope, and so on. For a list of errors detected at runtime, see [Error types](./asan.md#error-types).
59
+
The [`/fsanitize=address`](../build/reference/fsanitize.md) compiler option instruments memory references in your code to catch memory safety errors at runtime. The instrumentation hooks loads, stores, scopes, alloca, and CRT functions. It can detect hidden bugs such as out-of-bounds, use-after-free, use-after-scope, and so on. For a non-exhaustive list of errors detected at runtime, see [AddressSanitizer error examples](./asan-error-examples.md).
60
60
61
61
**`/fsanitize=address`** is compatible with all existing C++ or C optimization levels (for example, **`/Od`**, **`/O1`**, **`/O2`**, **`/O2 /GL`**, and profile guided optimization). The code produced with this option works with static and dynamic CRTs (for example, **`/MD`**, **`/MDd`**, **`/MT`**, and **`/MTd`**). This compiler option can be used to create an .EXE or .DLL targeting x86 or x64. Debug information is required for optimal formatting of call stacks.
62
62
63
-
See [the examples in the error reference](asan-error-examples.md) for sample usage.
63
+
For examples of code that demonstrates several kinds of error detection, see [AddressSanitizer error examples](asan-error-examples.md).
In this section, we list a set of the errors supported by AddressSanitizer in Microsoft C/C++ (MSVC). In each article, we've ported some examples that help you learn to use the AddressSanitizer features supported by MSVC in your code. These examples are based on sources in the [LLVM compiler-rt test suite](https://github.com/llvm/llvm-project/tree/main/compiler-rt/test/asan/TestCases).
9
+
We list a subset of the errors supported by AddressSanitizer in Microsoft C/C++ (MSVC) in this section. This list is not an exhaustive error list. It's meant to show several kinds of errors you'll see in AddressSanitizer. In each article, we've ported some examples that help you learn to use the AddressSanitizer features supported by MSVC in your code. These examples are based on sources in the [LLVM compiler-rt test suite](https://github.com/llvm/llvm-project/tree/main/compiler-rt/test/asan/TestCases). All screenshots were generated by using **`devenv.exe /debugexe example.exe`**.
10
+
11
+
10
12
11
13
## Build the error examples
12
14
13
-
Each error example provides source code and compilation instructions for a command-line build. To build each example, open a developer command prompt. Create a folder for your example project, then make it the current directory. Then copy the example code into a source file with the appropriate name, such as *`example1.cpp`*. Follow the build instructions to generate and run the instrumented code in the debugger.
15
+
Each error example provides source code and compilation instructions for a command-line build. To build each example, open a [developer command prompt](../build/building-on-the-command-line.md#developer_command_prompt_shortcuts). Create a folder for your example project, then make it the current directory. Then copy the example code into a source file with the appropriate name, such as *`example1.cpp`*. Follow the build instructions to generate and run the instrumented code in the debugger.
14
16
15
17
## Errors with examples
16
18
@@ -54,6 +56,6 @@ Each error example provides source code and compilation instructions for a comma
54
56
[AddressSanitizer known issues](./asan-known-issues.md)\
55
57
[AddressSanitizer build and language reference](./asan-building.md)\
| MD | EITHER | YES |*`clang_rt.asan_dbg_dynamic-{arch}`*, *`clang_rt.asan_dbg_dynamic_runtime_thunk-{arch}`*|
25
25
26
-
When compiling with `cl /fsanitize=address`, the compiler generates instructions to manage and check the [shadow bytes](./asan-shadowbytes.md). Your program uses this instrumentation to check memory accesses on the stack, in the heap, or in the global scope. The compiler also produces metadata describing stack and global variables. This metadata enables the runtime to generate precise error diagnostics: function names, lines, and columns in your source code. Combined, the compiler checks and runtime libraries can precisely diagnose many types of [memory safety bugs](./asan-error-examples.md) if they're encountered at run-time.
26
+
When compiling with `cl /fsanitize=address`, the compiler generates instructions to manage and check the [shadow bytes](./asan-shadow-bytes.md). Your program uses this instrumentation to check memory accesses on the stack, in the heap, or in the global scope. The compiler also produces metadata describing stack and global variables. This metadata enables the runtime to generate precise error diagnostics: function names, lines, and columns in your source code. Combined, the compiler checks and runtime libraries can precisely diagnose many types of [memory safety bugs](./asan-error-examples.md) if they're encountered at run-time.
27
27
28
28
## Function interception
29
29
30
30
The AddressSanitizer achieves function interception through many hot-patching techniques. These techniques are [best documented within the source code itself](https://github.com/llvm/llvm-project/blob/1a2eaebc09c6a200f93b8beb37130c8b8aab3934/compiler-rt/lib/interception/interception_win.cpp#L11).
31
31
32
-
The runtime libraries intercept many common memory management and memory manipulation functions. For a list, see [AddressSanitizer list of intercepted functions](#intercepted_functions). The allocation interceptors manage metadata and shadow bytes related to each allocation call. Every time a CRT function such as `malloc` or `delete` is called, the interceptors set specific values in the AddressSanitizer shadow-memory region to indicate whether those heap locations are currently accessible and what the bounds of the allocation are. These shadow bytes allow the compiler-generated checks of the [shadow bytes](./asan-shadowbytes.md) to determine whether a load or store is valid.
32
+
The runtime libraries intercept many common memory management and memory manipulation functions. For a list, see [AddressSanitizer list of intercepted functions](#intercepted_functions). The allocation interceptors manage metadata and shadow bytes related to each allocation call. Every time a CRT function such as `malloc` or `delete` is called, the interceptors set specific values in the AddressSanitizer shadow-memory region to indicate whether those heap locations are currently accessible and what the bounds of the allocation are. These shadow bytes allow the compiler-generated checks of the [shadow bytes](./asan-shadow-bytes.md) to determine whether a load or store is valid.
33
33
34
34
Interception isn't guaranteed to succeed. If a function prologue is too short for a `jmp` to be written, interception can fail. If an interception failure occurs, the program throws a `debugbreak` and halts. If you attach a debugger, it makes the cause of the interception issue clear. If you have this problem, [report a bug](https://aka.ms/feedback/report?space=62).
35
35
@@ -38,7 +38,7 @@ Interception isn't guaranteed to succeed. If a function prologue is too short fo
38
38
39
39
## Custom allocators and the AddressSanitizer runtime
40
40
41
-
The AddressSanitizer runtime provides interceptors for common allocator interfaces, `malloc`/`free`, `new`/`delete`, `HeapAlloc`/`HeapFree` (via `RtlAllocateHeap`/`RtlFreeHeap`). Many programs make use of custom allocators for one reason or another, an example would be any program using `dlmalloc` or a solution using the `std::allocator` interface and `VirtualAlloc()`. The compiler is unable to automatically add shadow-memory management calls to a custom allocator. It's the user's responsibility to use the [provided manual poisoning interface](#poisoning). This API enables these allocators to function properly with the existing AddressSanitizer runtime and [shadow byte](./asan-shadowbytes.md) conventions.
41
+
The AddressSanitizer runtime provides interceptors for common allocator interfaces, `malloc`/`free`, `new`/`delete`, `HeapAlloc`/`HeapFree` (via `RtlAllocateHeap`/`RtlFreeHeap`). Many programs make use of custom allocators for one reason or another, an example would be any program using `dlmalloc` or a solution using the `std::allocator` interface and `VirtualAlloc()`. The compiler is unable to automatically add shadow-memory management calls to a custom allocator. It's the user's responsibility to use the [provided manual poisoning interface](#poisoning). This API enables these allocators to function properly with the existing AddressSanitizer runtime and [shadow byte](./asan-shadow-bytes.md) conventions.
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. This compiler and runtime technology exposes many [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 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. This compiler and runtime technology exposes many [hard-to-find bugs](./asan-error-examples.md) with **zero false positives**.
14
14
15
15
Use this feature to reduce your time spent on:
16
16
@@ -53,7 +53,7 @@ Start building your executables with the **`/fsanitize=address`** compiler optio
53
53
- Visual Studio project system
54
54
- Visual Studio CMake integration
55
55
56
-
Recompile, then run your program normally. This code generation exposes [many types of precisely diagnosed bugs](#error-types). These errors get reported in three ways: in the debugger IDE, on the command line, or stored in a [new type of dump file](#crash-dumps) for precise off-line processing.
56
+
Recompile, then run your program normally. This code generation exposes [many types of precisely diagnosed bugs](./asan-error-examples.md). These errors get reported in three ways: in the debugger IDE, on the command line, or stored in a [new type of dump file](#crash-dumps) for precise off-line processing.
57
57
58
58
Microsoft recommends using the AddressSanitizer in these **three standard workflows**:
59
59
@@ -110,7 +110,7 @@ Consider the overlaid, red boxes that highlight seven key pieces of information:
110
110
3. The store took place in function `main()` defined in file `basic-global-overflow.cpp` on line 7.
111
111
4. The variable named `x` gets defined in basic-global-overflow.cpp on line 3, starting at column 8
112
112
5. This global variable `x` is of size 400 bytes
113
-
6. The exact [shadow byte](./asan-shadowbytes.md) describing the address targeted by the store had a value of `0xf9`
113
+
6. The exact [shadow byte](./asan-shadow-bytes.md) describing the address targeted by the store had a value of `0xf9`
114
114
7. The shadow byte legend says `0xf9` is an area of padding to the right of `int x[100]`
115
115
116
116
> [!NOTE]
@@ -174,27 +174,7 @@ Starting with Visual Studio 16.9 you can display **a precisely diagnosed error**
174
174
175
175
## <aname="error-types"></a> Error types
176
176
177
-
This list of runtime errors can be detected when you run your binaries compiled with the AddressSanitizer (**`/fsanitize=address`**):
All screenshots were generated by using **`devenv.exe /debugexe example.exe`**.
177
+
The MSVC AddressSanitizer implementation can detect many kinds of memory misuse errors. For a non-exhaustive list of errors and links to demonstration examples, see [AddressSanitizer error examples](./asan-error-examples.md).
198
178
199
179
## <aname="differences"></a> Differences with Clang 12.0
200
180
@@ -229,7 +209,7 @@ This seminal paper on the [AddressSanitizer](https://www.usenix.org/system/files
229
209
[AddressSanitizer known issues](./asan-known-issues.md)\
230
210
[AddressSanitizer build and language reference](./asan-building.md)\
0 commit comments