ceph/src/boost/tools/build/example/sanitizers/readme.adoc

   1 ////
   2 Copyright 2019 Damian Jarek
   3 Distributed under the Boost Software License, Version 1.0.
   4 (See accompanying file LICENSE_1_0.txt or http://www.boost.org/LICENSE_1_0.txt)
   5 ////
   6
   7 = Sanitizers
   8
   9 This example shows how to enable sanitizers when using a clang or gcc toolset
  10
  11 .`main.cpp`
  12 [source,cpp]
  13 ----
  14 include::../../example/sanitizers/main.cpp[tag=source]
  15 ----
  16
  17 Our `jamroot.jam` is minimal and only specifies one `exe` target for the
  18 program:
  19
  20 .`jamroot.jam`
  21 [source,jam]
  22 ----
  23 include::jamroot.jam[]
  24 ----
  25
  26 Sanitizers can be enabled by passing `on` or `norecover` to the appropriate sanitizer feature
  27 (e.g. `thread-sanitizer=on`). The `norecover` option causes the program to terminate after
  28 the first sanitizer issue is detected. The following example shows how to enable `address` and `undefined`
  29 sanitizers in a simple program:
  30
  31 [source,bash]
  32 ----
  33 > cd /example/sanitizers
  34 > b2 toolset=gcc address-sanitizer=norecover undefined-sanitizer=on
  35 ...found 10 targets...
  36 ...updating 7 targets...
  37 gcc.compile.c++ bin/gcc-7.3.0/debug/address-sanitizer-norecover/undefined-sanitizer-on/main.o
  38 gcc.link bin/gcc-7.3.0/debug/address-sanitizer-norecover/undefined-sanitizer-on/main
  39 ...updated 7 targets...
  40 ----
  41
  42 Running the produced program may produce an output simillar to the following:
  43
  44 [source,bash]
  45 ----
  46 > ./bin/gcc-7.3.0/debug/address-sanitizer-norecover/undefined-sanitizer-on/main
  47 Hello sanitizers
  48 main.cpp:6:43: runtime error: load of null pointer of type 'char'
  49 ASAN:DEADLYSIGNAL
  50 =================================================================
  51 ==29767==ERROR: AddressSanitizer: SEGV on unknown address 0x000000000000 (pc 0x55ba7988af1b bp 0x7ffdf3d76560 sp 0x7ffdf3d76530 T0)
  52 ==29767==The signal is caused by a READ memory access.
  53 ==29767==Hint: address points to the zero page.
  54     #0 0x55ba7988af1a in main /home/damian/projects/boost/tools/build/example/sanitizers/main.cpp:6
  55     #1 0x7f42f2ba1b96 in __libc_start_main (/lib/x86_64-linux-gnu/libc.so.6+0x21b96)
  56     #2 0x55ba7988adb9 in _start (/home/damian/projects/boost/tools/build/example/sanitizers/bin/gcc-7.3.0/debug/address-sanitizer-norecover/undefined-sanitizer-on/main+0xdb9)
  57
  58 AddressSanitizer can not provide additional info.
  59 SUMMARY: AddressSanitizer: SEGV /home/damian/projects/boost/tools/build/example/sanitizers/main.cpp:6 in main
  60 ==29767==ABORTING
  61 ----
  62
  63 NOTE: The actual paths in the `bin` sub-directory will depend on your
  64 toolset and configuration. The presented output may vary depending on your compiler version.