Skip to content

Commit 13e0b05

Browse files
author
Colin Robertson
committed
Fix review blockers
1 parent e987533 commit 13e0b05

61 files changed

Lines changed: 80 additions & 98 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎docs/sanitizers/asan-building.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -56,11 +56,11 @@ void test3() {
5656

5757
### `/fsanitize=address` compiler option
5858

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).
6060

6161
**`/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.
6262

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).
6464

6565
### `/fsanitize-address-use-after-return` compiler option (experimental)
6666

@@ -127,7 +127,7 @@ To enable this behavior, run the command `set ASAN_VCASAN_DEBUGGING=1` before yo
127127
[AddressSanitizer overview](./asan.md)\
128128
[AddressSanitizer known issues](./asan-known-issues.md)\
129129
[AddressSanitizer runtime reference](./asan-runtime.md)\
130-
[AddressSanitizer shadow bytes](./asan-shadowbytes.md)\
130+
[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\
131131
[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\
132132
[AddressSanitizer debugger integration](./asan-debugger-integration.md)\
133133
[AddressSanitizer error examples](./asan-error-examples.md)

‎docs/sanitizers/asan-debugger-integration.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,6 +44,6 @@ Here's what happens when a dump file is specified for `ASAN_SAVE_DUMPS`: If an e
4444
[AddressSanitizer known issues](./asan-known-issues.md)\
4545
[AddressSanitizer build and language reference](./asan-building.md)\
4646
[AddressSanitizer runtime reference](./asan-runtime.md)\
47-
[AddressSanitizer shadow bytes](./asan-shadowbytes.md)\
47+
[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\
4848
[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\
4949
[AddressSanitizer error examples](./asan-error-examples.md)

‎docs/sanitizers/asan-error-examples.md‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,16 +1,18 @@
11
---
2-
title: "AddressSanitizer error reference"
2+
title: "AddressSanitizer error examples"
33
description: "Top-level description of the AddressSanitizer errors and examples in Microsoft C/C++."
44
ms.date: 03/01/2021
55
helpviewer_keywords: ["ASan error examples", "AddressSanitizer error examples", "Address Sanitizer error examples", "Error examples for AddressSanitizer"]
66
---
77
# AddressSanitizer error examples
88

9-
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+
1012

1113
## Build the error examples
1214

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.
1416

1517
## Errors with examples
1618

@@ -54,6 +56,6 @@ Each error example provides source code and compilation instructions for a comma
5456
[AddressSanitizer known issues](./asan-known-issues.md)\
5557
[AddressSanitizer build and language reference](./asan-building.md)\
5658
[AddressSanitizer runtime reference](./asan-runtime.md)\
57-
[AddressSanitizer shadow bytes](./asan-shadowbytes.md)\
59+
[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\
5860
[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\
5961
[AddressSanitizer debugger integration](./asan-debugger-integration.md)

‎docs/sanitizers/asan-known-issues.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -66,7 +66,7 @@ The *`clang_rt.asan*.dll`* runtime files are installed next to the compilers in
6666
[AddressSanitizer overview](./asan.md)\
6767
[AddressSanitizer build and language reference](./asan-building.md)\
6868
[AddressSanitizer runtime reference](./asan-runtime.md)\
69-
[AddressSanitizer shadow bytes](./asan-shadowbytes.md)\
69+
[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\
7070
[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\
7171
[AddressSanitizer debugger integration](./asan-debugger-integration.md)\
7272
[AddressSanitizer error examples](./asan-error-examples.md)

‎docs/sanitizers/asan-offline-crash-dumps.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -84,6 +84,6 @@ For external documentation, see:
8484
[AddressSanitizer known issues](./asan-known-issues.md)\
8585
[AddressSanitizer build and language reference](./asan-building.md)\
8686
[AddressSanitizer runtime reference](./asan-runtime.md)\
87-
[AddressSanitizer shadow bytes](./asan-shadowbytes.md)\
87+
[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\
8888
[AddressSanitizer debugger integration](./asan-debugger-integration.md)\
8989
[AddressSanitizer error examples](./asan-error-examples.md)

‎docs/sanitizers/asan-runtime.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -23,13 +23,13 @@ Below is an inventory of runtime libraries for linking to the AddressSanitizer r
2323
| MT | DLL | YES | *`clang_rt.asan_dbg_dll_thunk-{arch}`* |
2424
| MD | EITHER | YES | *`clang_rt.asan_dbg_dynamic-{arch}`*, *`clang_rt.asan_dbg_dynamic_runtime_thunk-{arch}`* |
2525

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.
2727

2828
## Function interception
2929

3030
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).
3131

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.
3333

3434
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).
3535

@@ -38,7 +38,7 @@ Interception isn't guaranteed to succeed. If a function prologue is too short fo
3838
3939
## Custom allocators and the AddressSanitizer runtime
4040

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.
4242

4343
## <a name="poisoning"></a> Manual AddressSanitizer poisoning interface
4444

@@ -188,7 +188,7 @@ The interceptors listed here are only installed when an AddressSanitizer runtime
188188
[AddressSanitizer overview](./asan.md)\
189189
[AddressSanitizer known issues](./asan-known-issues.md)\
190190
[AddressSanitizer build and language reference](./asan-building.md)\
191-
[AddressSanitizer shadow bytes](./asan-shadowbytes.md)\
191+
[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\
192192
[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\
193193
[AddressSanitizer debugger integration](./asan-debugger-integration.md)\
194194
[AddressSanitizer error examples](./asan-error-examples.md)

‎docs/sanitizers/asan.md‎

Lines changed: 5 additions & 25 deletions
Original file line numberDiff line numberDiff line change
@@ -10,7 +10,7 @@ helpviewer_keywords: ["ASan", "AddressSanitizer", "Address Sanitizer", "compilin
1010

1111
## Overview
1212

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](#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**.
1414

1515
Use this feature to reduce your time spent on:
1616

@@ -53,7 +53,7 @@ Start building your executables with the **`/fsanitize=address`** compiler optio
5353
- Visual Studio project system
5454
- Visual Studio CMake integration
5555

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.
5757

5858
Microsoft recommends using the AddressSanitizer in these **three standard workflows**:
5959

@@ -110,7 +110,7 @@ Consider the overlaid, red boxes that highlight seven key pieces of information:
110110
3. The store took place in function `main()` defined in file `basic-global-overflow.cpp` on line 7.
111111
4. The variable named `x` gets defined in basic-global-overflow.cpp on line 3, starting at column 8
112112
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`
114114
7. The shadow byte legend says `0xf9` is an area of padding to the right of `int x[100]`
115115

