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 691bee3
Browse filesBrowse the repository at this point in the historyBrowse files
|[`/FS`](fs-force-synchronous-pdb-writes.md)| Forces serialization of all writes to the program database (PDB) file through MSPDBSRV.EXE. |
52
-
|[`/fsanitize`](fsanitize.md.md)| Enables compilation of sanitizer instrumentation such as AddressSanitizer. |
52
+
|[`/fsanitize`](fsanitize.md)| Enables compilation of sanitizer instrumentation such as AddressSanitizer. |
53
53
|[`/FU`](fu-name-forced-hash-using-file.md)| Forces the use of a file name as if it had been passed to the [`#using`](../../preprocessor/hash-using-directive-cpp.md) directive. |
54
54
|[`/Fx`](fx-merge-injected-code.md)| Merges injected code with source file. |
55
55
|[`/GA`](ga-optimize-for-windows-application.md)| Optimizes code for Windows application. |
@@ -19,7 +19,7 @@ Use the **`/fsanitize`** compiler options to enable sanitizers. As of Visual Stu
19
19
20
20
The **`/fsanitize=address`** compiler option enables [AddressSanitizer](../../sanitizers/asan.md), a powerful compiler and runtime technology to light up [hard-to-find bugs](../../sanitizers/asan.md#error-types).
21
21
22
-
The **`/fsanitize-address-use-after-return`** and **`/fno-sanitize-address-vcasan-lib`** compiler options, and the [`/INFERASANLIBS` (Use inferred sanitizer libs)](./inferasanlibs.md) and **`/INFERASANLIBS:NO`** linker options offer support for advanced users. See [AddressSanitizer build and language reference](../../sanitizers/asan-building.md) for more details.
22
+
The **`/fsanitize-address-use-after-return`** and **`/fno-sanitize-address-vcasan-lib`** compiler options, and the [`/INFERASANLIBS` (Use inferred sanitizer libs)](./inferasanlibs.md) and **`/INFERASANLIBS:NO`** linker options offer support for advanced users. For more information, see [AddressSanitizer build and language reference](../../sanitizers/asan-building.md).
23
23
24
24
The **`/fsanitize`** options are available beginning in Visual Studio 2019 version 16.9.
Use the **`/INFERASANLIBS`** linker option to enable or disable linking to the default sanitizer libraries. As of Visual Studio 2019 16.9, the only supported sanitizer is [AddressSanitizer](../../sanitizers/asan.md).
10
+
Use the **`/INFERASANLIBS`** linker option to enable or disable linking to the default AddressSanitizer libraries. As of Visual Studio 2019 16.9, the only supported sanitizer is [AddressSanitizer](../../sanitizers/asan.md).
11
11
12
12
## Syntax
13
13
14
14
> **`/INFERASANLIBS`**\[**`:NO`**]
15
15
16
16
## Remarks
17
17
18
-
The **`/INFERASANLIBS`** linker option enables the default [AddressSanitizer](../../sanitizers/asan.md) libraries. AddressSanitizer is a powerful compiler and runtime technology to light up [hard-to-find bugs](../../sanitizers/asan.md#error-types).
18
+
The **`/INFERASANLIBS`** linker option enables the default [AddressSanitizer](../../sanitizers/asan.md) libraries. This option is enabled by default.
19
19
20
-
The **`/INFERASANLIBS`** and **`/INFERASANLIBS:NO`** linker options offer support for advanced users. See [AddressSanitizer build and language reference](../../sanitizers/asan-building.md) for more details.
20
+
The **`/INFERASANLIBS`** and **`/INFERASANLIBS:NO`** linker options offer support for advanced users. For more information, see [AddressSanitizer build and language reference](../../sanitizers/asan-building.md).
21
21
22
22
The **`/INFERASANLIBS`** option is available beginning in Visual Studio 2019 version 16.9.
23
23
@@ -27,7 +27,7 @@ The **`/INFERASANLIBS`** option is available beginning in Visual Studio 2019 ver
1. Modify the **Additional Options** property. To enable default libraries, enter **/INFERASANLIBS** in the edit box. To disable default libraries, enter **/INFERASANLIBS:no** instead.
30
+
1. Modify the **Additional Options** property. To enable default libraries, enter **/INFERASANLIBS** in the edit box. To disable default libraries, enter **/INFERASANLIBS:NO** instead.
31
31
32
32
1. Choose **OK** or **Apply** to save your changes.
# AddressSanitizer language, build, and debugging reference
9
9
10
10
The sections in this article describe the AddressSanitizer language specification, compiler options, and linker options. They also describe the options that control Visual Studio debugger integration specific to the AddressSanitizer.
-[Visual Studio integration](#Visual-Studio-integration)
16
-
17
12
For more information on the AddressSanitizer runtime, intercepted functions, and how to hook custom allocators, see the [runtime reference](./asan-runtime.md). For more information on saving crash dumps from AddressSanitizer failures, see the [crash dump reference](./asan-offline-crash-dumps.md).
18
13
19
14
## Language specification
@@ -37,7 +32,7 @@ int main() {
37
32
38
33
### `__declspec(no_sanitize_address)`
39
34
40
-
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` disables _compiler_ behavior, not _runtime_ behavior.
35
+
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.
41
36
42
37
```cpp
43
38
__declspec(no_sanitize_address)
@@ -59,36 +54,32 @@ void test3() {
59
54
60
55
## Compiler
61
56
62
-
### `/fsanitize=address`
57
+
### `/fsanitize=address` compiler option
63
58
64
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).
65
60
66
-
**`/fsanitize=address`** is compatible with all existing C++ or C optimization levels (for example, `/Od`, `/O1`, `/O2`, `/O2 /GL`, and `PGO`). 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.
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.
67
62
68
63
See [the examples](asan.md#error-types) for sample usage.
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:
73
68
74
69
1. Compile using the [`/fsanitize-address-use-after-return`](../build/reference/fsanitize.md) option.
75
70
2. Before executing your program, run `set ASAN_OPTIONS=detect_stack_use_after_return=1` to set the runtime check option.
76
71
77
-
The **`/fsanitize-address-use-after-return`** option causes the compiler to generate code to use a dual stack frame in the heap when locals are considered "address taken". This code is **much slower** than just using **`/fsanitize=address`** alone.
78
-
79
-
See the [`stack-use-after-return` error](error-stack-use-after-return.md) for sample usage.
80
-
81
-
The dual stack frame in the heap remains after the return from the function that created it. Consider an example where the address of a local, allocated to a slot in the heap, is used after the return. The shadow bytes associated with the fake heap frame contain the value 0xf9. That 0xF9 means a stack-use-after-return error when the runtime reports the error.
72
+
The **`/fsanitize-address-use-after-return`** option causes the compiler to generate code to use a dual stack frame in the heap when locals are considered "address taken". This code is *much slower* than just using **`/fsanitize=address`** alone. For more information and an example, see [Error: `stack-use-after-return`](error-stack-use-after-return.md).
82
73
83
-
Stack frames are allocated in the heap and remain after functions return. The runtime uses garbage collection to asynchronously free these fake call-frame objects, after a certain time interval. By transferring addresses of locals to persistent frames in the heap, the system can detect when any locals get used afterthe defining function returns.
74
+
The dual stack frame in the heap remains after the return from the function that created it. Consider an example where the address of a local, allocated to a slot in the heap, is used after the return. The shadow bytes associated with the fake heap frame contain the value 0xF9. That 0xF9 means a stack-use-after-return error when the runtime reports the error.
84
75
85
-
See the [algorithm for stack use after return](https://github.com/google/sanitizers/wiki/AddressSanitizerUseAfterReturn) as documented by Google.
76
+
Stack frames are allocated in the heap and remain after functions return. The runtime uses garbage collection to asynchronously free these fake call-frame objects, after a certain time interval. Addresses of locals get transferred to persistent frames in the heap. It's how the system can detect when any locals get used after the defining function returns. For more information, see the [algorithm for stack use after return](https://github.com/google/sanitizers/wiki/AddressSanitizerUseAfterReturn) as documented by Google.
86
77
87
78
## Linker
88
79
89
-
### `-INFERASANLIBS[:no]`
80
+
### `/INFERASANLIBS[:NO]` linker option
90
81
91
-
The **`/fsanitize=address`** option links in libraries that begin with `clang_rt.asan*` into your final executable. The libraries chosen and automatically linked in are as follows.
82
+
The **`/fsanitize=address`**compiler option marks objects to specify the 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:
| MD | EITHER | YES |`clang_rt.asan_dbg_dynamic-{arch}, clang_rt.asan_dbg_dynamic_runtime_thunk-{arch}`|
101
92
102
-
The linker option `/INFERASANLIBS:NO` prevents the linker from linking the`clang_rt.asan*` library file from the default location. Add the library path in your build scripts if you use this option.
93
+
The linker option [`/INFERASANLIBS:NO`](../build/reference/inferasanlibs.md) prevents the linker from linking a`clang_rt.asan*` library file from the default location. Add the library path in your build scripts if you use this option. Otherwise, the linker reports an unresolved external symbol error.
The **`/fsanitize=address`** option links in extra capabilities to yield an improved Visual Studio debugging experience when an AddressSanitizer exception is thrown. These libraries are called **VCAsan**. These libraries enable Visual Studio to display AddressSanitizer errors on your source code. These libraries also enable the executable to generate crash dumps when an AddressSanitizer error report is created.
99
+
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).
109
100
110
-
The library chosen depends on the compilation options, and is automatically linked in as follows.
101
+
The library chosen depends on the compiler options, and is automatically linked in.
111
102
112
-
| Runtime option | VCAsan Version|
103
+
| Runtime option | VCAsan version|
113
104
|--------------|----------------|
114
105
|**`/MT`**|*`libvcasan.lib`*|
115
106
|**`/MD`**|*`vcasan.lib`*|
116
107
|**`/MTd`**|*`libvcasand.lib`*|
117
108
|**`/MDd`**|*`vcasand.lib`*|
118
109
119
-
However, if you compile using **`/Zl`** (Omit default library name), you'll need to manually specify the library. If you don't, you'll get a link failure; here are some typical examples:
110
+
However, if you compile using **`/Zl`** (Omit default library name), you'll need to manually specify the library. If you don't, you'll get an unresolved external symbol link error. Here are some typical examples:
120
111
121
112
```Output
122
113
error LNK2001: unresolved external symbol __you_must_link_with_VCAsan_lib
123
114
error LNK2001: unresolved external symbol ___you_must_link_with_VCAsan_lib
124
-
error LNK2019: unresolved external symbol __asan_report_load4 referenced in function main
125
-
error LNK2019: unresolved external symbol __asan_report_load8 referenced in function main
126
115
```
127
116
128
-
The improved debugging can be disabled at compile time using the **`/fno-sanitize-address-vcasan-lib`** option.
117
+
The improved debugging can be disabled at compile time by using the [`/fno-sanitize-address-vcasan-lib`](../build/reference/fsanitize.md) option.
129
118
130
-
### `ASAN_VCASAN_DEBUGGING`
119
+
### `ASAN_VCASAN_DEBUGGING` environment variable
131
120
132
-
The **`/fsanitize=address`** compiler option produces a binary that exposes memory safety bugs at runtime. When the binary is started from the command line, and the runtime reports an error, it prints the error details. It then and exits the process. The `ASAN_VCASAN_DEBUGGING` environment variable can be set to launch the Visual Studio IDE immediately when the runtime reports an error. This compiler option lets you view the error, superimposed over your source code, at the precise line and column that caused the error.
121
+
The **`/fsanitize=address`** compiler option produces a binary that exposes memory safety bugs at runtime. When the binary is started from the command line, and the runtime reports an error, it prints the error details. It then exits the process. The `ASAN_VCASAN_DEBUGGING` environment variable can be set to launch the Visual Studio IDE immediately when the runtime reports an error. This compiler option lets you view the error, superimposed over your source code, at the precise line and column that caused the error.
133
122
134
123
To enable this behavior, run the command `set ASAN_VCASAN_DEBUGGING=1` before you run your application. You can disable the enhanced debugging experience by running `set ASAN_VCASAN_DEBUGGING=0`.
0 commit comments