The GCC manual contains next to no documentation about the use of the various -fsanitize options. At the moment, the best source of information are 3rd party sites like the google AddressSanitizer wiki <https://code.google.com/p/address-sanitizer/wiki/AddressSanitizer> which refer primarily to LLVM/Clang; it's not clear how applicable they are to the current sanitizer implementations in GCC. The GCC manual should contain a proper description of the sanitizer functionality.
https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging-Options What exactly are you missing?
Just for reference this is the documentation that is included in GCC (minus the formating): -fsanitize=address Enable AddressSanitizer, a fast memory error detector. Memory access instructions are instrumented to detect out-of-bounds and use-after-free bugs. See http://code.google.com/p/address-sanitizer/ for more details. The run-time behavior can be influenced using the ASAN_OPTIONS environment variable; see https://code.google.com/p/address-sanitizer/wiki/Flags#Run-time_flags for a list of supported options. -fsanitize=kernel-address Enable AddressSanitizer for Linux kernel. See http://code.google.com/p/address-sanitizer/wiki/AddressSanitizerForKernel for more details. -fsanitize=thread Enable ThreadSanitizer, a fast data race detector. Memory access instructions are instrumented to detect data race bugs. See http://code.google.com/p/thread-sanitizer/ for more details. The run-time behavior can be influenced using the TSAN_OPTIONS environment variable; see https://code.google.com/p/thread-sanitizer/wiki/Flags for a list of supported options. -fsanitize=leak Enable LeakSanitizer, a memory leak detector. This option only matters for linking of executables and if neither -fsanitize=address nor -fsanitize=thread is used. In that case the executable is linked against a library that overrides malloc and other allocator functions. See https://code.google.com/p/address-sanitizer/wiki/LeakSanitizer for more details. The run-time behavior can be influenced using the LSAN_OPTIONS environment variable. -fsanitize=undefined Enable UndefinedBehaviorSanitizer, a fast undefined behavior detector. Various computations are instrumented to detect undefined behavior at runtime. 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. -fsanitize=integer-divide-by-zero Detect integer division by zero as well as INT_MIN / -1 division. -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. 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. -fsanitize=bounds-strict This option enables strict instrumentation of array bounds. Most out of bounds accesses are detected, including flexible array members and 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_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. 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.
> https://gcc.gnu.org/onlinedocs/gcc/Debugging-Options.html#Debugging-Options > What exactly are you missing? Basically, I think the information from the address sanitizer wiki (and the other linked pages) should be integrated into the GCC manual, rather than the manual referring to the wiki, such that the manual is self-contained. The google code wiki only refers to LLVM, and it's not clear to the reader (to me at least) if it is still being maintained (given that "Google Code will be turning read-only") and to what extent it applies to GCC. Moreover, the undefined behavior sanitizer runtime options (UBSAN_OPTIONS, as described here <https://www.chromium.org/developers/testing/undefinedbehaviorsanitizer>) aren't documented at all in the manual.
LLVM is were all new Sanitizer development happens. gcc's libsanitizer just merges from upstream from time to time. I don't think that duplicating all documentation is necessary.
(In reply to smagnet from comment #3) > Moreover, the undefined behavior sanitizer runtime options (UBSAN_OPTIONS, > as described here > <https://www.chromium.org/developers/testing/undefinedbehaviorsanitizer>) > aren't documented at all in the manual. UBSAN_OPTIONS isn't currently supported by GCC. (In reply to Markus Trippelsdorf from comment #4) > LLVM is were all new Sanitizer development happens. > gcc's libsanitizer just merges from upstream from time to time. > > I don't think that duplicating all documentation is necessary. Agreed.
(In reply to Markus Trippelsdorf from comment #4) > LLVM is were all new Sanitizer development happens. > gcc's libsanitizer just merges from upstream from time to time. > > I don't think that duplicating all documentation is necessary. Perhaps we could at least mention upstream site in GCC docs?
(In reply to Marek Polacek from comment #5) > (In reply to smagnet from comment #3) > > Moreover, the undefined behavior sanitizer runtime options (UBSAN_OPTIONS, > > as described here > > <https://www.chromium.org/developers/testing/undefinedbehaviorsanitizer>) > > aren't documented at all in the manual. > > UBSAN_OPTIONS isn't currently supported by GCC. These kind of divergences give reason to think that the sanitizers should be further documented in the GCC manual. Another example is the range of supported platforms: GCC's sanitizer could in principle support different ones (more? fewer?) than Clang's. I'm not saying that anyone should stop working on what they are doing to implement this, but if a volunteer appears (Smagnet?) and wants to work on this, why not allow them? Perhaps they can create better documentation than the official one.
(In reply to Manuel López-Ibáñez from comment #7) > I'm not saying that anyone should stop working on what they are doing to > implement this, but if a volunteer appears (Smagnet?) and wants to work on > this, why not allow them? Perhaps they can create better documentation than > the official one. Hi, It can make sense to create _some_ sanitizer-related docs in gcc. For example clang has one: http://clang.llvm.org/docs/AddressSanitizer.html Such page can give a "quick start" guide and also thoroughly document gcc-specifics (e.g. attributes, macros, features, etc). But I don't think it is a good idea to duplicate everything. Some people will look at the "official" documentation and be confused, gcc-hosted docs will get outdated in some ways as well. And we are interested in improving the "official" docs. Maybe we need to think about a clear way to document gcc- and clang-specific aspects, and actually do that throughout the docs. Sanitizers will move to github soon: https://github.com/google/sanitizers Then it will be easier to accept pull requests for docs changes.
(In reply to Dmitry Vyukov from comment #8) > (In reply to Manuel López-Ibáñez from comment #7) > > I'm not saying that anyone should stop working on what they are doing to > > implement this, but if a volunteer appears (Smagnet?) and wants to work on > > this, why not allow them? Perhaps they can create better documentation than > > the official one. > It can make sense to create _some_ sanitizer-related docs in gcc. For > example clang has one: > http://clang.llvm.org/docs/AddressSanitizer.html > Such page can give a "quick start" guide and also thoroughly document > gcc-specifics (e.g. attributes, macros, features, etc). But I don't think it > is a good idea to duplicate everything. Some people will look at the > "official" documentation and be confused, gcc-hosted docs will get outdated > in some ways as well. FYI this has already led to mismatches and user confusion several times. > And we are interested in improving the "official" docs. Maybe we need to > think about a clear way to document gcc- and clang-specific aspects, and > actually do that throughout the docs. > Sanitizers will move to github soon: > https://github.com/google/sanitizers > Then it will be easier to accept pull requests for docs changes. Perhaps GCC docs could be hosted on github as well and then (automatically) copied to GCC trunk during regular ASan merge process?
(In reply to Marek Polacek from comment #5) > (In reply to smagnet from comment #3) > > Moreover, the undefined behavior sanitizer runtime options (UBSAN_OPTIONS, > > as described here > > <https://www.chromium.org/developers/testing/undefinedbehaviorsanitizer>) > > aren't documented at all in the manual. > > UBSAN_OPTIONS isn't currently supported by GCC. Are you sure? I've been using it with libubsan in GCC trunk...
(In reply to Yury Gribov from comment #10) > Are you sure? I've been using it with libubsan in GCC trunk... Ah, ok, it seems to work: $ UBSAN_OPTIONS=print_stacktrace=1 ./a.out r.c:6:10: runtime error: signed integer overflow: 2147483647 + 1 cannot be represented in type 'int' #0 0x400712 in foo (/home/marek/x/trunk/gcc/a.out+0x400712) #1 0x400729 in main (/home/marek/x/trunk/gcc/a.out+0x400729) #2 0x3a498206ff in __libc_start_main (/lib64/libc.so.6+0x3a498206ff) #3 0x400618 in _start (/home/marek/x/trunk/gcc/a.out+0x400618)