116116
> [!NOTE]
@@ -174,27 +174,7 @@ Starting with Visual Studio 16.9 you can display **a precisely diagnosed error**
174174

175175
## <a name="error-types"></a> Error types
176176

177-
This list of runtime errors can be detected when you run your binaries compiled with the AddressSanitizer (**`/fsanitize=address`**):
178-
179-
- [Error: `alloc-dealloc-mismatch`](./error-alloc-dealloc-mismatch.md)
180-
- [Error: `allocation-size-too-big`](./error-allocation-size-too-big.md)
181-
- [Error: `calloc-overflow`](./error-calloc-overflow.md)
182-
- [Error: `double-free`](./error-double-free.md)
183-
- [Error: `dynamic-stack-buffer-overflow`](./error-dynamic-stack-buffer-overflow.md)
184-
- [Error: `global-overflow`](./error-global-buffer-overflow.md)
185-
- [Error: `heap-buffer-overflow`](./error-heap-buffer-overflow.md)
186-
- [Error: `heap-use-after-free`](./error-heap-use-after-free.md)
187-
- [Error: `invalid-allocation-alignment`](./error-invalid-allocation-alignment.md)
188-
- [Error: `memcpy-param-overlap`](./error-memcpy-param-overlap.md)
189-
- [Error: `new-delete-type-mismatch`](./error-new-delete-type-mismatch.md)
190-
- [Error: `stack-buffer-overflow`](./error-stack-buffer-overflow.md)
191-
- [Error: `stack-buffer-underflow`](./error-stack-buffer-underflow.md)
192-
- [Error: `stack-use-after-return`](./error-stack-use-after-return.md)
193-
- [Error: `stack-use-after-scope`](./error-stack-use-after-scope.md)
194-
- [Error: `strncat-param-overlap`](./error-strncat-param-overlap.md)
195-
- [Error: `use-after-poison`](./error-use-after-poison.md)
196-
197-
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).
198178

