Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / clang / 303aae98a5a27f2595d023c0b4e1484bf2c0ee57 / . / docs / AddressSanitizer.html
blob: e6f7e990478b34dc0a901c19aa9914d44e4c86c6 [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>
24 <li> <a href="intro">Introduction</a>
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]25 <li> <a href="howtobuild">How to Build</a>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]26 <li> <a href="usage">Usage</a>
27 <ul><li> <a href="has_feature">__has_feature(address_sanitizer)</a></ul>
28 <li> <a href="platforms">Supported Platforms</a>
29 <li> <a href="limitations">Limitations</a>
30 <li> <a href="status">Current Status</a>
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]31 <li> <a href="moreinfo">More Information</a>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]32</ul>
33
34<h2 id="intro">Introduction</h2>
35AddressSanitizer is a fast memory error detector.
36It consists of a compiler instrumentation module and a run-time library.
37The tool can detect the following types of bugs:
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]38<ul> <li> Out-of-bounds accesses to heap, stack and globals
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]39 <li> Use-after-free
40 <li> Use-after-return (to some extent)
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]41 <li> Double-free, invalid free
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]42</ul>
43Typical slowdown introduced by AddressSanitizer is <b>2x</b>.
44
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]45<h2 id="howtobuild">How to build</h2>
46Follow the <a href="../get_started.html">clang build instructions</a>.
47
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]48<h2 id="intro">Usage</h2>
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]49Simply compile and link your program with <tt>-faddress-sanitizer</tt> flag. <BR>
50To get a reasonable performance add <tt>-O1</tt> or higher. <BR>
51
52<pre>
53% cat example_UseAfterFree.cc
54int main(int argc, char **argv) {
55 int *array = new int[100];
56 delete [] array;
57 return array[argc]; // BOOM
58}
59</pre>
60
61<pre>
62% clang -O1 -g -faddress-sanitizer example_UseAfterFree.cc
63</pre>
64
65If 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]66non-zero exit code.
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]67Currently, AddressSanitizer does not symbolize its output, so you may need to use a
68separate script to symbolize the result offline (this will be fixed in future).
69<pre>
70% ./a.out 2> log
71% projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
72==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
73READ of size 4 at 0x7f7ddab8c084 thread T0
74 #0 0x403c8c in main example_UseAfterFree.cc:4
75 #1 0x7f7ddabcac4d in __libc_start_main ??:0
760x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210)
77freed by thread T0 here:
78 #0 0x404704 in operator delete[](void*) ??:0
79 #1 0x403c53 in main example_UseAfterFree.cc:4
80 #2 0x7f7ddabcac4d in __libc_start_main ??:0
81previously allocated by thread T0 here:
82 #0 0x404544 in operator new[](unsigned long) ??:0
83 #1 0x403c43 in main example_UseAfterFree.cc:2
84 #2 0x7f7ddabcac4d in __libc_start_main ??:0
85==9442== ABORTING
86</pre>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]87
88<h3 id="has_feature">__has_feature(address_sanitizer)</h3>
89In some cases one may need to execute different code depending on whether
90AddressSanitizer is enabled.
91<a href="LanguageExtensions.html#__has_feature_extension">__has_feature</a>
92can be used for this purpose.
93<pre>
94#if defined(__has_feature) && __has_feature(address_sanitizer)
95 code that runs only under AddressSanitizer
96#else
97 code that does not run under AddressSanitizer
98#endif
99</pre>
100
101<h2 id="platforms">Supported Platforms</h2>
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]102AddressSanitizer is supported on
103<ul><li>Linux x86_64 (tested on Ubuntu 10.04).
104<li>MacOS 10.6 i386/x86_64.
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]105</ul>
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]106Support for Linux i386/ARM and MacOS 10.7 is in progress.
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]107
108<h2 id="limitations">Limitations</h2>
109<ul>
110 <li> AddressSanitizer uses more real memory than a native run.
111 How much -- depends on the allocations sizes. The smaller the
112 allocations you make the bigger the overhead.
113 <li> On 64-bit platforms AddressSanitizer maps (but not reserves)
114 16+ Terabytes of virtual address space.
115 This means that tools like <tt>ulimit</tt> may not work as usually expected.
116 <li> Static linking is not supported.
117</ul>
118
119
120<h2 id="status">Current Status</h2>
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]121AddressSanitizer is fully functional on supported platforms in LLVM head.
122However, the test suite is not fully integrated yet and we lack the testing
123process (buildbots).
124
125<h2 id="moreinfo">More Information</h2>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]126<a href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a>.
127
128
Kostya Serebryany7a31d7b2011-11-28 22:34:10 +0000[diff] [blame]129</div>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]130</body>
131</html>