Skip to content

Commit 691bee3

Browse files
author
Colin Robertson
committed
Fix links, display issues
1 parent af0cbe5 commit 691bee3

10 files changed

Lines changed: 51 additions & 62 deletions

‎docs/build/reference/compiler-options-listed-alphabetically.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,7 +49,7 @@ This table contains an alphabetical list of compiler options. For a list of comp
4949
| [`/Fp`](fp-name-dot-pch-file.md) | Specifies a precompiled header file name. |
5050
| [`/FR`](fr-fr-create-dot-sbr-file.md)<br /><br /> [`/Fr`](fr-fr-create-dot-sbr-file.md) | Generates browser files. **`/Fr`** is deprecated. |
5151
| [`/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. |
5353
| [`/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. |
5454
| [`/Fx`](fx-merge-injected-code.md) | Merges injected code with source file. |
5555
| [`/GA`](ga-optimize-for-windows-application.md) | Optimizes code for Windows application. |

‎docs/build/reference/compiler-options-listed-by-category.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -155,7 +155,7 @@ This article contains a categorical list of compiler options. For an alphabetica
155155
| [`/errorReport`](errorreport-report-internal-compiler-errors.md) | Deprecated. Error reporting is controlled by [Windows Error Reporting (WER)](/windows/win32/wer/windows-error-reporting) settings. |
156156
| [`/FC`](fc-full-path-of-source-code-file-in-diagnostics.md) | Displays the full path of source code files passed to *cl.exe* in diagnostic text. |
157157
| [`/FS`](fs-force-synchronous-pdb-writes.md) | Forces writes to the PDB file to be serialized through *MSPDBSRV.EXE*. |
158-
| [`/fsanitize`](fsanitize.md.md) | Enables compilation of sanitizer instrumentation such as AddressSanitizer. |
158+
| [`/fsanitize`](fsanitize.md) | Enables compilation of sanitizer instrumentation such as AddressSanitizer. |
159159
| [`/H`](h-restrict-length-of-external-names.md) | Deprecated. Restricts the length of external (public) names. |
160160
| [`/HELP`](help-compiler-command-line-help.md) | Lists the compiler options. |
161161
| [`/J`](j-default-char-type-is-unsigned.md) | Changes the default **`char`** type. |

‎docs/build/reference/fsanitize.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -2,8 +2,8 @@
22
description: "Learn more about the /fsanitize (enable sanitizers) compiler option"
33
title: "/fsanitize (Enable sanitizers)"
44
ms.date: 02/24/2021
5-
f1_keywords: ["/fsanitize", "-fsanitize", "/fsanitize-address-use-after-return", "-fsanitize-address-use-after-return", "/fno-sanitize-address-vcasan-lib", "-fno-sanitize-address-vcasan-lib"]
6-
helpviewer_keywords: ["/fsanitize [C++]", "-fsanitize=address [C++]", "address sanitizer [C++]", "/fsanitize-address-use-after-return", "/fno-sanitize-address-vcasan-lib"]
5+
f1_keywords: ["/fsanitize", "-fsanitize", "/fsanitize=address", "/fsanitize-address-use-after-return", "-fsanitize-address-use-after-return", "/fno-sanitize-address-vcasan-lib", "-fno-sanitize-address-vcasan-lib"]
6+
helpviewer_keywords: ["/fsanitize [C++]", "-fsanitize=address [C++]", "address sanitizer compiler option [C++]", "/fsanitize-address-use-after-return", "/fno-sanitize-address-vcasan-lib"]
77
---
88
# `/fsanitize` (Enable sanitizers)
99

@@ -19,7 +19,7 @@ Use the **`/fsanitize`** compiler options to enable sanitizers. As of Visual Stu
1919

2020
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).
2121

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

2424
The **`/fsanitize`** options are available beginning in Visual Studio 2019 version 16.9.
2525

‎docs/build/reference/inferasanlibs.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -7,17 +7,17 @@ helpviewer_keywords: ["/INFERASANLIBS [C++]", "address sanitizer [C++] linker op
77
---
88
# `/INFERASANLIBS` (Use inferred sanitizer libs)
99

10-
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).
1111

