From 7727b998e07d276c390e33750f6a6cbafa7a3a17 Mon Sep 17 00:00:00 2001 From: Rageking8 <106309953+Rageking8@users.noreply.github.com> Date: Mon, 18 Aug 2025 00:22:04 +0800 Subject: [PATCH 1/6] Add backticks in "AddressSanitizer runtime" topic --- docs/sanitizers/asan-runtime.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/sanitizers/asan-runtime.md b/docs/sanitizers/asan-runtime.md index 52fac2efa2a..7d588a4bd6b 100644 --- a/docs/sanitizers/asan-runtime.md +++ b/docs/sanitizers/asan-runtime.md @@ -11,13 +11,13 @@ The AddressSanitizer runtime library intercepts common memory allocation functio When compiling with `cl /fsanitize=address`, the compiler generates instructions to manage and check [shadow bytes](./asan-shadow-bytes.md). Your program uses this instrumentation to check memory accesses on the stack, in the heap, or in the global scope. The compiler also produces metadata describing stack and global variables. This metadata enables the runtime to generate precise error diagnostics: function names, lines, and columns in your source code. Combined, the compiler checks and runtime libraries can precisely diagnose many types of [memory safety bugs](./asan-error-examples.md) if they're encountered at run-time. -The list of runtime libraries for linking to the AddressSanitizer runtime, as of Visual Studio 17.7 Preview 3, follows. For more information about the `/MT` (statically link the runtime) and `/MD` (dynamically link the redist at runtime) options, see [/MD, /MT, /LD (Use Run-Time Library)](../build/reference/md-mt-ld-use-run-time-library.md). +The list of runtime libraries for linking to the AddressSanitizer runtime, as of Visual Studio 17.7 Preview 3, follows. For more information about the `/MT` (statically link the runtime) and `/MD` (dynamically link the redist at runtime) options, see [`/MD`, `/MT`, `/LD` (Use Run-Time Library)](../build/reference/md-mt-ld-use-run-time-library.md). > [!NOTE] > In the following table, *`{arch}`* is either *`i386`* or *`x86_64`*. > These libraries use Clang conventions for architecture names. MSVC conventions are normally `x86` and `x64` rather than `i386` and `x86_64`, but they refer to the same architectures. -| CRT option | AddressSanitizer runtime library (.lib) | Address runtime binary (.dll) +| CRT option | AddressSanitizer runtime library (`.lib`) | Address runtime binary (`.dll`) |--|--|--| | `/MT` or `/MTd` | *`clang_rt.asan_dynamic-{arch}`*, *`clang_rt.asan_static_runtime_thunk-{arch}`* | *`clang_rt.asan_dynamic-{arch}`* | `/MD` or `/MDd` | *`clang_rt.asan_dynamic-{arch}`*, *`clang_rt.asan_dynamic_runtime_thunk-{arch}`* | *`clang_rt.asan_dynamic-{arch}`* @@ -130,8 +130,8 @@ extern "C" const char* __asan_default_options() ### Unsupported AddressSanitizer options -- detect_container_overflow -- unmap_shadow_on_exit +- `detect_container_overflow` +- `unmap_shadow_on_exit` > [!NOTE] > The AddressSanitizer runtime option `halt_on_error` doesn't function the way you might expect. In both the Clang and the MSVC runtime libraries, many error types are considered **non-continuable**, including most memory corruption errors. @@ -152,9 +152,9 @@ For more information, see the [Differences with Clang 12.0](asan.md#differences) - If set to `"ignore"`, the runtime doesn't attempt to correct any overwritten functions and proceeds with execution. - `windows_fast_fail_on_error` -Boolean (false by default), set to `true` to enable the process to terminate with a __fastfail(71) after printing the error report. +Boolean (`false` by default), set to `true` to enable the process to terminate with a `__fastfail(71)` after printing the error report. >[!NOTE] ->When abort_on_error value is set to true, on Windows the program terminates with an exit(3). In order to not change current behavior we decided to introduce this new option instead. If both abort_on_error and windows_fast_fail_on_error are true, the program will exit with the __fastfail. +>When `abort_on_error` value is set to `true`, on Windows the program terminates with an `exit(3)`. In order to not change current behavior we decided to introduce this new option instead. If both `abort_on_error` and `windows_fast_fail_on_error` are `true`, the program will exit with the `__fastfail`. - `windows_hook_legacy_allocators` Boolean, set to `false` to disable interception of [`GlobalAlloc`](/windows/win32/api/winbase/nf-winbase-globalalloc) and [`LocalAlloc`](/windows/win32/api/winbase/nf-winbase-localalloc) allocators. From cb41768d114cd3682d31571dd3c38e33f71500ce Mon Sep 17 00:00:00 2001 From: Rageking8 <106309953+Rageking8@users.noreply.github.com> Date: Mon, 18 Aug 2025 00:26:07 +0800 Subject: [PATCH 2/6] Fix some typos in "AddressSanitizer runtime" topic --- docs/sanitizers/asan-runtime.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/sanitizers/asan-runtime.md b/docs/sanitizers/asan-runtime.md index 7d588a4bd6b..9512c30be20 100644 --- a/docs/sanitizers/asan-runtime.md +++ b/docs/sanitizers/asan-runtime.md @@ -31,7 +31,7 @@ The image shows three scenarios for linking the runtime library. The first is /M The following diagram shows how the ASan library is linked for various compiler options: :::image type="complex" source="media/asan-one-dll.png" alt-text="Diagram of how the ASan runtime dll is linked." -The image shows four scenarios for linking the ASan runtime library. The scenarios are for /MT (statically link the runtime), /MTd (statically link the debug runtime), /MD (dynamically link the redist at runtime), /MDd (dynamically link the debug redist at runtime). In all cases, my_exe.exe links and its associates my_dll.dll link to a single instance of clang-rt.asan-dynamix-x86_64.dll. +The image shows four scenarios for linking the ASan runtime library. The scenarios are for /MT (statically link the runtime), /MTd (statically link the debug runtime), /MD (dynamically link the redist at runtime), /MDd (dynamically link the debug redist at runtime). In all cases, my_exe.exe links and its associates my_dll.dll link to a single instance of clang_rt.asan_dynamic-x86_64.dll. :::image-end::: Even when statically linking, the ASan runtime DLL must be present at runtime--unlike other C Runtime components. @@ -101,7 +101,7 @@ For an illustration of the alignment requirement and potential issues, see the p ## Runtime options -The MSVC AddressSanitizer is based on the [Clang AddressSanitizer runtime from the llvm-project repository](https://github.com/llvm/llvm-project). Because of this, most of clang's ASan runtime options available in MSVC as well. [A complete list of the public Clang runtime options is available here](https://github.com/google/sanitizers/wiki/SanitizerCommonFlags). We document some differences in the sections that follow. If you discover options that don't function as expected, [report a bug](https://aka.ms/feedback/report?space=62). +The MSVC AddressSanitizer is based on the [Clang AddressSanitizer runtime from the llvm-project repository](https://github.com/llvm/llvm-project). Because of this, most of clang's ASan runtime options are available in MSVC as well. [A complete list of the public Clang runtime options is available here](https://github.com/google/sanitizers/wiki/SanitizerCommonFlags). We document some differences in the sections that follow. If you discover options that don't function as expected, [report a bug](https://aka.ms/feedback/report?space=62). ### Configure runtime options From fd42c86b732133228a34d8c97d2d1c5651f9f618 Mon Sep 17 00:00:00 2001 From: Rageking8 <106309953+Rageking8@users.noreply.github.com> Date: Mon, 18 Aug 2025 00:29:33 +0800 Subject: [PATCH 3/6] Add missing indent and format `windows_fast_fail_on_error` content in "AddressSanitizer runtime" topic --- docs/sanitizers/asan-runtime.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/sanitizers/asan-runtime.md b/docs/sanitizers/asan-runtime.md index 9512c30be20..280f3d777ab 100644 --- a/docs/sanitizers/asan-runtime.md +++ b/docs/sanitizers/asan-runtime.md @@ -152,9 +152,10 @@ For more information, see the [Differences with Clang 12.0](asan.md#differences) - If set to `"ignore"`, the runtime doesn't attempt to correct any overwritten functions and proceeds with execution. - `windows_fast_fail_on_error` -Boolean (`false` by default), set to `true` to enable the process to terminate with a `__fastfail(71)` after printing the error report. ->[!NOTE] ->When `abort_on_error` value is set to `true`, on Windows the program terminates with an `exit(3)`. In order to not change current behavior we decided to introduce this new option instead. If both `abort_on_error` and `windows_fast_fail_on_error` are `true`, the program will exit with the `__fastfail`. + Boolean (`false` by default), set to `true` to enable the process to terminate with a `__fastfail(71)` after printing the error report. + + > [!NOTE] + > When `abort_on_error` value is set to `true`, on Windows the program terminates with an `exit(3)`. In order to not change current behavior we decided to introduce this new option instead. If both `abort_on_error` and `windows_fast_fail_on_error` are `true`, the program will exit with the `__fastfail`. - `windows_hook_legacy_allocators` Boolean, set to `false` to disable interception of [`GlobalAlloc`](/windows/win32/api/winbase/nf-winbase-globalalloc) and [`LocalAlloc`](/windows/win32/api/winbase/nf-winbase-localalloc) allocators. From 3e1df7d6edda353ac2917a2f5804d0950825d9b2 Mon Sep 17 00:00:00 2001 From: Rageking8 <106309953+Rageking8@users.noreply.github.com> Date: Mon, 18 Aug 2025 00:31:15 +0800 Subject: [PATCH 4/6] Fix wrong link to `RtlDestroyHeap` in "AddressSanitizer runtime" topic --- docs/sanitizers/asan-runtime.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sanitizers/asan-runtime.md b/docs/sanitizers/asan-runtime.md index 280f3d777ab..00df2bf65a1 100644 --- a/docs/sanitizers/asan-runtime.md +++ b/docs/sanitizers/asan-runtime.md @@ -218,7 +218,7 @@ The AddressSanitizer runtime hotpatches many functions to enable memory safety c - [`realloc`](../c-runtime-library/reference/realloc.md) - [`RtlAllocateHeap`](/windows-hardware/drivers/ddi/ntifs/nf-ntifs-rtlallocateheap) - [`RtlCreateHeap`](/windows-hardware/drivers/ddi/ntifs/nf-ntifs-rtlcreateheap) -- [`RtlDestroyHeap`](/windows-hardware/drivers/ddi/ntifs/nf-ntifs-rtlcreateheap) +- [`RtlDestroyHeap`](/windows-hardware/drivers/ddi/ntifs/nf-ntifs-rtldestroyheap) - [`RtlFreeHeap`](/windows-hardware/drivers/ddi/ntifs/nf-ntifs-rtlfreeheap) - [`RtlRaiseException`](/windows/win32/api/rtlsupportapi/nf-rtlsupportapi-rtlraiseexception) - `RtlReAllocateHeap` (undocumented) From efde89e912403adebc1efe2b54fcaffbc52f6317 Mon Sep 17 00:00:00 2001 From: Rageking8 <106309953+Rageking8@users.noreply.github.com> Date: Mon, 18 Aug 2025 00:37:46 +0800 Subject: [PATCH 5/6] Clean up redundant `./` and normalize win32 links to lowercase in "AddressSanitizer runtime" topic --- docs/sanitizers/asan-runtime.md | 50 ++++++++++++++++----------------- 1 file changed, 25 insertions(+), 25 deletions(-) diff --git a/docs/sanitizers/asan-runtime.md b/docs/sanitizers/asan-runtime.md index 00df2bf65a1..1c1e523ad3f 100644 --- a/docs/sanitizers/asan-runtime.md +++ b/docs/sanitizers/asan-runtime.md @@ -7,9 +7,9 @@ helpviewer_keywords: ["AddressSanitizer runtime", "Address Sanitizer runtime", " # AddressSanitizer runtime -The AddressSanitizer runtime library intercepts common memory allocation functions and operations to enable inspection of memory accesses. There are several different runtime libraries that support the various types of executables the compiler may generate. The compiler and linker automatically link the appropriate runtime libraries, as long as you pass the [`/fsanitize=address`](../build/reference/fsanitize.md) option at compile time. You can override the default behavior by using the **`/NODEFAULTLIB`** option at link time. For more information, see the section on [linking](./asan-building.md#linker) in the [AddressSanitizer language, build, and debugging reference](./asan-building.md). +The AddressSanitizer runtime library intercepts common memory allocation functions and operations to enable inspection of memory accesses. There are several different runtime libraries that support the various types of executables the compiler may generate. The compiler and linker automatically link the appropriate runtime libraries, as long as you pass the [`/fsanitize=address`](../build/reference/fsanitize.md) option at compile time. You can override the default behavior by using the **`/NODEFAULTLIB`** option at link time. For more information, see the section on [linking](asan-building.md#linker) in the [AddressSanitizer language, build, and debugging reference](asan-building.md). -When compiling with `cl /fsanitize=address`, the compiler generates instructions to manage and check [shadow bytes](./asan-shadow-bytes.md). Your program uses this instrumentation to check memory accesses on the stack, in the heap, or in the global scope. The compiler also produces metadata describing stack and global variables. This metadata enables the runtime to generate precise error diagnostics: function names, lines, and columns in your source code. Combined, the compiler checks and runtime libraries can precisely diagnose many types of [memory safety bugs](./asan-error-examples.md) if they're encountered at run-time. +When compiling with `cl /fsanitize=address`, the compiler generates instructions to manage and check [shadow bytes](asan-shadow-bytes.md). Your program uses this instrumentation to check memory accesses on the stack, in the heap, or in the global scope. The compiler also produces metadata describing stack and global variables. This metadata enables the runtime to generate precise error diagnostics: function names, lines, and columns in your source code. Combined, the compiler checks and runtime libraries can precisely diagnose many types of [memory safety bugs](asan-error-examples.md) if they're encountered at run-time. The list of runtime libraries for linking to the AddressSanitizer runtime, as of Visual Studio 17.7 Preview 3, follows. For more information about the `/MT` (statically link the runtime) and `/MD` (dynamically link the redist at runtime) options, see [`/MD`, `/MT`, `/LD` (Use Run-Time Library)](../build/reference/md-mt-ld-use-run-time-library.md). @@ -63,7 +63,7 @@ The image shows four scenarios for linking the ASan runtime library. The scenari The AddressSanitizer achieves function interception through many hotpatching techniques. These techniques are [best documented within the source code itself](https://github.com/llvm/llvm-project/blob/1a2eaebc09c6a200f93b8beb37130c8b8aab3934/compiler-rt/lib/interception/interception_win.cpp#L11). -The runtime libraries intercept many common memory management and memory manipulation functions. For a list, see [AddressSanitizer list of intercepted functions](#intercepted_functions). The allocation interceptors manage metadata and shadow bytes related to each allocation call. Every time a CRT function such as `malloc` or `delete` is called, the interceptors set specific values in the AddressSanitizer shadow-memory region to indicate whether those heap locations are currently accessible and what the bounds of the allocation are. These shadow bytes allow the compiler-generated checks of the [shadow bytes](./asan-shadow-bytes.md) to determine whether a load or store is valid. +The runtime libraries intercept many common memory management and memory manipulation functions. For a list, see [AddressSanitizer list of intercepted functions](#intercepted_functions). The allocation interceptors manage metadata and shadow bytes related to each allocation call. Every time a CRT function such as `malloc` or `delete` is called, the interceptors set specific values in the AddressSanitizer shadow-memory region to indicate whether those heap locations are currently accessible and what the bounds of the allocation are. These shadow bytes allow the compiler-generated checks of the [shadow bytes](asan-shadow-bytes.md) to determine whether a load or store is valid. Interception isn't guaranteed to succeed. If a function prologue is too short for a `jmp` to be written, interception can fail. If an interception failure occurs, the program throws a `debugbreak` and halts. If you attach a debugger, it makes the cause of the interception issue clear. If you have this problem, [report a bug](https://aka.ms/feedback/report?space=62). @@ -72,7 +72,7 @@ Interception isn't guaranteed to succeed. If a function prologue is too short fo ## Custom allocators and the AddressSanitizer runtime -The AddressSanitizer runtime provides interceptors for common allocator interfaces, `malloc`/`free`, `new`/`delete`, `HeapAlloc`/`HeapFree` (via `RtlAllocateHeap`/`RtlFreeHeap`). Many programs make use of custom allocators for one reason or another, an example would be any program using `dlmalloc` or a solution using the `std::allocator` interface and `VirtualAlloc()`. The compiler is unable to automatically add shadow-memory management calls to a custom allocator. It's the user's responsibility to use the [provided manual poisoning interface](#poisoning). This API enables these allocators to function properly with the existing AddressSanitizer runtime and [shadow byte](./asan-shadow-bytes.md) conventions. +The AddressSanitizer runtime provides interceptors for common allocator interfaces, `malloc`/`free`, `new`/`delete`, `HeapAlloc`/`HeapFree` (via `RtlAllocateHeap`/`RtlFreeHeap`). Many programs make use of custom allocators for one reason or another, an example would be any program using `dlmalloc` or a solution using the `std::allocator` interface and `VirtualAlloc()`. The compiler is unable to automatically add shadow-memory management calls to a custom allocator. It's the user's responsibility to use the [provided manual poisoning interface](#poisoning). This API enables these allocators to function properly with the existing AddressSanitizer runtime and [shadow byte](asan-shadow-bytes.md) conventions. ## Manual AddressSanitizer poisoning interface @@ -113,7 +113,7 @@ If the environment variable and the user function specify conflicting options, t Multiple options are specified by separating them with a colon (`:`). -The following example sets [`alloc_dealloc_mismatch`](./error-alloc-dealloc-mismatch.md) to one and `symbolize` to zero: +The following example sets [`alloc_dealloc_mismatch`](error-alloc-dealloc-mismatch.md) to one and `symbolize` to zero: ```cmd set ASAN_OPTIONS=alloc_dealloc_mismatch=1:symbolize=0 @@ -249,26 +249,26 @@ The interceptors listed here are only installed when an AddressSanitizer runtime `set ASAN_OPTIONS=windows_hook_legacy_allocators=false` - [`GlobalAlloc`](/windows/win32/api/winbase/nf-winbase-globalalloc) -- [`GlobalFree`](/windows/win32/api/winbase/nf-winbase-GlobalFree) -- [`GlobalHandle`](/windows/win32/api/winbase/nf-winbase-GlobalHandle) -- [`GlobalLock`](/windows/win32/api/winbase/nf-winbase-GlobalLock) -- [`GlobalReAlloc`](/windows/win32/api/winbase/nf-winbase-GlobalReAlloc) -- [`GlobalSize`](/windows/win32/api/winbase/nf-winbase-GlobalSize) -- [`GlobalUnlock`](/windows/win32/api/winbase/nf-winbase-GlobalUnlock) -- [`LocalAlloc`](/windows/win32/api/winbase/nf-winbase-LocalAlloc) -- [`LocalFree`](/windows/win32/api/winbase/nf-winbase-LocalFree) -- [`LocalHandle`](/windows/win32/api/winbase/nf-winbase-LocalHandle) -- [`LocalLock`](/windows/win32/api/winbase/nf-winbase-LocalLock) -- [`LocalReAlloc`](/windows/win32/api/winbase/nf-winbase-LocalReAlloc) -- [`LocalSize`](/windows/win32/api/winbase/nf-winbase-LocalSize) -- [`LocalUnlock`](/windows/win32/api/winbase/nf-winbase-LocalUnlock) +- [`GlobalFree`](/windows/win32/api/winbase/nf-winbase-globalfree) +- [`GlobalHandle`](/windows/win32/api/winbase/nf-winbase-globalhandle) +- [`GlobalLock`](/windows/win32/api/winbase/nf-winbase-globallock) +- [`GlobalReAlloc`](/windows/win32/api/winbase/nf-winbase-globalrealloc) +- [`GlobalSize`](/windows/win32/api/winbase/nf-winbase-globalsize) +- [`GlobalUnlock`](/windows/win32/api/winbase/nf-winbase-globalunlock) +- [`LocalAlloc`](/windows/win32/api/winbase/nf-winbase-localalloc) +- [`LocalFree`](/windows/win32/api/winbase/nf-winbase-localfree) +- [`LocalHandle`](/windows/win32/api/winbase/nf-winbase-localhandle) +- [`LocalLock`](/windows/win32/api/winbase/nf-winbase-locallock) +- [`LocalReAlloc`](/windows/win32/api/winbase/nf-winbase-localrealloc) +- [`LocalSize`](/windows/win32/api/winbase/nf-winbase-localsize) +- [`LocalUnlock`](/windows/win32/api/winbase/nf-winbase-localunlock) ## See also -[AddressSanitizer overview](./asan.md)\ -[AddressSanitizer known issues](./asan-known-issues.md)\ -[AddressSanitizer build and language reference](./asan-building.md)\ -[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\ -[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\ -[AddressSanitizer debugger integration](./asan-debugger-integration.md)\ -[AddressSanitizer error examples](./asan-error-examples.md) +[AddressSanitizer overview](asan.md)\ +[AddressSanitizer known issues](asan-known-issues.md)\ +[AddressSanitizer build and language reference](asan-building.md)\ +[AddressSanitizer shadow bytes](asan-shadow-bytes.md)\ +[AddressSanitizer cloud or distributed testing](asan-offline-crash-dumps.md)\ +[AddressSanitizer debugger integration](asan-debugger-integration.md)\ +[AddressSanitizer error examples](asan-error-examples.md) From de560920bcb1d5b3c1b671a39e4e7475d10ff48a Mon Sep 17 00:00:00 2001 From: Rageking8 <106309953+Rageking8@users.noreply.github.com> Date: Mon, 18 Aug 2025 01:12:10 +0800 Subject: [PATCH 6/6] Change code block language from `C++` to `cpp` in "AddressSanitizer runtime" topic --- docs/sanitizers/asan-runtime.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/sanitizers/asan-runtime.md b/docs/sanitizers/asan-runtime.md index 1c1e523ad3f..3d862c6a0bc 100644 --- a/docs/sanitizers/asan-runtime.md +++ b/docs/sanitizers/asan-runtime.md @@ -121,7 +121,7 @@ set ASAN_OPTIONS=alloc_dealloc_mismatch=1:symbolize=0 Or add the following function to your code: -```C++ +```cpp extern "C" const char* __asan_default_options() { return "alloc_dealloc_mismatch=1:symbolize=0";