199179
## <a name="differences"></a> Differences with Clang 12.0
200180

@@ -229,7 +209,7 @@ This seminal paper on the [AddressSanitizer](https://www.usenix.org/system/files
229209
[AddressSanitizer known issues](./asan-known-issues.md)\
230210
[AddressSanitizer build and language reference](./asan-building.md)\
231211
[AddressSanitizer runtime reference](./asan-runtime.md)\
232-
[AddressSanitizer shadow bytes](./asan-shadowbytes.md)\
212+
[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\
233213
[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\
234214
[AddressSanitizer debugger integration](./asan-debugger-integration.md)\
235215
[AddressSanitizer error examples](./asan-error-examples.md)

‎docs/sanitizers/error-alloc-dealloc-mismatch.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -50,15 +50,15 @@ devenv /debugexe example1.exe 2
5050

5151
### Resulting error
5252

53-
![Screenshot of debugger displaying error in example1](media/alloc-dealloc-mismatch-example1.png)
53+
![Screenshot of debugger displaying alloc-dealloc-mismatch error in example 1.](media/alloc-dealloc-mismatch-example-1.png)
5454

5555
## See also
5656

5757
[AddressSanitizer overview](./asan.md)\
5858
[AddressSanitizer known issues](./asan-known-issues.md)\
5959
[AddressSanitizer build and language reference](./asan-building.md)\
6060
[AddressSanitizer runtime reference](./asan-runtime.md)\
61-
[AddressSanitizer shadow bytes](./asan-shadowbytes.md)\
61+
[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\
6262
[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\
6363
[AddressSanitizer debugger integration](./asan-debugger-integration.md)\
6464
[AddressSanitizer error examples](./asan-error-examples.md)

‎docs/sanitizers/error-allocation-size-too-big.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,15 +46,15 @@ devenv /debugexe example1.exe
4646

4747
### Resulting error
4848

49-
![Screenshot of debugger displaying error in example1](media/allocation-size-too-big-example1.png)
49+
![Screenshot of debugger displaying allocation-size-too-big error in example 1.](media/allocation-size-too-big-example-1.png)
5050

5151
## See also
5252

5353
[AddressSanitizer overview](./asan.md)\
5454
[AddressSanitizer known issues](./asan-known-issues.md)\
5555
[AddressSanitizer build and language reference](./asan-building.md)\
5656
[AddressSanitizer runtime reference](./asan-runtime.md)\
57-
[AddressSanitizer shadow bytes](./asan-shadowbytes.md)\
57+
[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\
5858
[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\
5959
[AddressSanitizer debugger integration](./asan-debugger-integration.md)\
6060
[AddressSanitizer error examples](./asan-error-examples.md)

‎docs/sanitizers/error-calloc-overflow.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -41,15 +41,15 @@ devenv /debugexe example1.exe
4141

4242
### Resulting error
4343

44-
![Screenshot of debugger displaying error in example1](media/calloc-overflow-example1.png)
44+
![Screenshot of debugger displaying calloc-overflow error in example 1.](media/calloc-overflow-example-1.png)
4545

4646
## See also
4747

4848
[AddressSanitizer overview](./asan.md)\
4949
[AddressSanitizer known issues](./asan-known-issues.md)\
5050
[AddressSanitizer build and language reference](./asan-building.md)\
5151
[AddressSanitizer runtime reference](./asan-runtime.md)\
52-
[AddressSanitizer shadow bytes](./asan-shadowbytes.md)\
52+
[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\
5353
[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\
5454
[AddressSanitizer debugger integration](./asan-debugger-integration.md)\
5555
[AddressSanitizer error examples](./asan-error-examples.md)

0 commit comments

Comments
 (0)