Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 398b8e86ab421592f9e72b92c4558ea865b26e86 / . / docs / AddressSanitizer.html
blob: 397eafc2d51b1785e9ff635968a2b76e10804a0e [file] [log] [blame]
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
4<html>
5<head>
6 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
7 <title>AddressSanitizer, a fast memory error detector</title>
8 <link type="text/css" rel="stylesheet" href="../menu.css">
9 <link type="text/css" rel="stylesheet" href="../content.css">
10 <style type="text/css">
11 td {
12 vertical-align: top;
13 }
14 </style>
15</head>
16<body>
17
18<!--#include virtual="../menu.html.incl"-->
19
Kostya Serebryany7a31d7b2011-11-28 22:34:10 +0000[diff] [blame]20<div id="content">
21
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]22<h1>AddressSanitizer</h1>
23<ul>
Kostya Serebryanycef57e52012-04-23 09:05:50 +0000[diff] [blame]24 <li> <a href="#intro">Introduction</a>
25 <li> <a href="#howtobuild">How to Build</a>
26 <li> <a href="#usage">Usage</a>
27 <ul><li> <a href="#has_feature">__has_feature(address_sanitizer)</a></ul>
28 <ul><li> <a href="#no_address_safety_analysis">
29 __attribute__((no_address_safety_analysis))</a></ul>
30 <li> <a href="#platforms">Supported Platforms</a>
31 <li> <a href="#limitations">Limitations</a>
32 <li> <a href="#status">Current Status</a>
33 <li> <a href="#moreinfo">More Information</a>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]34</ul>
35
36<h2 id="intro">Introduction</h2>
37AddressSanitizer is a fast memory error detector.
38It consists of a compiler instrumentation module and a run-time library.
39The tool can detect the following types of bugs:
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]40<ul> <li> Out-of-bounds accesses to heap, stack and globals
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]41 <li> Use-after-free
42 <li> Use-after-return (to some extent)
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]43 <li> Double-free, invalid free
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]44</ul>
45Typical slowdown introduced by AddressSanitizer is <b>2x</b>.
46
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]47<h2 id="howtobuild">How to build</h2>
Alexey Samsonovadea5172012-10-24 13:21:51 +0000[diff] [blame]48Follow the <a href="../get_started.html">clang build instructions</a>.
49CMake build is supported.<BR>
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]50
Benjamin Kramer665a8dc2012-01-15 15:26:07 +0000[diff] [blame]51<h2 id="usage">Usage</h2>
Alexey Samsonove246d902012-11-06 16:19:11 +0000[diff] [blame]52Simply compile and link your program with <tt>-fsanitize=address</tt> flag. <BR>
Kostya Serebryany460e7a22012-10-19 07:00:46 +0000[diff] [blame]53The AddressSanitizer run-time library should be linked to the final executable,
54so make sure to use <tt>clang</tt> (not <tt>ld</tt>) for the final link step.<BR>
55When linking shared libraries, the AddressSanitizer run-time is not linked,
56so <tt>-Wl,-z,defs</tt> may cause link errors (don't use it with AddressSanitizer). <BR>
57
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]58To get a reasonable performance add <tt>-O1</tt> or higher. <BR>
Kostya Serebryanye683fd92012-01-06 17:35:27 +0000[diff] [blame]59To get nicer stack traces in error messages add
60<tt>-fno-omit-frame-pointer</tt>. <BR>
Kostya Serebryanyf5249f52012-01-23 18:50:23 +0000[diff] [blame]61To get perfect stack traces you may need to disable inlining (just use <tt>-O1</tt>) and tail call
Alexey Samsonovadea5172012-10-24 13:21:51 +0000[diff] [blame]62elimination (<tt>-fno-optimize-sibling-calls</tt>).
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]63
64<pre>
65% cat example_UseAfterFree.cc
66int main(int argc, char **argv) {
67 int *array = new int[100];
68 delete [] array;
69 return array[argc]; // BOOM
70}
71</pre>
72
73<pre>
Kostya Serebryany460e7a22012-10-19 07:00:46 +0000[diff] [blame]74# Compile and link
Alexey Samsonove246d902012-11-06 16:19:11 +0000[diff] [blame]75% clang -O1 -g -fsanitize=address -fno-omit-frame-pointer example_UseAfterFree.cc
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]76</pre>
Kostya Serebryany460e7a22012-10-19 07:00:46 +0000[diff] [blame]77OR
78<pre>
79# Compile
Alexey Samsonove246d902012-11-06 16:19:11 +0000[diff] [blame]80% clang -O1 -g -fsanitize=address -fno-omit-frame-pointer -c example_UseAfterFree.cc
Kostya Serebryany460e7a22012-10-19 07:00:46 +0000[diff] [blame]81# Link
Alexey Samsonove246d902012-11-06 16:19:11 +0000[diff] [blame]82% clang -g -fsanitize=address example_UseAfterFree.o
Kostya Serebryany460e7a22012-10-19 07:00:46 +0000[diff] [blame]83</pre>
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]84
85If a bug is detected, the program will print an error message to stderr and exit with a
Kostya Serebryanyb8769932011-12-02 00:24:42 +0000[diff] [blame]86non-zero exit code.
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]87Currently, AddressSanitizer does not symbolize its output, so you may need to use a
88separate script to symbolize the result offline (this will be fixed in future).
89<pre>
90% ./a.out 2> log
91% projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
92==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
93READ of size 4 at 0x7f7ddab8c084 thread T0
94 #0 0x403c8c in main example_UseAfterFree.cc:4
95 #1 0x7f7ddabcac4d in __libc_start_main ??:0
960x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210)
97freed by thread T0 here:
98 #0 0x404704 in operator delete[](void*) ??:0
99 #1 0x403c53 in main example_UseAfterFree.cc:4
100 #2 0x7f7ddabcac4d in __libc_start_main ??:0
101previously allocated by thread T0 here:
102 #0 0x404544 in operator new[](unsigned long) ??:0
103 #1 0x403c43 in main example_UseAfterFree.cc:2
104 #2 0x7f7ddabcac4d in __libc_start_main ??:0
105==9442== ABORTING
106</pre>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]107
Kostya Serebryanyecf7cc12012-10-30 05:07:05 +0000[diff] [blame]108AddressSanitizer exits on the first detected error. This is by design.
109One reason: it makes the generated code smaller and faster (both by ~5%).
110Another reason: this makes fixing bugs unavoidable. With Valgrind, it is often
111the case that users treat Valgrind warnings as false positives
112(which they are not) and don't fix them.
113
114
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]115<h3 id="has_feature">__has_feature(address_sanitizer)</h3>
116In some cases one may need to execute different code depending on whether
117AddressSanitizer is enabled.
118<a href="LanguageExtensions.html#__has_feature_extension">__has_feature</a>
119can be used for this purpose.
120<pre>
Kostya Serebryanyf45f2342012-07-02 11:00:33 +0000[diff] [blame]121#if defined(__has_feature)
122# if __has_feature(address_sanitizer)
123 code that builds only under AddressSanitizer
124# endif
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]125#endif
126</pre>
127
Kostya Serebryanycef57e52012-04-23 09:05:50 +0000[diff] [blame]128<h3 id="no_address_safety_analysis">__attribute__((no_address_safety_analysis))</h3>
Alexey Samsonovadea5172012-10-24 13:21:51 +0000[diff] [blame]129Some code should not be instrumented by AddressSanitizer.
130One may use the function attribute
Kostya Serebryanycef57e52012-04-23 09:05:50 +0000[diff] [blame]131<a href="LanguageExtensions.html#address_sanitizer">
132 <tt>no_address_safety_analysis</tt></a>
133to disable instrumentation of a particular function.
Kostya Serebryanyf45f2342012-07-02 11:00:33 +0000[diff] [blame]134This attribute may not be supported by other compilers, so we suggest to
135use it together with <tt>__has_feature(address_sanitizer)</tt>.
Kostya Serebryanycef57e52012-04-23 09:05:50 +0000[diff] [blame]136Note: currently, this attribute will be lost if the function is inlined.
137
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]138<h2 id="platforms">Supported Platforms</h2>
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]139AddressSanitizer is supported on
Kostya Serebryany460e7a22012-10-19 07:00:46 +0000[diff] [blame]140<ul><li>Linux i386/x86_64 (tested on Ubuntu 10.04 and 12.04).
Alexey Samsonova8ee4412012-09-06 09:49:03 +0000[diff] [blame]141<li>MacOS 10.6, 10.7 and 10.8 (i386/x86_64).
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]142</ul>
Kostya Serebryany460e7a22012-10-19 07:00:46 +0000[diff] [blame]143Support for Linux ARM (and Android ARM) is in progress
Kostya Serebryanyabc31ca2012-03-15 16:20:29 +0000[diff] [blame]144(it may work, but is not guaranteed too).
145
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]146
147<h2 id="limitations">Limitations</h2>
148<ul>
Kostya Serebryanycef57e52012-04-23 09:05:50 +0000[diff] [blame]149<li> AddressSanitizer uses more real memory than a native run.
Alexey Samsonovadea5172012-10-24 13:21:51 +0000[diff] [blame]150Exact overhead depends on the allocations sizes. The smaller the
151allocations you make the bigger the overhead is.
Kostya Serebryanycef57e52012-04-23 09:05:50 +0000[diff] [blame]152<li> AddressSanitizer uses more stack memory. We have seen up to 3x increase.
153<li> On 64-bit platforms AddressSanitizer maps (but not reserves)
15416+ Terabytes of virtual address space.
155This means that tools like <tt>ulimit</tt> may not work as usually expected.
156<li> Static linking is not supported.
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]157</ul>
158
159
160<h2 id="status">Current Status</h2>
Kostya Serebryany219cd6c2012-04-23 10:15:18 +0000[diff] [blame]161AddressSanitizer is fully functional on supported platforms starting from LLVM 3.1.
Alexey Samsonovadea5172012-10-24 13:21:51 +0000[diff] [blame]162The test suite is integrated into CMake build and can be run with
163<tt>make check-asan</tt> command.
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]164
165<h2 id="moreinfo">More Information</h2>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]166<a href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a>.
167
168
Kostya Serebryany7a31d7b2011-11-28 22:34:10 +0000[diff] [blame]169</div>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]170</body>
171</html>