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
# Address Sanitizer Language, Build, and Debugging Reference
9
+
# AddressSanitizer Language, Build, and Debugging Reference
10
10
11
-
This section describes the language specification, compiler flags, and linker flags. It also describes the options controlling Visual Studio debugger integration specific to the Address Sanitizer.
11
+
This section describes the language specification, compiler flags, and linker flags. It also describes the options controlling Visual Studio debugger integration specific to the AddressSanitizer.
-[Visual Studio integration](#Visual-Studio-integration)
17
17
18
-
For more information on the Address Sanitizer runtime, intercepted functions, and how to hook custom allocators, see the [runtime reference](./asan-runtime.md). For more information on saving crash dumps from Address Sanitizer failures, see the [crash dump reference](./asan-offline-crash-dumps.md).
18
+
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).
19
19
20
20
## Language specification
21
21
22
22
### `__SANITIZE_ADDRESS__`
23
23
24
-
Useful for advanced users when conditionalizing source code for the presence of the Address Sanitizer runtime, the `__SANITIZE_ADDRESS__` macro is defined to `1` when `-fsanitize=address` is set.
24
+
Useful for advanced users when conditionalizing source code for the presence of the AddressSanitizer runtime, the `__SANITIZE_ADDRESS__` macro is defined to `1` when `-fsanitize=address` is set.
25
25
26
26
```cpp
27
27
#include<cstdio>
@@ -70,7 +70,7 @@ See[the examples](asan-top-level.md#Error-types) for sample usage.
The MSVC compiler (unlike Clang), will not default to generating code to allocating frames in the heap to catch use-after-return errors. To catch these errors with Address Sanitizer, you must:
73
+
The MSVC compiler (unlike Clang), will not default to generating code to allocating frames in the heap to catch use-after-return errors. To catch these errors with AddressSanitizer, you must:
74
74
75
75
1. Compile with `-fsanitize-address-use-after-return`
76
76
2. Before executing your program, set `set ASAN_OPTIONS=detect_stack_use_after_return=1`
@@ -91,7 +91,7 @@ See the [algorithm for stack use after return](https://github.com/google/sanitiz
91
91
92
92
The `-fsanitize=address` switch links in libraries that begin with `clang_rt.asan*` into your final executable. The libraries chosen and automatically linked in are as follows.
93
93
94
-
| CRT Flag | DLL or EXE | DEBUG? |Address Sanitizer Runtime Libraries |
94
+
| CRT Flag | DLL or EXE | DEBUG? |AddressSanitizer Runtime Libraries |
| MT | EXE | NO |`clang_rt.asan-{arch}, clang_rt.asan_cxx-{arch}`|
97
97
| MT | DLL | NO |`clang_rt.asan_dll_thunk-{arch}`|
@@ -106,7 +106,7 @@ The linker switch `-INFERASANLIBS:NO` will prevent the linker from choosing the
106
106
107
107
### `-fno-sanitize-address-vcasan-lib`
108
108
109
-
The `-fsanitize=address` switch links in extra capabilities to yield an improved Visual Studio debugging experience when an Address Sanitizer exception is thrown. These libraries are called **VCAsan**. These libraries enable Visual Studio to display Address Sanitizer errors on your source code. These libraries also enable the executable to generate crash dumps when an Address Sanitizer error report is created.
109
+
The `-fsanitize=address` switch 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.
110
110
111
111
The library chosen depends on the compilation flags, and is automatically linked in as follows.
112
112
@@ -134,12 +134,12 @@ The `-fsanitize=address` compiler switch produces a binary that will expose memo
134
134
135
135
## See also
136
136
137
-
-[Address Sanitizer Overview](./asan.md)
138
-
-[Address Sanitizer Known Issues](./asan-known-issues.md)
139
-
-[Address Sanitizer Build and Language Reference](./asan-building.md)
> [!NOTE] Send us [feedback](https://aka.ms/feedback/suggest?space=62) on what you would like to see in future releases, and please [report bugs](https://aka.ms/feedback/report?space=62) if you run into issues.
# Visual Studio Address Sanitizer extended functionality library (VCASan)
9
+
# Visual Studio AddressSanitizer extended functionality library (VCASan)
10
10
11
-
The **VCAsan\*.lib** libraries implement extended debugger IDE features in Visual Studio. These features allow the IDE to light up Address Sanitizer errors in live debug sessions, or offline by saving a crash dump file with metadata. The library is linked any time AddressSanitizer is enabled with the Visual C++ compiler.
11
+
The **VCAsan\*.lib** libraries implement extended debugger IDE features in Visual Studio. These features allow the IDE to light up AddressSanitizer errors in live debug sessions, or offline by saving a crash dump file with metadata. The library is linked any time AddressSanitizer is enabled with the Visual C++ compiler.
12
12
13
13
## VCAsan library inventory
14
14
@@ -21,30 +21,30 @@ The **VCAsan\*.lib** libraries implement extended debugger IDE features in Visua
21
21
22
22
## VCAsan library features
23
23
24
-
### Rich Address Sanitizer error report window in Visual Studio IDE
24
+
### Rich AddressSanitizer error report window in Visual Studio IDE
25
25
26
-
The VCAsan library will register a callback within the Address runtime with the [ASan interface function `__asan_set_error_report_callback`.](https://github.com/llvm/llvm-project/blob/1ba5ea67a30170053964a28f2f47aea4bb7f5ff1/compiler-rt/include/sanitizer/asan_interface.h#L256) If an Address Sanitizer report is generated, this callback is used to throw an exception that will be caught by Visual Studio. The data in the exception is used to generate the Visual Studio message that is displayed to the user within the IDE.
26
+
The VCAsan library will register a callback within the Address runtime with the [ASan interface function `__asan_set_error_report_callback`.](https://github.com/llvm/llvm-project/blob/1ba5ea67a30170053964a28f2f47aea4bb7f5ff1/compiler-rt/include/sanitizer/asan_interface.h#L256) If an AddressSanitizer report is generated, this callback is used to throw an exception that will be caught by Visual Studio. The data in the exception is used to generate the Visual Studio message that is displayed to the user within the IDE.
27
27
> [!NOTE]
28
-
> The VCASan library registers a callback function in the Address Sanitizer runtime. If your code calls this registration function a second time, it will overwrite the VCAsan library callback registration. This would result in the loss of all Visual Studio IDE integration. You would revert back to the default IDE user experience. It's also possible for a user's call to register their callback, to be lost. If you encounter either problem, please file a feedback ticket with the [Visual Studio developer community](https://developercommunity.visualstudio.com) we need to see these scenarios "in the wid".
28
+
> The VCASan library registers a callback function in the AddressSanitizer runtime. If your code calls this registration function a second time, it will overwrite the VCAsan library callback registration. This would result in the loss of all Visual Studio IDE integration. You would revert back to the default IDE user experience. It's also possible for a user's call to register their callback, to be lost. If you encounter either problem, please file a feedback ticket with the [Visual Studio developer community](https://developercommunity.visualstudio.com) we need to see these scenarios "in the wid".
29
29
30
-
### Save Address Sanitizer errors in a new type of crash dump file
30
+
### Save AddressSanitizer errors in a new type of crash dump file
31
31
32
-
When the VCasan library is linked, it is possible for the user to generate a crash dump when the Address Sanitizer runtime produces a (specifically diagnosed) error. To enable this feature, the user must set an environment variable as follows:
32
+
When the VCasan library is linked, it is possible for the user to generate a crash dump when the AddressSanitizer runtime produces a (specifically diagnosed) error. To enable this feature, the user must set an environment variable as follows:
33
33
34
34
`set ASAN_SAVE_DUMPS=MyFileName.dmp`
35
35
36
36
Note: It must use a .dmp suffix for Visual Studio IDE conventions.
37
37
38
-
This will save a crash dump file with new meta-data associated with an error caught by the Address Sanitizer runtime. The meta-data that is saved in the dump file is parsed by the new Visual Studio debugger IDE. You can set `ASAN_SAVE_DUMPS` on a per-test basis and store these binary artifacts and then view these in the IDE with proper source indexing.
38
+
This will save a crash dump file with new meta-data associated with an error caught by the AddressSanitizer runtime. The meta-data that is saved in the dump file is parsed by the new Visual Studio debugger IDE. You can set `ASAN_SAVE_DUMPS` on a per-test basis and store these binary artifacts and then view these in the IDE with proper source indexing.
39
39
40
40
## See also
41
41
42
-
-[Address Sanitizer Overview](./asan.md)
43
-
-[Address Sanitizer Known Issues](./asan-known-issues.md)
44
-
-[Address Sanitizer Build and Language Reference](./asan-building.md)
> [!NOTE] Send us [feedback](https://aka.ms/feedback/suggest?space=62) on what you would like to see in future releases, and please [report bugs](https://aka.ms/feedback/report?space=62) if you run into issues.
> [!NOTE] Send us [feedback](https://aka.ms/feedback/suggest?space=62) on what you would like to see in future releases, and please [report bugs](https://aka.ms/feedback/report?space=62) if you run into issues.
12
12
13
13
## Incompatible switches and functionality
14
14
15
15
The following switches and functionality are not currently compatible with `-fsanitize=address` and should be disabled or avoided.
16
16
17
-
- The [/RTC](https://docs.microsoft.com/en-us/cpp/build/reference/rtc-run-time-error-checks?view=msvc-160) family of switches are incompatible with Address Sanitizer and should be disabled.
17
+
- The [/RTC](https://docs.microsoft.com/en-us/cpp/build/reference/rtc-run-time-error-checks?view=msvc-160) family of switches are incompatible with AddressSanitizer and should be disabled.
18
18
-[Incremental Linking](https://docs.microsoft.com/en-us/cpp/build/reference/incremental-link-incrementally?view=msvc-160) is not currently supported, and should be disabled.
19
19
-[Edit-and-Continue](https://docs.microsoft.com/en-us/visualstudio/debugger/edit-and-continue-visual-cpp?view=vs-2019) is not currently supported, and should be disabled.
20
-
-[Coroutines](https://devblogs.microsoft.com/cppblog/category/coroutine/) are not compatible with Address Sanitizer, and resumable functions are exempt from instrumentation.
20
+
-[Coroutines](https://devblogs.microsoft.com/cppblog/category/coroutine/) are not compatible with AddressSanitizer, and resumable functions are exempt from instrumentation.
21
21
-[Open MP](https://docs.microsoft.com/en-us/cpp/build/reference/openmp-enable-openmp-2-0-support?view=msvc-160)is not currently supported, and should be disabled.
22
22
-[Managed C++](https://docs.microsoft.com/en-us/cpp/build/reference/clr-common-language-runtime-compilation?view=msvc-160) is not currently supported, and should be disabled.
23
23
-[C++ AMP](https://docs.microsoft.com/en-us/cpp/parallel/amp/cpp-amp-overview?view=msvc-160) is not currently supported, and should be disabled.
24
24
-[Special Case List](https://clang.llvm.org/docs/SanitizerSpecialCaseList.html) files are not supported.
25
25
26
26
## STL enlightenment
27
27
28
-
The MSVC standard library (STL) is not currently enlightened to understand the Address Sanitizer, so ASan exceptions raised in STL code, while identifying true bugs, are not as precise as they could be.
28
+
The MSVC standard library (STL) is not currently enlightened to understand the AddressSanitizer, so ASan exceptions raised in STL code, while identifying true bugs, are not as precise as they could be.
29
29
30
30
The following example demonstrates this. Compile with `cl -fsanitize=address /Zi`
31
31
@@ -54,7 +54,7 @@ int main() {
54
54
55
55
## Memory usage
56
56
57
-
The Address Sanitizer runtime does not release memory back to the OS during execution. From the OS point of view it may look like memory is being leaked, but this is an intentional design decision to not allocate all the required memory up front.
57
+
The AddressSanitizer runtime does not release memory back to the OS during execution. From the OS point of view it may look like memory is being leaked, but this is an intentional design decision to not allocate all the required memory up front.
58
58
59
59
## clang_rt.asan*.dll files
60
60
@@ -64,12 +64,12 @@ The clang_rt.asan*.dll runtime files are dropped next to the compilers in `%VSIN
64
64
65
65
## See also
66
66
67
-
-[Address Sanitizer Overview](./asan.md)
68
-
-[Address Sanitizer Known Issues](./asan-known-issues.md)
69
-
-[Address Sanitizer Build and Language Reference](./asan-building.md)
> [!NOTE] Send us [feedback](https://aka.ms/feedback/suggest?space=62) on what you would like to see in future releases, and please [report bugs](https://aka.ms/feedback/report?space=62) if you run into issues.
0 commit comments