-fsanitize=address

Enable AddressSanitizer, a fast memory error detector. Memory access instructions are instrumented to
detect out-of-bounds and use-after-free bugs. The option enables -fsanitize-address-use-after-scope.
See https://github.com/google/sanitizers/wiki/AddressSanitizer for more details. The run-time behavior can
be influenced using the ASAN_OPTIONS environment variable. When set to help=1, the available options are
shown at startup of the instrumented program.
See https://github.com/google/sanitizers/wiki/AddressSanitizerFlags#run-time-flags for a list of supported
options. The option cannot be combined with -fsanitize=thread or -fsanitize=hwaddress. Note that the only
target -fsanitize=hwaddress is currently supported on is AArch64.

To get more accurate stack traces, it is possible to use options such as -O0, -O1, or -Og (which, for instance,
prevent most function inlining), -fno-optimize-sibling-calls (which prevents optimizing sibling and tail
recursive calls; this option is implicit for -O0, -O1, or -Og), or -fno-ipa-icf (which disables Identical Code
Folding for functions). Since multiple runs of the program may yield backtraces with different addresses
due to ASLR (Address Space Layout Randomization), it may be desirable to turn ASLR off. On Linux, this
can be achieved with ‘setarch `uname -m` -R ./prog’.

-fsanitize=kernel-address

Enable AddressSanitizer for Linux kernel. See https://github.com/google/kernel-sanitizers for more details.

-fsanitize=hwaddress

Enable Hardware-assisted AddressSanitizer, which uses a hardware ability to ignore the top byte of a
pointer to allow the detection of memory errors with a low memory overhead. Memory access instructions
are instrumented to detect out-of-bounds and use-after-free bugs. The option enables -fsanitize-address-
use-after-scope. See https://clang.llvm.org/docs/HardwareAssistedAddressSanitizerDesign.html for more
details. The run-time behavior can be influenced using the HWASAN_OPTIONS environment variable. When set
to help=1, the available options are shown at startup of the instrumented program. The option cannot be
combined with -fsanitize=thread or -fsanitize=address, and is currently only available on AArch64.

-fsanitize=kernel-hwaddress

Enable Hardware-assisted AddressSanitizer for compilation of the Linux kernel. Similar to -

fsanitize=kernel-address but using an alternate instrumentation method, and similar to -
fsanitize=hwaddress but with instrumentation differences necessary for compiling the Linux kernel. These
differences are to avoid hwasan library initialization calls and to account for the stack pointer having a
different value in its top byte.

Note: This option has different defaults to the -fsanitize=hwaddress. Instrumenting the stack and alloca calls
are not on by default but are still possible by specifying the command-line options --param hwasan-
instrument-stack=1 and --param hwasan-instrument-allocas=1 respectively. Using a random frame tag is not
implemented for kernel instrumentation.

-fsanitize=pointer-compare

Instrument comparison operation (<, <=, >, >=) with pointer operands. The option must be combined with
either -fsanitize=kernel-address or -fsanitize=address The option cannot be combined with -
fsanitize=thread. Note: By default the check is disabled at run time. To enable it,
add detect_invalid_pointer_pairs=2 to the environment variable ASAN_OPTIONS.
Using detect_invalid_pointer_pairs=1 detects invalid operation only when both pointers are non-null.

-fsanitize=pointer-subtract

Instrument subtraction with pointer operands. The option must be combined with either -fsanitize=kernel-
address or -fsanitize=address The option cannot be combined with -fsanitize=thread. Note: By default the
check is disabled at run time. To enable it, add detect_invalid_pointer_pairs=2 to the environment
variable ASAN_OPTIONS. Using detect_invalid_pointer_pairs=1 detects invalid operation only when both
pointers are non-null.

-fsanitize=shadow-call-stack

Enable ShadowCallStack, a security enhancement mechanism used to protect programs against return
address overwrites (e.g. stack buffer overflows.) It works by saving a function’s return address to a
separately allocated shadow call stack in the function prologue and restoring the return address from the
 shadow call stack in the function epilogue. Instrumentation only occurs in functions that need to save the
return address to the stack.

Currently it only supports the aarch64 platform. It is specifically designed for linux kernels that enable the
CONFIG_SHADOW_CALL_STACK option. For the user space programs, runtime support is not currently
provided in libc and libgcc. Users who want to use this feature in user space need to provide their own
support for the runtime. It should be noted that this may cause the ABI rules to be broken.

On aarch64, the instrumentation makes use of the platform register x18. This generally means that any code
that may run on the same thread as code compiled with ShadowCallStack must be compiled with the flag -
ffixed-x18, otherwise functions compiled without -ffixed-x18 might clobber x18 and so corrupt the shadow
stack pointer.

Also, because there is no userspace runtime support, code compiled with ShadowCallStack cannot use
exception handling. Use -fno-exceptions to turn off exceptions.

See https://clang.llvm.org/docs/ShadowCallStack.html for more details.

-fsanitize=thread

