Skip to content

Commit 4aab680

Browse files
TylerMSFTTylerMSFT
authored
Change AddressSanitizer references to MSVC AddressSanitizer
Getting a head start on the new branding.
1 parent 8575d50 commit 4aab680

File tree

1 file changed

+34
-31
lines changed

1 file changed

+34
-31
lines changed

‎docs/sanitizers/asan-building.md‎

Lines changed: 34 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -1,30 +1,31 @@
11
---
2-
title: "AddressSanitizer language, build, and debugging reference"
3-
description: "Technical description of building for the AddressSanitizer"
2+
title: "MSVC AddressSanitizer language, build, and debugging reference"
3+
description: "Technical description of building for the MSVC AddressSanitizer"
44
ms.date: 02/05/2024
55
f1_keywords: ["__SANITIZE_ADDRESS__", "ASAN_VCASAN_DEBUGGING"]
6-
helpviewer_keywords: ["ASan reference", "AddressSanitizer reference", "Address Sanitizer reference"]
6+
helpviewer_keywords: ["ASan reference", "MSVC AddressSanitizer reference", "MSVC Address Sanitizer reference"]
77
---
8-
# AddressSanitizer language, build, and debugging reference
8+
# MSVC AddressSanitizer language, build, and debugging reference
99

10-
This article describes the AddressSanitizer language specification, compiler options, linker options, and the options that control Visual Studio debugger integration specific to the AddressSanitizer.
10+
This article describes the MSVC AddressSanitizer language specification, compiler options, linker options, and the options that control Visual Studio debugger integration specific to the MSVC AddressSanitizer.
1111

12-
For more information on the AddressSanitizer runtime, see the [runtime reference](asan-runtime.md). It includes information on intercepted functions and how to hook custom allocators. For more information on saving crash dumps from AddressSanitizer failures, see the [crash dump reference](asan-offline-crash-dumps.md).
12+
For more information on the MSVC AddressSanitizer runtime, see the [runtime reference](asan-runtime.md). It includes information on intercepted functions and how to hook custom allocators. For more information on saving crash dumps from MSVC AddressSanitizer failures, see the [crash dump reference](asan-offline-crash-dumps.md).
1313

1414
## Language specification
1515

1616
### `__SANITIZE_ADDRESS__`
1717

18-
The `__SANITIZE_ADDRESS__` preprocessor macro is defined as `1` when [`/fsanitize=address`](../build/reference/fsanitize.md) is set. This macro is useful for advanced users to conditionally specify source code for the presence of the AddressSanitizer runtime.
18+
The `__SANITIZE_ADDRESS__` preprocessor macro is defined as `1` when [`/fsanitize=address`](../build/reference/fsanitize.md) is set. This macro is useful to conditionally specify source code for the presence of the MSVC AddressSanitizer runtime.
1919

