Re: [PATCH] D15217: Clang documentation for UBSan.

[Alexey Samsonov via cfe-commits]

samsonov added a comment.

Thanks! Addressed the comments.


Repository:
  rL LLVM

http://reviews.llvm.org/D15217



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

Re: [PATCH] D15217: Clang documentation for UBSan.

[Alexey Samsonov via cfe-commits]

This revision was automatically updated to reflect the committed changes.
samsonov marked 5 inline comments as done.
Closed by commit rL254733: Clang documentation for UBSan. (authored by 
samsonov).

Changed prior to commit:
  http://reviews.llvm.org/D15217?vs=41823&id=41891#toc

Repository:
  rL LLVM

http://reviews.llvm.org/D15217

Files:
  cfe/trunk/docs/UndefinedBehaviorSanitizer.rst
  cfe/trunk/docs/UsersManual.rst
  cfe/trunk/docs/index.rst

Index: cfe/trunk/docs/UndefinedBehaviorSanitizer.rst
===
--- cfe/trunk/docs/UndefinedBehaviorSanitizer.rst
+++ cfe/trunk/docs/UndefinedBehaviorSanitizer.rst
@@ -0,0 +1,202 @@
+==
+UndefinedBehaviorSanitizer
+==
+
+.. contents::
+   :local:
+
+Introduction
+
+
+UndefinedBehaviorSanitizer (UBSan) is a fast undefined behavior detector.
+UBSan modifies the program at compile-time to catch various kinds of undefined
+behavior during program execution, for example:
+
+* Using misaligned or null pointer
+* Signed integer overflow
+* Conversion to, from, or between floating-point types which would
+  overflow the destination
+
+See the full list of available :ref:`checks ` below.
+
+UBSan has an optional run-time library which provides better error reporting.
+The checks have small runtime cost and no impact on address space layout or ABI.
+
+How to build
+
+
+Build LLVM/Clang with `CMake `_.
+
+Usage
+=
+
+Use ``clang++`` to compile and link your program with ``-fsanitize=undefined``
+flag. Make sure to use ``clang++`` (not ``ld``) as a linker, so that your
+executable is linked with proper UBSan runtime libraries. You can use ``clang``
+instead of ``clang++`` if you're compiling/linking C code.
+
+.. code-block:: console
+
+  % cat test.cc
+  int main(int argc, char **argv) {
+int k = 0x7fff;
+k += argc;
+return 0;
+  }
+  % clang++ -fsanitize=undefined test.cc
+  % ./a.out
+  test.cc:3:5: runtime error: signed integer overflow: 2147483647 + 1 cannot be represented in type 'int'
+
+You can enable only a subset of :ref:`checks ` offered by UBSan,
+and define the desired behavior for each kind of check:
+
+* print a verbose error report and continue execution (default);
+* print a verbose error report and exit the program;
+* execute a trap instruction (doesn't require UBSan run-time support).
+
+For example if you compile/link your program as:
+
+.. code-block:: console
+
+  % clang++ -fsanitize=signed-integer-overflow,null,alignment -fno-sanitize-recover=null -fsanitize-trap=alignment
+
+the program will continue execution after signed integer overflows, exit after
+the first invalid use of a null pointer, and trap after the first use of misaligned
+pointer.
+
+.. _ubsan-checks:
+
+Availablle checks
+=
+
+Available checks are:
+
+  -  ``-fsanitize=alignment``: Use of a misaligned pointer or creation
+ of a misaligned reference.
+  -  ``-fsanitize=bool``: Load of a ``bool`` value which is neither
+ ``true`` nor ``false``.
+  -  ``-fsanitize=bounds``: Out of bounds array indexing, in cases
+ where the array bound can be statically determined.
+  -  ``-fsanitize=enum``: Load of a value of an enumerated type which
+ is not in the range of representable values for that enumerated
+ type.
+  -  ``-fsanitize=float-cast-overflow``: Conversion to, from, or
+ between floating-point types which would overflow the
+ destination.
+  -  ``-fsanitize=float-divide-by-zero``: Floating point division by
+ zero.
+  -  ``-fsanitize=function``: Indirect call of a function through a
+ function pointer of the wrong type (Linux, C++ and x86/x86_64 only).
+  -  ``-fsanitize=integer-divide-by-zero``: Integer division by zero.
+  -  ``-fsanitize=nonnull-attribute``: Passing null pointer as a function
+ parameter which is declared to never be null.
+  -  ``-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=returns-nonnull-attribute``: Returning null pointer
+ from a function which is declared to never return null.
+  -  ``-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++. You can use ``-fsanitize=shift-base`` or
+ ``-fsanitiz

Re: [PATCH] D15217: Clang documentation for UBSan.

[Dan Albert via cfe-commits]

danalbert added inline comments.


Comment at: docs/UndefinedBehaviorSanitizer.rst:128
@@ +127,3 @@
+ ``-fsanitize=undefined``.
+  -  ``-fsanitize=integer``: Checks for undefined or suspicious integer
+ behavior.

rsmith wrote:
> danalbert wrote:
> > Suspicious here meaning that it also checks undefined overflow? Might want 
> > to clarify.
> You mean "defined" rather than "undefined", right? :)
I actually meant unsigned, but yes, same thing :)


http://reviews.llvm.org/D15217



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

Re: [PATCH] D15217: Clang documentation for UBSan.

[Sean Silva via cfe-commits]

silvas accepted this revision.
silvas added a comment.

Thanks for working on this!

A tiny nit, but otherwise this LGTM.



Comment at: docs/UndefinedBehaviorSanitizer.rst:33
@@ +32,3 @@
+
+Use ``clang++`` to compile and link your program with ``-fsanitize=undefined``
+flag. Make sure to use ``clang++`` (not ``ld``) as a linker, so that your

We support C as well, right? (not a big deal, just mention that this document 
will focus on C++ usage but C usage is similar)


http://reviews.llvm.org/D15217



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

Re: [PATCH] D15217: Clang documentation for UBSan.

[Richard Smith via cfe-commits]

rsmith accepted this revision.
This revision is now accepted and ready to land.


Comment at: docs/UndefinedBehaviorSanitizer.rst:128
@@ +127,3 @@
+ ``-fsanitize=undefined``.
+  -  ``-fsanitize=integer``: Checks for undefined or suspicious integer
+ behavior.

danalbert wrote:
> Suspicious here meaning that it also checks undefined overflow? Might want to 
> clarify.
You mean "defined" rather than "undefined", right? :)


Comment at: docs/UndefinedBehaviorSanitizer.rst:178
@@ +177,3 @@
+
+and for for the following architectures:
+

Typo 'for for'


http://reviews.llvm.org/D15217



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits

Re: [PATCH] D15217: Clang documentation for UBSan.

[Dan Albert via cfe-commits]

danalbert added inline comments.


Comment at: docs/UndefinedBehaviorSanitizer.rst:128
@@ +127,3 @@
+ ``-fsanitize=undefined``.
+  -  ``-fsanitize=integer``: Checks for undefined or suspicious integer
+ behavior.

Suspicious here meaning that it also checks undefined overflow? Might want to 
clarify.


http://reviews.llvm.org/D15217



___
cfe-commits mailing list
cfe-commits@lists.llvm.org
http://lists.llvm.org/cgi-bin/mailman/listinfo/cfe-commits