Enable ThreadSanitizer, a fast data race detector. Memory access instructions are instrumented to detect
data race bugs. See https://github.com/google/sanitizers/wiki#threadsanitizer for more details. The run-time
behavior can be influenced using the TSAN_OPTIONS environment variable;
see https://github.com/google/sanitizers/wiki/ThreadSanitizerFlags for a list of supported options. The
option cannot be combined with -fsanitize=address, -fsanitize=leak.

Note that sanitized atomic builtins cannot throw exceptions when operating on invalid memory addresses
with non-call exceptions (-fnon-call-exceptions).

-fsanitize=leak

Enable LeakSanitizer, a memory leak detector. This option only matters for linking of executables. The
executable is linked against a library that overrides malloc and other allocator functions.
See https://github.com/google/sanitizers/wiki/AddressSanitizerLeakSanitizer for more details. The run-time
behavior can be influenced using the LSAN_OPTIONS environment variable. The option cannot be combined
with -fsanitize=thread.

-fsanitize=undefined

Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector. Various computations are

instrumented to detect undefined behavior at runtime.
See https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html for more details. The run-time behavior
can be influenced using the UBSAN_OPTIONS environment variable. Current suboptions are:
-fsanitize=shift

This option enables checking that the result of a shift operation is not undefined. Note that what
exactly is considered undefined differs slightly between C and C++, as well as between ISO C90
and C99, etc. This option has two suboptions, -fsanitize=shift-base and -fsanitize=shift-exponent.

-fsanitize=shift-exponent

This option enables checking that the second argument of a shift operation is not negative and is
smaller than the precision of the promoted first argument.

-fsanitize=shift-base

If the second argument of a shift operation is within range, check that the result of a shift operation
is not undefined. Note that what exactly is considered undefined differs slightly between C and
C++, as well as between ISO C90 and C99, etc.
-fsanitize=integer-divide-by-zero

Detect integer division by zero.

-fsanitize=unreachable

With this option, the compiler turns the __builtin_unreachable call into a diagnostics message call
instead. When reaching the __builtin_unreachable call, the behavior is undefined.
-fsanitize=vla-bound
 This option instructs the compiler to check that the size of a variable length array is positive.
-fsanitize=null

This option enables pointer checking. Particularly, the application built with this option turned on
will issue an error message when it tries to dereference a NULL pointer, or if a reference (possibly
an rvalue reference) is bound to a NULL pointer, or if a method is invoked on an object pointed by
a NULL pointer.

-fsanitize=return

This option enables return statement checking. Programs built with this option turned on will issue
an error message when the end of a non-void function is reached without actually returning a value.
This option works in C++ only.

-fsanitize=signed-integer-overflow

This option enables signed integer overflow checking. We check that the result of +, *, and both
unary and binary - does not overflow in the signed arithmetics. This also detects INT_MIN /
-1 signed division. Note, integer promotion rules must be taken into account. That is, the following
is not an overflow:

signed char a = SCHAR_MAX;

a++;

-fsanitize=bounds

This option enables instrumentation of array bounds. Various out of bounds accesses are detected.
Flexible array members, flexible array member-like arrays, and initializers of variables with static
storage are not instrumented, with the exception of flexible array member-like arrays for which -
fstrict-flex-arrays or -fstrict-flex-arrays= options or strict_flex_array attributes say they
shouldn’t be treated like flexible array member-like arrays.
-fsanitize=bounds-strict

This option enables strict instrumentation of array bounds. Most out of bounds accesses are
detected, including flexible array member-like arrays. Initializers of variables with static storage are
not instrumented.

-fsanitize=alignment

This option enables checking of alignment of pointers when they are dereferenced, or when a
reference is bound to insufficiently aligned target, or when a method or constructor is invoked on
insufficiently aligned object.
-fsanitize=object-size

This option enables instrumentation of memory references using

the __builtin_dynamic_object_size function. Various out of bounds pointer accesses are detected.
-fsanitize=float-divide-by-zero

Detect floating-point division by zero. Unlike other similar options, -fsanitize=float-divide-by-

zero is not enabled by -fsanitize=undefined, since floating-point division by zero can be a legitimate
way of obtaining infinities and NaNs.

-fsanitize=float-cast-overflow

This option enables floating-point type to integer conversion checking. We check that the result of
the conversion does not overflow. Unlike other similar options, -fsanitize=float-cast-overflow is
not enabled by -fsanitize=undefined. This option does not work well with FE_INVALID exceptions
enabled.
-fsanitize=nonnull-attribute

This option enables instrumentation of calls, checking whether null values are not passed to
arguments marked as requiring a non-null value by the nonnull function attribute.
-fsanitize=returns-nonnull-attribute
 This option enables instrumentation of return statements in functions marked
with returns_nonnull function attribute, to detect returning of null values from such functions.

-fsanitize=bool

This option enables instrumentation of loads from bool. If a value other than 0/1 is loaded, a run-
time error is issued.
-fsanitize=enum

This option enables instrumentation of loads from an enum type. If a value outside the range of
values for the enum type is loaded, a run-time error is issued.
-fsanitize=vptr

This option enables instrumentation of C++ member function calls, member accesses and some
conversions between pointers to base and derived classes, to verify the referenced object has the
correct dynamic type.
-fsanitize=pointer-overflow

