Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 32ad2ee2618745ce3da51c2ae066ed5f21157c07 / . / docs / AddressSanitizer.html
blob: d47eb0a62c894c1eb96eadc753ae67d3151de140 [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
Benjamin Kramer665a8dc2012-01-15 15:26:07 +0000[diff] [blame]48<h2 id="usage">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>
Kostya Serebryanye683fd92012-01-06 17:35:27 +0000[diff] [blame]51To get nicer stack traces in error messages add
52<tt>-fno-omit-frame-pointer</tt>. <BR>
Kostya Serebryanyf5249f52012-01-23 18:50:23 +0000[diff] [blame]53To get perfect stack traces you may need to disable inlining (just use <tt>-O1</tt>) and tail call
54elimination (</tt>-fno-optimize-sibling-calls</tt>).
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]55
56<pre>
57% cat example_UseAfterFree.cc
58int main(int argc, char **argv) {
59 int *array = new int[100];
60 delete [] array;
61 return array[argc]; // BOOM
62}
63</pre>
64
65<pre>
Kostya Serebryanye683fd92012-01-06 17:35:27 +0000[diff] [blame]66% clang -O1 -g -faddress-sanitizer -fno-omit-frame-pointer example_UseAfterFree.cc
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]67</pre>
68
69If 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]70non-zero exit code.
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]71Currently, AddressSanitizer does not symbolize its output, so you may need to use a
72separate script to symbolize the result offline (this will be fixed in future).
73<pre>
74% ./a.out 2> log
75% projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
76==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
77READ of size 4 at 0x7f7ddab8c084 thread T0
78 #0 0x403c8c in main example_UseAfterFree.cc:4
79 #1 0x7f7ddabcac4d in __libc_start_main ??:0
800x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210)
81freed by thread T0 here:
82 #0 0x404704 in operator delete[](void*) ??:0
83 #1 0x403c53 in main example_UseAfterFree.cc:4
84 #2 0x7f7ddabcac4d in __libc_start_main ??:0
85previously allocated by thread T0 here:
86 #0 0x404544 in operator new[](unsigned long) ??:0
87 #1 0x403c43 in main example_UseAfterFree.cc:2
88 #2 0x7f7ddabcac4d in __libc_start_main ??:0
89==9442== ABORTING
90</pre>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]91
92<h3 id="has_feature">__has_feature(address_sanitizer)</h3>
93In some cases one may need to execute different code depending on whether
94AddressSanitizer is enabled.
95<a href="LanguageExtensions.html#__has_feature_extension">__has_feature</a>
96can be used for this purpose.
97<pre>
Benjamin Kramer665a8dc2012-01-15 15:26:07 +0000[diff] [blame]98#if defined(__has_feature) &amp;&amp; __has_feature(address_sanitizer)
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]99 code that runs only under AddressSanitizer
100#else
101 code that does not run under AddressSanitizer
102#endif
103</pre>
104
105<h2 id="platforms">Supported Platforms</h2>
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]106AddressSanitizer is supported on
107<ul><li>Linux x86_64 (tested on Ubuntu 10.04).
108<li>MacOS 10.6 i386/x86_64.
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]109</ul>
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]110Support for Linux i386/ARM and MacOS 10.7 is in progress.
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]111
112<h2 id="limitations">Limitations</h2>
113<ul>
114 <li> AddressSanitizer uses more real memory than a native run.
115 How much -- depends on the allocations sizes. The smaller the
116 allocations you make the bigger the overhead.
117 <li> On 64-bit platforms AddressSanitizer maps (but not reserves)
118 16+ Terabytes of virtual address space.
119 This means that tools like <tt>ulimit</tt> may not work as usually expected.
120 <li> Static linking is not supported.
121</ul>
122
123
124<h2 id="status">Current Status</h2>
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]125AddressSanitizer is fully functional on supported platforms in LLVM head.
126However, the test suite is not fully integrated yet and we lack the testing
127process (buildbots).
128
129<h2 id="moreinfo">More Information</h2>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]130<a href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a>.
131
132
Kostya Serebryany7a31d7b2011-11-28 22:34:10 +0000[diff] [blame]133</div>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]134</body>
135</html>