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
# AddressSanitizer language, build, and debugging reference
8
+
# MSVC AddressSanitizer language, build, and debugging reference
9
9
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.
11
11
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).
13
13
14
14
## Language specification
15
15
16
16
### `__SANITIZE_ADDRESS__`
17
17
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.
19
19
20
20
```cpp
21
21
#include<cstdio>
22
22
23
-
intmain() {
23
+
intmain()
24
+
{
24
25
#ifdef __SANITIZE_ADDRESS__
25
-
printf("Address sanitizer enabled");
26
+
printf("MSVC AddressSanitizer enabled");
26
27
#else
27
-
printf("Address sanitizer not enabled");
28
+
printf("MSVC AddressSanitizer not enabled");
28
29
#endif
29
30
return 1;
30
31
}
@@ -35,19 +36,30 @@ int main() {
35
36
The [`__declspec(no_sanitize_address)`](../cpp/no-sanitize-address.md) specifier can be used to selectively disable the sanitizer on functions, local variables, or global variables. This `__declspec` affects _compiler_ behavior, not _runtime_ behavior.
36
37
37
38
```cpp
38
-
__declspec(no_sanitize_address)
39
-
void test1() {
39
+
#ifdef __SANITIZE_ADDRESS__
40
+
// no_sanitize_address is only defined when compiling with MSVC AddressSanitizer.
41
+
// Guard against this by checking if `__SANITIZE_ADDRESS__` is defined.
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).
60
72
61
73
**`/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.
62
74
63
-
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).
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:
99
111
100
112
1. Compile using the [`/fsanitize-address-use-after-return`](../build/reference/fsanitize.md) option.
101
113
2. Before executing your program, run `set ASAN_OPTIONS=detect_stack_use_after_return=1` to set the runtime check option.
@@ -120,13 +132,13 @@ Using **`/fsanitize-address-asan-compat-lib`** to link a newer compiler with an
120
132
121
133
### `/INFERASANLIBS[:NO]` linker option
122
134
123
-
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.
124
136
125
137
> [!NOTE]
126
138
> In the following table, *`{arch}`* is either *`i386`* or *`x86_64`*.
127
139
> 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.
| `/MT` or `/MTd` | *`clang_rt.asan_dynamic-{arch}.lib`*, *`/wholearchive:clang_rt.asan_static_runtime_thunk-{arch}.lib`* | *`clang_rt.asan_dynamic-{arch}.dll`*
132
144
| `/MD` or `/MDd` | *`clang_rt.asan_dynamic-{arch}.lib`*, *`/wholearchive:clang_rt.asan_dynamic_runtime_thunk-{arch}.lib`* | *`clang_rt.asan_dynamic-{arch}.dll`*
@@ -135,10 +147,10 @@ The linker option [`/INFERASANLIBS:NO`](../build/reference/inferasanlibs.md) pre
135
147
136
148
**Previous Versions**
137
149
138
-
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/).
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).
155
167
156
168
The library chosen depends on the compiler options, and is automatically linked in.
157
169
@@ -179,10 +191,10 @@ To enable this behavior, run the command `set ASAN_VCASAN_DEBUGGING=1` before yo
179
191
180
192
## See also
181
193
182
-
[AddressSanitizer overview](asan.md)\
183
-
[AddressSanitizer known issues](asan-known-issues.md)\
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments