Add AddressSanitizer Runtime Options page #5632

39otsu · 2025-08-07T18:57:21Z

We previously linked outdated documentation for asan runtime options. It was all over the place and split into two pieces with no indication of what our implementation does in the event it diverges from the one on the llvm repo.
The new page will give our customers a complete and organized list of runtime options that Address Sanitizer supports.

learn-build-service-prod · 2025-08-07T19:00:03Z

Learn Build status updates of commit 1f0f9f7:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/sanitizers/asan-flags.md	💡Suggestion		Details
docs/sanitizers/asan-runtime.md	✅Succeeded

docs/sanitizers/asan-flags.md

Line 14, Column 2: [Suggestion: column-header-missing - See documentation] Column headers are required for tables. Add appropriate header text, or remove any extra table cells that cause an extra column.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

davidmrdavid

Just a quick pass since there was a build warning

davidmrdavid · 2025-08-07T19:48:46Z

docs/sanitizers/asan-flags.md

+The following is a list of supported runtime options that can be set by the `ASAN_OPTIONS` environment variable or by overriding the `__asan_default_options()` user function. Reference: [AddressSanitizer Runtime Options](./asan-runtime.md#runtime-options). Note that while these mirror the options available in Clang's ASan, the description will differ by varying amounts in consideration of the MSVC ASan runtime.
+
+This is a living document that may update at any time due to the constant development of AddressSanitizer on the Windows platform. If you discover options that aren't accurately documented, we invite you to [report a bug](https://aka.ms/feedback/report?space=62).
+


for the error here: #5632 (comment)

I think you're missing this:

Suggested change

| ------- | -----------------| -----------|

It prints out the pipes and hyphens in plain text above the table. Not sure what its asking for :/

learn-build-service-prod · 2025-08-07T20:02:05Z

Learn Build status updates of commit 8898c80:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/sanitizers/asan-flags.md	💡Suggestion		Details
docs/sanitizers/asan-runtime.md	✅Succeeded

docs/sanitizers/asan-flags.md

Line 14, Column 2: [Suggestion: column-header-missing - See documentation] Column headers are required for tables. Add appropriate header text, or remove any extra table cells that cause an extra column.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

learn-build-service-prod · 2025-08-07T20:09:28Z

Learn Build status updates of commit eaf7ba9:

💡 Validation status: suggestions

File	Status	Preview URL	Details
docs/sanitizers/asan-flags.md	💡Suggestion		Details
docs/sanitizers/asan-runtime.md	✅Succeeded

docs/sanitizers/asan-flags.md

Line 14, Column 2: [Suggestion: column-header-missing - See documentation] Column headers are required for tables. Add appropriate header text, or remove any extra table cells that cause an extra column.

For more details, please refer to the build report.

Note: Your PR may contain errors or warnings or suggestions unrelated to the files you changed. This happens when external dependencies like GitHub alias, Microsoft alias, cross repo links are updated. Please use these instructions to resolve them.

39otsu · 2025-08-07T20:09:43Z

@microsoft-github-policy-service agree company="Microsoft"

prmerger-automator · 2025-08-07T20:09:56Z

@39otsu : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change.

v-dirichards · 2025-08-07T20:23:39Z

@TylerMSFT

Can you review the proposed changes?

Important: When the changes are ready for publication, adding a #sign-off comment is the best way to signal that the PR is ready for the review team to merge.

#label:"aq-pr-triaged"
@MicrosoftDocs/public-repo-pr-review-team

TylerMSFT

Hi David, I left some notes but stopped after a bit. Rather than have you wade through a bunch of my notes, I could do an edit pass on this before it gets checked in and that might save you some time. Let me know if you'd like me to do that.

TylerMSFT · 2025-08-07T22:32:16Z

docs/sanitizers/asan-runtime.md

@@ -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 available in MSVC as well. [A complete list of runtime options we support is available here](./asan-flags.md). 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).


This is a grammatically incorrect sentence (it was before). How about: "Because of this, most of Clang's ASan runtime options are available in MSVC."

TylerMSFT · 2025-08-07T22:32:54Z

docs/sanitizers/asan-flags.md

+helpviewer_keywords: ["AddressSanitizer options", "AddressSanitizer flags", "Address Sanitizer options", "Address Sanitizer flags", "asan options", "asan flags", "sanitizer flags", "asan_options", "AddressSanitizerFlags", "CommonSanitizerFlags"]
+---
+
+# AddressSanitizer Runtime Options


Our style is to use sentence casing, e.g. "AddressSantizer runtime options"

TylerMSFT · 2025-08-07T22:35:53Z

