|
| 1 | +--- |
| 2 | +title: "AddressSanitizer Runtime Options" |
| 3 | +description: "List of runtime options for the Microsoft C/C++ Address Sanitizer" |
| 4 | +ms.date: 8/08/2025 |
| 5 | +helpviewer_keywords: ["AddressSanitizer options", "AddressSanitizer flags", "Address sanitizer options", "Address sanitizer flags", "asan options", "asan flags", "sanitizer flags", "asan_options", "AddressSanitizerFlags", "SanitizerCommonFlags"] |
| 6 | +--- |
| 7 | + |
| 8 | +# AddressSanitizer Runtime Options |
| 9 | + |
| 10 | +The following table lists the options for the AddressSanitizer. Enable them via the `ASAN_OPTIONS` environment variable or by overriding the `__asan_default_options()` user function described [here](./asan-runtime.md#runtime-options). |
| 11 | + |
| 12 | +> [!NOTE] |
| 13 | +> These descriptions account for Microsoft Visual C++ (MSVC) specific behaviors, which may vary from Clang's runtime options. |
| 14 | +
|
| 15 | + |
| 16 | +| Flag | Default value | Description | |
| 17 | +|------|---------------|-------------| |
| 18 | +|`abort_on_error` | `false` | If `true`, ASan calls `abort()` instead of `_exit()` after printing the error report.| |
| 19 | +|`alloc_dealloc_mismatch` | `false` | Detects mismatched memory operations such as `malloc`/`delete`, `new[]`/`free`, and so on.| |
| 20 | +|`allocator_frees_and_returns_null_on_realloc_zero` | `true` | If set to `true`, `realloc(p, 0)` is the same as `free(p)` by default (which is the same as the POSIX standard). If set to `false`, `realloc(p, 0)` returns a pointer to an allocated space that can't be used. | |
| 21 | +|`allocator_may_return_null` | `false` | If `true`, the allocator returns `nullptr` when out of memory. Instead of crashing, ASan emits a warning about the allocator's failure and execution continues.| |
| 22 | +|`allow_user_poisoning` | `true` | If `true`, you may manually mark memory regions as poisoned or unpoisoned using the [Manual AddressSanitizer poising interface](./asan-runtime.md#poisoning).| |
| 23 | +|`check_initialization_order` | `false` | If `true`, attempts to catch initialization order issues.| |
| 24 | +|`continue_on_error` | 0 | Allows an application to continue running while reporting memory safety errors.<br>0-disabled.<br>1-enabled; errors are sent to `stdout`.<br>2-enabled; errors are sent to `stderr`.<br>For more information, see [continue_on_error](asan-continue-on-error.md).| |
| 25 | +|`detect_container_overflow` | `true` | If `true`, honor the container overflow annotations. For more information, see [ContainerOverflow](./error-container-overflow.md).| |
| 26 | +|`detect_invalid_pointer_pairs` | `false` | If `true`, ASan detects operations like `<`, `<=`, `>`, `>=`, and `-` on invalid pointer pairs such as pointers that belong to different objects.| |
| 27 | +|`detect_stack_use_after_return` | `false` | Experimental. If `true`, ASan enables `stack-use-after-return` checking at runtime. Requires `/fsanitize-address-use-after-return`. For more information, see [stack-use-after-return](./error-stack-use-after-return.md).| |
| 28 | +|`exitcode` | 1 | Overrides the program exit status with this value if ASan finds an error.| |
| 29 | +|`external_symbolizer_path` | "" | Path to the external symbolizer. If empty, ASan searches `$PATH` for the symbolizer.| |
| 30 | +|`fast_unwind_on_malloc` | `true` | If available, ASan uses the fast frame-pointer-based unwinder on `malloc`/`free`.| |
| 31 | +|`halt_on_error` | `true` | Not supported. Use `continue_on_error` instead.| |
| 32 | +|`handle_segv` | `true` | If `true`, ASan handles `SEGV` errors.| |
| 33 | +|`handle_sigfpe` | `true` | If `true`, ASan handles `SIGFPE` errors.| |
| 34 | +|`handle_sigill` | `true` | If `true`, ASan handles `SIGILL` errors.| |
| 35 | +|`help` | `false` | If `true`, ASan prints the flag options to the console.| |
| 36 | +|`iat_overwrite`|`error`|`error` - reports an error whenever an overwrite is detected.<br>`protect` - trys to avoid using the overwritten definition.<br>`ignore` - doesn't try to correct any overwritten functions. For more information, see [`iat_overwrite`](./asan-runtime.md#msvc-specific-addresssanitizer-runtime-options).| |
| 37 | +|`include_if_exists` | "" | Reads options from the specified file. ASan doesn't fail if the file doesn't exist.| |
| 38 | +|`intercept_strpbrk` | `true` | If `true`, uses custom wrappers for `strpbrk` to find more errors.| |
| 39 | +|`intercept_strspn` | `true` | If `true`, uses custom wrappers for `strspn` and `strcspn` to find more errors.| |
| 40 | +|`intercept_strstr` | `true` | If `true`, uses custom wrappers for `strstr` and `strcasestr` to find more errors.| |
| 41 | +|`malloc_context_size` | 1 | Maximum number of stack frames to keep for each allocation/deallocation.| |
| 42 | +|`malloc_fill_byte` | `0xbe` | Value used to fill newly allocated memory.| |
| 43 | +|`max_malloc_fill_size` | 4096 | The ASan allocator fills an allocation with `malloc_fill_byte` up to `max_malloc_fill_size` on a call to `malloc`.| |
| 44 | +|`max_redzone` | 2048 | Maximum size (in bytes) of redzones around heap objects.| |
| 45 | +|`new_delete_type_mismatch` | `true` | Report errors on mismatch between the size of `new` and `delete`. For more information, see [`new-delete-type-mismatch`](./error-new-delete-type-mismatch.md).| |
| 46 | +|`poison_heap` | `true` | If `true`, poison the heap memory on allocation and deallocation. `false` is useful for benchmarking the allocator or instrumentator.| |
| 47 | +|`poison_partial` | `true` | If `true`, poison partially addressable 8-byte aligned words. This flag affects heap and global buffers, but not stack buffers.| |
| 48 | +|`print_cmdline` | `false` | Print the command line on crash. With `continue_on_error` set >= 1, prints the current working directory and is `UTF-16` aware.| |
| 49 | +|`print_summary` | `true` | If `false`, disables showing error summaries that accompany error reports.| |
| 50 | +|`quarantine_size_mb` | -1 | Size (in Mb) of quarantine used to detect `use-after-free` errors. A lower value may increase the chance of false negatives.| |
| 51 | +|`redzone` | 16 | Minimum size (in bytes) of redzones around heap objects. Requirement: `redzone >= 16` and must be a power of two.| |
| 52 | +|`replace_str` | `true` | If `true`, uses custom wrappers and replacements for `libc` string functions to find more errors.| |
| 53 | +|`report_globals` | 1 | How to respond to buffer overflow for globals:<br>0-don't detect buffer overflow on globals.<br>1 - detect buffer overflow.<br>2 - detect buffer overflow and print registered globals data.| |
| 54 | +|`sleep_before_dying` | 0 | Number of seconds to sleep between printing an error report and terminating the program.| |
| 55 | +|`stack_trace_format` | `DEFAULT` | Format string used to render stack frames. `DEFAULT` - ` #%n %p %F %L`. List of available placeholders:<br> `%%` - represents a `'%'` character<br> `%n` - frame number (copy of `frame_no`)<br> `%p` - `PC`<br> `%m` - path to module<br> `%o` - offset in the module<br> `%f` - function name<br> `%q` - if available, offset in the function<br> `%s` - path to source file<br> `%l` - line in the source file<br> `%c` - column in the source file<br> `%F` - if the function is known, ASan prints `in <func name>` followed by the offset in this function if source is unknown<br> `%S` - ASan prints file/line/column information<br> `%L` - If file information is available, ASan prints the file name, line, and column. If module information is available, ASan prints the module name, offset, and architecture. If neither are available, ASan prints `(<unknown module>)`<br> `%M` - If known, ASan prints module basename and offset, or `PC`| |
| 56 | +|`strict_memcmp` | `true` | If `true`, assumes that `memcmp(p1, p2, n)` always reads `n` bytes before comparing `p1` and `p2`.| |
| 57 | +|`strict_string_checks` | `false` | If `true` checks that string arguments are properly null-terminated.| |
| 58 | +|`strip_path_prefix` | "" | Strips this prefix from file paths in error reports.| |
| 59 | +|`symbolize` | `true` | If `true`, use the `llvm-symbolizer` to turn virtual addresses into file or line locations.| |
| 60 | +|`symbolize_inline_frames` | `true` | Print inlined frames in stacktraces.| |
| 61 | +|`verbosity` | 0 | Verbosity level:<br>0 - default verbosity.<br>1 - more output.<br>2 - even more output.<br>3 - maximum verbosity. | |
| 62 | +|`windows_fast_fail_on_error`| `false` | If `true`, the process can terminate with a `__fastfail(71)` after printing the error report. For more information, see [`windows_fast_fail_on_error`](./asan-runtime.md#msvc-specific-addresssanitizer-runtime-options).| |
| 63 | +|`windows_hook_legacy_allocators`| `true` |If `true`, enables hooking of (`Global`/`Local`)(`Alloc`/`Free`/`Size`/`ReAlloc`/`Lock`/`Unlock`) functions.| |
| 64 | + |
| 65 | +## See also |
| 66 | + |
| 67 | +[AddressSanitizer overview](./asan.md)\ |
| 68 | +[AddressSanitizer known issues](./asan-known-issues.md)\ |
| 69 | +[AddressSanitizer build and language reference](./asan-building.md)\ |
| 70 | +[AddressSanitizer shadow bytes](./asan-shadow-bytes.md)\ |
| 71 | +[AddressSanitizer cloud or distributed testing](./asan-offline-crash-dumps.md)\ |
| 72 | +[AddressSanitizer debugger integration](./asan-debugger-integration.md)\ |
| 73 | +[AddressSanitizer error examples](./asan-error-examples.md) |
![learn-build-service-prod[bot]](https://avatars.githubusercontent.com/in/237442?v=4&size=40){kind=avatar}
0 commit comments