2020
```cpp
2121
#include <cstdio>
2222

23-
int main() {
23+
int main()
24+
{
2425
#ifdef __SANITIZE_ADDRESS__
25-
printf("Address sanitizer enabled");
26+
printf("MSVC AddressSanitizer enabled");
2627
#else
27-
printf("Address sanitizer not enabled");
28+
printf("MSVC AddressSanitizer not enabled");
2829
#endif
2930
return 1;
3031
}
@@ -36,27 +37,29 @@ The [`__declspec(no_sanitize_address)`](../cpp/no-sanitize-address.md) specifier
3637
3738
```cpp
3839
#ifdef __SANITIZE_ADDRESS__
39-
// `no_sanitize_address` is only defined when compiling with ASan.
40-
// You can guard against this by checking if `__SANITIZE_ADDRESS__`
41-
// is defined.
40+
// no_sanitize_address is only defined when compiling with MSVC AddressSanitizer.
41+
// Guard against this by checking if `__SANITIZE_ADDRESS__` is defined.
4242
#define NO_SANITIZE_ADDRESS __declspec(no_sanitize_address)
4343
#else
4444
#define NO_SANITIZE_ADDRESS
4545
#endif
4646
4747
NO_SANITIZE_ADDRESS
48-
void test1() {
48+
void test1()
49+
{
4950
int x[100];
5051
x[100] = 5; // ASan exception not caught
5152
}
5253
53-
void test2() {
54+
void test2()
55+
{
5456
NO_SANITIZE_ADDRESS int x[100];
5557
x[100] = 5; // ASan exception not caught
5658
}
5759
5860
NO_SANITIZE_ADDRESS int g[100];
59-
void test3() {
61+
void test3()
62+
{
6063
g[100] = 5; // ASan exception not caught
6164
}
6265
```
@@ -65,11 +68,11 @@ void test3() {
6568

6669
### `/fsanitize=address` compiler option
6770

68-
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 nonexhaustive list of errors detected at runtime, see [AddressSanitizer error examples](asan-error-examples.md).
71+
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 nonexhaustive list of errors detected at runtime, see [MSVC AddressSanitizer error examples](asan-error-examples.md).
6972

7073
**`/fsanitize=address`** is compatible with all existing C++ or C optimization levels (for example, **`/Od`**, **`/O1`**, **`/O2`**, and **`/O2 /GL`**). 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. This compiler option isn't supported with profile guided optimization.
7174

72-
For examples of code that demonstrates several kinds of error detection, see [AddressSanitizer error examples](asan-error-examples.md).
75+
For examples of code that demonstrates several kinds of error detection, see [MSVC AddressSanitizer error examples](asan-error-examples.md).
7376

7477
### `/fsanitize=fuzzer` compiler option (experimental)
7578

@@ -104,7 +107,7 @@ If you specify **`/NODEFAULTLIB`** and you don't specify one of these libraries,
104107

105108
### `/fsanitize-address-use-after-return` compiler option (experimental)
106109

107-
By default, the MSVC compiler (unlike Clang) doesn't generate code to allocate frames in the heap to catch use-after-return errors. To catch these errors using AddressSanitizer, you must:
110+
By default, the MSVC compiler (unlike Clang) doesn't generate code to allocate frames in the heap to catch use-after-return errors. To catch these errors using MSVC AddressSanitizer, you must:
108111

109112
1. Compile using the [`/fsanitize-address-use-after-return`](../build/reference/fsanitize.md) option.
110113
2. Before executing your program, run `set ASAN_OPTIONS=detect_stack_use_after_return=1` to set the runtime check option.
@@ -129,13 +132,13 @@ Using **`/fsanitize-address-asan-compat-lib`** to link a newer compiler with an
129132

130133
### `/INFERASANLIBS[:NO]` linker option
131134

132-
The **`/fsanitize=address`** compiler option marks objects to specify which AddressSanitizer library to link into your executable. The libraries have names that begin with *`clang_rt.asan*`*. The [`/INFERASANLIBS`](../build/reference/inferasanlibs.md) linker option (on by default) links these libraries from their default locations automatically. Here are the libraries chosen and automatically linked in.
135+
The **`/fsanitize=address`** compiler option marks objects to specify which MSVC AddressSanitizer library to link into your executable. The libraries have names that begin with *`clang_rt.asan*`*. The [`/INFERASANLIBS`](../build/reference/inferasanlibs.md) linker option (on by default) links these libraries from their default locations automatically. Here are the libraries chosen and automatically linked in.
133136

134137
> [!NOTE]
135138
> In the following table, *`{arch}`* is either *`i386`* or *`x86_64`*.
136139
> These libraries use Clang conventions for architecture names. MSVC conventions are normally `x86` and `x64` rather than `i386` and `x86_64`. They refer to the same architectures.
137140
138-
| CRT option | AddressSanitizer runtime library (.lib) | Address runtime binary (.dll)
141+
| CRT option | MSVC AddressSanitizer runtime library (.lib) | Address runtime binary (.dll)
139142
|--|--|--|
140143
| `/MT` or `/MTd` | *`clang_rt.asan_dynamic-{arch}.lib`*, *`/wholearchive:clang_rt.asan_static_runtime_thunk-{arch}.lib`* | *`clang_rt.asan_dynamic-{arch}.dll`*
141144
| `/MD` or `/MDd` | *`clang_rt.asan_dynamic-{arch}.lib`*, *`/wholearchive:clang_rt.asan_dynamic_runtime_thunk-{arch}.lib`* | *`clang_rt.asan_dynamic-{arch}.dll`*
@@ -144,10 +147,10 @@ The linker option [`/INFERASANLIBS:NO`](../build/reference/inferasanlibs.md) pre
144147

145148
**Previous Versions**
146149

147-
Prior to Visual Studio 17.7 Preview 3, statically linked (**`/MT`** or **`/MTd`**) builds didn't use a DLL dependency. Instead, the AddressSanitizer runtime was statically linked into the user's EXE. DLL projects would then load exports from the user's EXE to access ASan functionality. Also, dynamically linked projects (**`/MD`** or **`/MTd`**) used different libraries and DLLs depending on whether the project was configured for debug or release. For more information about these changes and their motivations, see [MSVC Address Sanitizer – One DLL for all Runtime Configurations](https://devblogs.microsoft.com/cppblog/msvc-address-sanitizer-one-dll-for-all-runtime-configurations/).
150+
Prior to Visual Studio 17.7 Preview 3, statically linked (**`/MT`** or **`/MTd`**) builds didn't use a DLL dependency. Instead, the MSVC AddressSanitizer runtime was statically linked into the user's EXE. DLL projects would then load exports from the user's EXE to access ASan functionality. Also, dynamically linked projects (**`/MD`** or **`/MTd`**) used different libraries and DLLs depending on whether the project was configured for debug or release. For more information about these changes and their motivations, see [MSVC AddressSanitizer – One DLL for all Runtime Configurations](https://devblogs.microsoft.com/cppblog/msvc-address-sanitizer-one-dll-for-all-runtime-configurations/).
148151

149152

150-
| CRT runtime option | DLL or EXE | AddressSanitizer runtime libraries |
153+
| CRT runtime option | DLL or EXE | MSVC AddressSanitizer runtime libraries |
151154
|--|--|--|
152155
| **`/MT`** | EXE | *`/wholearchive:clang_rt.asan-{arch}.lib`*, *`clang_rt.asan_cxx-{arch}.lib`* |
153156
| **`/MT`** | DLL | *`/wholearchive:clang_rt.asan_dll_thunk-{arch}.lib`* |
@@ -160,7 +163,7 @@ Prior to Visual Studio 17.7 Preview 3, statically linked (**`/MT`** or **`/MTd`*
160163

161164
### `/fno-sanitize-address-vcasan-lib` compiler option
162165

163-
The **`/fsanitize=address`** option links in extra libraries for an improved Visual Studio debugging experience when an AddressSanitizer exception is thrown. These libraries are called **VCAsan**. The libraries enable Visual Studio to display AddressSanitizer errors on your source code. They also enable the executable to generate crash dumps when an AddressSanitizer error report is created. For more information, see [Visual Studio AddressSanitizer extended functionality library](asan-debugger-integration.md).
166+
The **`/fsanitize=address`** option links in extra libraries for an improved Visual Studio debugging experience when an MSVC AddressSanitizer exception is thrown. These libraries are called **VCAsan**. The libraries enable Visual Studio to display MSVC AddressSanitizer errors on your source code. They also enable the executable to generate crash dumps when an MSVC AddressSanitizer error report is created. For more information, see [Visual Studio MSVC AddressSanitizer extended functionality library](asan-debugger-integration.md).
164167

165168
The library chosen depends on the compiler options, and is automatically linked in.
166169

@@ -188,10 +191,10 @@ To enable this behavior, run the command `set ASAN_VCASAN_DEBUGGING=1` before yo
188191

189192
## See also
190193

191-
[AddressSanitizer overview](asan.md)\
192-
[AddressSanitizer known issues](asan-known-issues.md)\
193-
[AddressSanitizer runtime reference](asan-runtime.md)\
194-
[AddressSanitizer shadow bytes](asan-shadow-bytes.md)\
195-
[AddressSanitizer cloud or distributed testing](asan-offline-crash-dumps.md)\
196-
[AddressSanitizer debugger integration](asan-debugger-integration.md)\
197-
[AddressSanitizer error examples](asan-error-examples.md)
194+
[MSVC AddressSanitizer overview](asan.md)\
195+
[MSVC AddressSanitizer known issues](asan-known-issues.md)\
196+
[MSVC AddressSanitizer runtime reference](asan-runtime.md)\
197+
[MSVC AddressSanitizer shadow bytes](asan-shadow-bytes.md)\
198+
[MSVC AddressSanitizer cloud or distributed testing](asan-offline-crash-dumps.md)\
199+
[MSVC AddressSanitizer debugger integration](asan-debugger-integration.md)\
200+
[MSVC AddressSanitizer error examples](asan-error-examples.md)

0 commit comments

Comments
 (0)