This option enables instrumentation of pointer arithmetics. If the pointer arithmetics overflows, a
run-time error is issued.
-fsanitize=builtin

This option enables instrumentation of arguments to selected builtin functions. If an invalid value is
passed to such arguments, a run-time error is issued. E.g. passing 0 as the argument
to __builtin_ctz or __builtin_clz invokes undefined behavior and is diagnosed by this option.

Note that sanitizers tend to increase the rate of false positive warnings, most notably those around -Wmaybe-
uninitialized. We recommend against combining -Werror and [the use of] sanitizers.

While -ftrapv causes traps for signed overflows to be emitted, -fsanitize=undefined gives a diagnostic
message. This currently works only for the C family of languages.
-fno-sanitize=all

This option disables all previously enabled sanitizers. -fsanitize=all is not allowed, as some sanitizers
cannot be used together.

-fasan-shadow-offset=number

This option forces GCC to use custom shadow offset in AddressSanitizer checks. It is useful for
experimenting with different shadow memory layouts in Kernel AddressSanitizer.
-fsanitize-sections=s1,s2,...

Sanitize global variables in selected user-defined sections. si may contain wildcards.

-fsanitize-recover[=opts]

-fsanitize-recover= controls error recovery mode for sanitizers mentioned in comma-separated list of opts.
Enabling this option for a sanitizer component causes it to attempt to continue running the program as if no
error happened. This means multiple runtime errors can be reported in a single program run, and the exit
code of the program may indicate success even when errors have been reported. The -fno-sanitize-
recover= option can be used to alter this behavior: only the first detected error is reported and program then
exits with a non-zero exit code.

Currently this feature only works for -fsanitize=undefined (and its suboptions except for -
fsanitize=unreachable and -fsanitize=return), -fsanitize=float-cast-overflow, -fsanitize=float-divide-by-
zero, -fsanitize=bounds-strict, -fsanitize=kernel-address and -fsanitize=address. For these sanitizers error
recovery is turned on by default, except -fsanitize=address, for which this feature is experimental. -
fsanitize-recover=all and -fno-sanitize-recover=all is also accepted, the former enables recovery for all
sanitizers that support it, the latter disables recovery for all sanitizers that support it.

Even if a recovery mode is turned on the compiler side, it needs to be also enabled on the runtime library
side, otherwise the failures are still fatal. The runtime library defaults to halt_on_error=0 for ThreadSanitizer
and UndefinedBehaviorSanitizer, while default value for AddressSanitizer is halt_on_error=1. This can be
overridden through setting the halt_on_error flag in the corresponding environment variable.
 Syntax without an explicit opts parameter is deprecated. It is equivalent to specifying an opts list of:

undefined,float-cast-overflow,float-divide-by-zero,bounds-strict

-fsanitize-address-use-after-scope

Enable sanitization of local variables to detect use-after-scope bugs. The option sets -fstack-reuse to ‘none’.

-fsanitize-trap[=opts]

The -fsanitize-trap= option instructs the compiler to report for sanitizers mentioned in comma-separated
list of opts undefined behavior using __builtin_trap rather than a libubsan library routine. If this option is
enabled for certain sanitizer, it takes precedence over the -fsanitizer-recover= for that
sanitizer, __builtin_trap will be emitted and be fatal regardless of whether recovery is enabled or disabled
using -fsanitize-recover=.

The advantage of this is that the libubsan library is not needed and is not linked in, so this is usable even in
freestanding environments.

Currently this feature works with -fsanitize=undefined (and its suboptions except for -fsanitize=vptr), -
fsanitize=float-cast-overflow, -fsanitize=float-divide-by-zero and -fsanitize=bounds-strict. -fsanitize-
trap=all can be also specified, which enables it for undefined suboptions, -fsanitize=float-cast-overflow, -
fsanitize=float-divide-by-zero and -fsanitize=bounds-strict. If -fsanitize-trap=undefined or -fsanitize-
trap=all is used and -fsanitize=vptr is enabled on the command line, the instrumentation is silently ignored
as the instrumentation always needs libubsan support, -fsanitize-trap=vptr is not allowed.

-fsanitize-undefined-trap-on-error

The -fsanitize-undefined-trap-on-error option is deprecated equivalent of -fsanitize-trap=all.

-fsanitize-coverage=trace-pc

Enable coverage-guided fuzzing code instrumentation. Inserts a call to __sanitizer_cov_trace_pc into every
basic block.

-fsanitize-coverage=trace-cmp

Enable dataflow guided fuzzing code instrumentation. Inserts a call

to __sanitizer_cov_trace_cmp1, __sanitizer_cov_trace_cmp2, __sanitizer_cov_trace_cmp4 or __sanitizer_cov_trace
integral comparison with both operands variable
or __sanitizer_cov_trace_const_cmp1, __sanitizer_cov_trace_const_cmp2, __sanitizer_cov_trace_const_cmp4 or __s
integral comparison with one operand
constant, __sanitizer_cov_trace_cmpf or __sanitizer_cov_trace_cmpd for float or double comparisons
and __sanitizer_cov_trace_switch for switch statements.