1212
## Syntax
1313

1414
> **`/INFERASANLIBS`**\[**`:NO`**]
1515
1616
## Remarks
1717

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

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

2222
The **`/INFERASANLIBS`** option is available beginning in Visual Studio 2019 version 16.9.
2323

@@ -27,7 +27,7 @@ The **`/INFERASANLIBS`** option is available beginning in Visual Studio 2019 ver
2727

2828
1. Select the **Configuration Properties** > **Linker** > **Command Line** property page.
2929

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

3232
1. Choose **OK** or **Apply** to save your changes.
3333

‎docs/sanitizers/asan-building.md‎

Lines changed: 19 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,19 +1,14 @@
11
---
22
title: "AddressSanitizer language, build, and debugging reference"
33
description: "Technical description of building for the AddressSanitizer"
4-
ms.date: 02/15/2021
4+
ms.date: 03/02/2021
55
f1_keywords: ["__SANITIZE_ADDRESS__", "ASAN_VCASAN_DEBUGGING"]
66
helpviewer_keywords: ["ASan reference", "AddressSanitizer reference", "Address Sanitizer reference"]
77
---
88
# AddressSanitizer language, build, and debugging reference
99

1010
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.
1111

12-
- [Language specification](#Language-specification)
13-
- [Compiler](#Compiler)
14-
- [Linker](#Linker)
15-
- [Visual Studio integration](#Visual-Studio-integration)
16-
1712
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).
1813

1914
## Language specification
@@ -37,7 +32,7 @@ int main() {
3732
3833
### `__declspec(no_sanitize_address)`
3934
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.
4136
4237
```cpp
4338
__declspec(no_sanitize_address)
@@ -59,36 +54,32 @@ void test3() {
5954

6055
## Compiler
6156

62-
### `/fsanitize=address`
57+
### `/fsanitize=address` compiler option
6358

6459
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).
6560

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

6863
See [the examples](asan.md#error-types) for sample usage.
6964

70-
### `/fsanitize-address-use-after-return` (experimental)
65+
### `/fsanitize-address-use-after-return` compiler option (experimental)
7166

7267
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:
7368

7469
1. Compile using the [`/fsanitize-address-use-after-return`](../build/reference/fsanitize.md) option.
7570
2. Before executing your program, run `set ASAN_OPTIONS=detect_stack_use_after_return=1` to set the runtime check option.
7671

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

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 after the 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.
8475

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

8778
## Linker
8879

89-
### `-INFERASANLIBS[:no]`
80+
### `/INFERASANLIBS[:NO]` linker option
9081

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:
9283

9384
| CRT option | DLL or EXE | DEBUG? | AddressSanitizer runtime libraries |
9485
|----------|------------|--------|------------------------------------------------------------------------------------|
@@ -99,37 +90,35 @@ The **`/fsanitize=address`** option links in libraries that begin with `clang_rt
9990
| MT | DLL | YES | `clang_rt.asan_dbg_dll_thunk-{arch}` |
10091
| MD | EITHER | YES | `clang_rt.asan_dbg_dynamic-{arch}, clang_rt.asan_dbg_dynamic_runtime_thunk-{arch}` |
10192

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

10495
## Visual Studio integration
10596

106-
### `/fno-sanitize-address-vcasan-lib`
97+
### `/fno-sanitize-address-vcasan-lib` compiler option
10798

108-
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).
109100

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

112-
| Runtime option | VCAsan Version |
103+
| Runtime option | VCAsan version |
113104
|--------------|----------------|
114105
| **`/MT`** | *`libvcasan.lib`* |
115106
| **`/MD`** | *`vcasan.lib`* |
116107
| **`/MTd`** | *`libvcasand.lib`* |
117108
| **`/MDd`** | *`vcasand.lib`* |
118109

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:
120111

121112
```Output
122113
error LNK2001: unresolved external symbol __you_must_link_with_VCAsan_lib
123114
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
126115
```
127116

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

130-
### `ASAN_VCASAN_DEBUGGING`
119+
### `ASAN_VCASAN_DEBUGGING` environment variable
131120

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

134123
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`.
135124

0 commit comments

Comments
 (0)