From fd9d0e13a17b915fa6b35e3a3465513d67f1482d Mon Sep 17 00:00:00 2001 From: Richard Smith Date: Tue, 6 Nov 2012 19:23:14 +0000 Subject: [PATCH] Updates to user's manual and release notes for -fsanitize= options. git-svn-id: https://llvm.org/svn/llvm-project/cfe/trunk@167479 91177308-0d34-0410-b5e6-96231b3b80d8 --- docs/ReleaseNotes.html | 7 +++- docs/UsersManual.html | 90 ++++++++++++++++++++++++++++-------------- 2 files changed, 66 insertions(+), 31 deletions(-) diff --git a/docs/ReleaseNotes.html b/docs/ReleaseNotes.html index 78108fb9db..8a195f0b83 100644 --- a/docs/ReleaseNotes.html +++ b/docs/ReleaseNotes.html @@ -170,11 +170,14 @@ int f(vector<map<int, double>>); -
  • Clang's -fcatch-undefined-behavior option has grown the ability - to check for several new types of undefined behavior. +
  • Clang's -fcatch-undefined-behavior option has been renamed to + -fsanitize=undefined and has grown the ability to check for several + new types of undefined behavior. See the Users Manual for more information. + +
    • diff --git a/docs/UsersManual.html b/docs/UsersManual.html index 50a373886a..35fc5dca33 100644 --- a/docs/UsersManual.html +++ b/docs/UsersManual.html @@ -874,45 +874,77 @@ likely to affect PCH files that reference a large number of headers.

    -
    -fcatch-undefined-behavior: Turn -on runtime code generation to check for undefined behavior.
    +
    -fsanitize=check1,check2: Turn on runtime checks +for various forms of undefined behavior.
    + +
    This option controls whether Clang adds runtime checks for various forms of +undefined behavior, and is disabled by default. If a check fails, a diagnostic +message is produced at runtime explaining the problem. The main checks are: -
    This option, which defaults to off, controls whether or not Clang -adds runtime checks for undefined runtime behavior. If a check fails, -__builtin_trap() is used to indicate failure. -The currently implemented checks include:
      -
    • Subscripting where the static type of one operand is a variable - which is decayed from an array type and the other operand is - greater than the size of the array or less than zero.
      • -
    • Shift operators where the amount shifted is greater or equal to the - promoted bit-width of the left-hand-side or less than zero.
      • -
    • If control flow reaches __builtin_unreachable.
      • -
    • Reads and writes for objects which are inappropriately aligned or are not - large enough (in cases where the size can be determined). -
    • Signed integer overflow, including all the checks added by -ftrapv - and also checking for signed left shift overflow.
      • -
    • Binding a reference to a storage location which is not of an appropriate - alignment or size (in cases where the size can be determined), or binding - a reference to an empty glvalue (a dereferenced null pointer). -
    • Class member access or member function call where the this - pointer is not of an appropriate alignment or size (in cases where the size - can be determined), or where it is null.
      • +
    • -fsanitize=address: + AddressSanitizer, a memory error + detector.
      • +
    • -fsanitize=thread: + ThreadSanitizer, an experimental + data race detector. Not ready for widespread use.
      • +
    • -fsanitize=undefined: + Enables all the checks listed below.
    -

    The sizes of objects are determined using __builtin_object_size, and -consequently may be able to detect more problems at higher optimization levels. -Bit-fields and vectors are not yet checked.

    +The following more fine-grained checks are also available: +
      +
    • -fsanitize=alignment: + Use of a misaligned pointer or creation of a misaligned reference.
      • +
    • -fsanitize=divide-by-zero: + Division by zero.
      • +
    • -fsanitize=float-cast-overflow: + Conversion to, from, or between floating-point types which would overflow + the destination.
      • +
    • -fsanitize=null: + Use of a null pointer or creation of a null reference.
      • +
    • -fsanitize=object-size: + An attempt to use bytes which the optimizer can determine are not part of + the object being accessed. + The sizes of objects are determined using __builtin_object_size, and + consequently may be able to detect more problems at higher optimization + levels.
      • +
    • -fsanitize=return: + In C++, reaching the end of a value-returning function without returning a + value.
      • +
    • -fsanitize=shift: + Shift operators where the amount shifted is greater or equal to the + promoted bit-width of the left hand side or less than zero, or where + the left hand side is negative. For a signed left shift, also checks + for signed overflow in C, and for unsigned overflow in C++.
      • +
    • -fsanitize=signed-integer-overflow: + Signed integer overflow, including all the checks added by -ftrapv, + and checking for overflow in signed division (INT_MIN / -1).
      • +
    • -fsanitize=unreachable: + If control flow reaches __builtin_unreachable.
      • +
    • -fsanitize=vla-bound: + A variable-length array whose bound does not evaluate to a positive value.
      • +
    • -fsanitize=vptr: + Use of an object whose vptr indicates that it is of the wrong dynamic type, + or that its lifetime has not begun or has ended. Incompatible with + -fno-rtti.
      • +
    + +The -fsanitize= argument must also be provided when linking, in order +to link to the appropriate runtime library. It is not possible to combine the +-fsanitize=address and -fsanitize=thread checkers in the same +program.
    -f[no-]address-sanitizer: -Turn on AddressSanitizer, -a memory error detector. +Deprecated synonym for -f[no-]sanitize=address.
    -f[no-]thread-sanitizer: -Turn on ThreadSanitizer, an experimental data race detector. -Not ready for widespread use. +Deprecated synonym for -f[no-]sanitize=thread. + +
    -fcatch-undefined-behavior: +Deprecated synonym for -fsanitize=undefined.
    -fno-assume-sane-operator-new: Don't assume that the C++'s new operator is sane.
    -- 2.50.1