docs/sanitizers/asan-flags.md

+
+# AddressSanitizer Runtime Options
+
+The following is a list of supported runtime options that can be set by the `ASAN_OPTIONS` environment variable or by overriding the `__asan_default_options()` user function. Reference: [AddressSanitizer Runtime Options](./asan-runtime.md#runtime-options). Note that while these mirror the options available in Clang's ASan, the description will differ by varying amounts in consideration of the MSVC ASan runtime.


What is the reference about? Are you wanting to say: "For more information about setting runtime options, see AddressSanitizer Runtime Options"

TylerMSFT · 2025-08-07T22:40:26Z

docs/sanitizers/asan-flags.md

+
+# AddressSanitizer Runtime Options
+
+The following is a list of supported runtime options that can be set by the `ASAN_OPTIONS` environment variable or by overriding the `__asan_default_options()` user function. Reference: [AddressSanitizer Runtime Options](./asan-runtime.md#runtime-options). Note that while these mirror the options available in Clang's ASan, the description will differ by varying amounts in consideration of the MSVC ASan runtime.


We don't say "note ...". If it truly is a note that we want to call out, we use > [!NOTE] with the note text on the next line.
In this case, I'd just say "These options mirror those in Clang's ASan, but the descriptions may vary when there are differences with the MSVC ASan runtime".

TylerMSFT · 2025-08-07T22:41:46Z

docs/sanitizers/asan-flags.md

+
+The following is a list of supported runtime options that can be set by the `ASAN_OPTIONS` environment variable or by overriding the `__asan_default_options()` user function. Reference: [AddressSanitizer Runtime Options](./asan-runtime.md#runtime-options). Note that while these mirror the options available in Clang's ASan, the description will differ by varying amounts in consideration of the MSVC ASan runtime.
+
+This is a living document that may update at any time due to the constant development of AddressSanitizer on the Windows platform. If you discover options that aren't accurately documented, we invite you to [report a bug](https://aka.ms/feedback/report?space=62).


I'd drop the living document part and just say "Please report incorrectly documented options at ..." and the report a bug link.

TylerMSFT · 2025-08-07T22:47:08Z

docs/sanitizers/asan-flags.md

+|atexit | false | If true, prints ASan exit stats even after program terminates successfully.|
+|can_use_proc_maps_statm | true | If false, do not attempt to read `/proc/maps/statm`. Mostly useful for testing sanitizers. (Not implemented - `/proc/maps/statm` doesn't exist on Windows)|
+|check_initialization_order | false | If true, attempts to catch initialization order issues.|
+|check_malloc_usable_size | true | Allows the users to work around the bug in Nvidia drivers prior to 295.*.|


Please reconsider all places where you use 'user' in the doc. Probably could be replaced with 'you', yes?

TylerMSFT · 2025-08-07T22:48:19Z

docs/sanitizers/asan-flags.md

+|can_use_proc_maps_statm | true | If false, do not attempt to read `/proc/maps/statm`. Mostly useful for testing sanitizers. (Not implemented - `/proc/maps/statm` doesn't exist on Windows)|
+|check_initialization_order | false | If true, attempts to catch initialization order issues.|
+|check_malloc_usable_size | true | Allows the users to work around the bug in Nvidia drivers prior to 295.*.|
+|check_printf | true | If true, enables ASan to validate printf family function arguments for memory safety violations.|


Avoid passive voice. Instead, be direct, e.g. "If true, Asan validates printf family function arguments for memory safety violations." Applies throughout.

TylerMSFT · 2025-08-07T22:49:47Z

docs/sanitizers/asan-flags.md

+|check_initialization_order | false | If true, attempts to catch initialization order issues.|
+|check_malloc_usable_size | true | Allows the users to work around the bug in Nvidia drivers prior to 295.*.|
+|check_printf | true | If true, enables ASan to validate printf family function arguments for memory safety violations.|
+|clear_shadow_mmap_threshold | 64 * 1024 | Large shadow regions are zero-filled using `mmap(NORESERVE)` instead of `memset()`. This is the threshold size in bytes. (Not Implemented - `memset()` is always called on Windows)|


I don't understand whether 'not implemented' means the flag isn't implemented. If it isn't implemented, why are we documenting it? Maybe I misunderstand what not implemented means here.

TylerMSFT · 2025-08-07T22:50:36Z

docs/sanitizers/asan-flags.md

+|check_printf | true | If true, enables ASan to validate printf family function arguments for memory safety violations.|
+|clear_shadow_mmap_threshold | 64 * 1024 | Large shadow regions are zero-filled using `mmap(NORESERVE)` instead of `memset()`. This is the threshold size in bytes. (Not Implemented - `memset()` is always called on Windows)|
+|color | auto | Colorize reports: (always|never|auto). (Not Implemented on Windows)|
+|continue_on_error | 0 | Allows an application to continue running while reporting unique memory safety errors. 0 - disabled, 1 - stderr(1), 2 - stderr(2). See [continue_on_error](asan-continue-on-error.md).|


Our style, verbose though it is, is to say "For more information about xxx, see link. Otherwise, we get linting errors on the docs.

TylerMSFT · 2025-08-07T22:51:44Z

docs/sanitizers/asan-flags.md

+|clear_shadow_mmap_threshold | 64 * 1024 | Large shadow regions are zero-filled using `mmap(NORESERVE)` instead of `memset()`. This is the threshold size in bytes. (Not Implemented - `memset()` is always called on Windows)|
+|color | auto | Colorize reports: (always|never|auto). (Not Implemented on Windows)|
+|continue_on_error | 0 | Allows an application to continue running while reporting unique memory safety errors. 0 - disabled, 1 - stderr(1), 2 - stderr(2). See [continue_on_error](asan-continue-on-error.md).|
+|coverage | false | If true, coverage information will be dumped at program shutdown (if the coverage instrumentation was enabled at compile time).|


Passive voice is easy to fall into but less clear. An active voice fix here is: "if true and coverage instrumentation is enabled at compile time, coverage information is dumped when the program shuts down." Applies throughout.

39otsu · 2025-08-07T23:19:24Z

Hi David, I left some notes but stopped after a bit. Rather than have you wade through a bunch of my notes, I could do an edit pass on this before it gets checked in and that might save you some time. Let me know if you'd like me to do that.

It's Mac. I appreciate the feedback. Please do an edit pass, it has been quite a while since I've taken an English course haha.

macgyvercodilla added 2 commits August 7, 2025 11:49

Add AddressSanitizer Runtime Options page

13facdb

Update link to redirect to new AddressSanitizer Runtime Options page

1f0f9f7

prmerger-automator bot added the do-not-merge label Aug 7, 2025

davidmrdavid reviewed Aug 7, 2025

View reviewed changes

Fix header row, alignment row, and fix spacing consistency

8898c80

Hopefully fix header

eaf7ba9

prmerger-automator bot assigned TylerMSFT Aug 7, 2025

prmerger-automator bot requested a review from TylerMSFT August 7, 2025 20:09

prmerger-automator bot added Change sent to author tools/subsvc visual-cpp/svc labels Aug 7, 2025

prmerger-automator bot added the aq-pr-triaged Tracking label for the PR review team label Aug 7, 2025

TylerMSFT requested changes Aug 7, 2025

View reviewed changes

		The following is a list of supported runtime options that can be set by the `ASAN_OPTIONS` environment variable or by overriding the `__asan_default_options()` user function. Reference: [AddressSanitizer Runtime Options](./asan-runtime.md#runtime-options). Note that while these mirror the options available in Clang's ASan, the description will differ by varying amounts in consideration of the MSVC ASan runtime.

		This is a living document that may update at any time due to the constant development of AddressSanitizer on the Windows platform. If you discover options that aren't accurately documented, we invite you to [report a bug](https://aka.ms/feedback/report?space=62).


		# AddressSanitizer Runtime Options

		The following is a list of supported runtime options that can be set by the `ASAN_OPTIONS` environment variable or by overriding the `__asan_default_options()` user function. Reference: [AddressSanitizer Runtime Options](./asan-runtime.md#runtime-options). Note that while these mirror the options available in Clang's ASan, the description will differ by varying amounts in consideration of the MSVC ASan runtime.

Add AddressSanitizer Runtime Options page #5632

Are you sure you want to change the base?

Add AddressSanitizer Runtime Options page #5632

Conversation

39otsu commented Aug 7, 2025

Uh oh!

learn-build-service-prod bot commented Aug 7, 2025

💡 Validation status: suggestions

Uh oh!

davidmrdavid left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

learn-build-service-prod bot commented Aug 7, 2025

💡 Validation status: suggestions

Uh oh!

learn-build-service-prod bot commented Aug 7, 2025

💡 Validation status: suggestions

Uh oh!

39otsu commented Aug 7, 2025

Uh oh!

prmerger-automator bot commented Aug 7, 2025

Uh oh!

v-dirichards commented Aug 7, 2025

Uh oh!

TylerMSFT left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

39otsu commented Aug 7, 2025

Uh oh!

Uh oh!