Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / clang / 4a131e1c6360419ceabdae80175ccb43d0ca31ee / . / docs / AddressSanitizer.html
blob: d60cdd9d353c8b3f3dcd6eb6d12d1f08267d9302 [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>
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]52Simply compile and link your program with <tt>-faddress-sanitizer</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
Kostya Serebryanye683fd92012-01-06 17:35:27 +0000[diff] [blame]75% clang -O1 -g -faddress-sanitizer -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
80% clang -O1 -g -faddress-sanitizer -fno-omit-frame-pointer -c example_UseAfterFree.cc
81# Link
82% clang -g -faddress-sanitizer example_UseAfterFree.o
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
108<h3 id="has_feature">__has_feature(address_sanitizer)</h3>
109In some cases one may need to execute different code depending on whether
110AddressSanitizer is enabled.
111<a href="LanguageExtensions.html#__has_feature_extension">__has_feature</a>
112can be used for this purpose.
113<pre>
Kostya Serebryanyf45f2342012-07-02 11:00:33 +0000[diff] [blame]114#if defined(__has_feature)
115# if __has_feature(address_sanitizer)
116 code that builds only under AddressSanitizer
117# endif
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]118#endif
119</pre>
120
Kostya Serebryanycef57e52012-04-23 09:05:50 +0000[diff] [blame]121<h3 id="no_address_safety_analysis">__attribute__((no_address_safety_analysis))</h3>
Alexey Samsonovadea5172012-10-24 13:21:51 +0000[diff] [blame]122Some code should not be instrumented by AddressSanitizer.
123One may use the function attribute
Kostya Serebryanycef57e52012-04-23 09:05:50 +0000[diff] [blame]124<a href="LanguageExtensions.html#address_sanitizer">
125 <tt>no_address_safety_analysis</tt></a>
126to disable instrumentation of a particular function.
Kostya Serebryanyf45f2342012-07-02 11:00:33 +0000[diff] [blame]127This attribute may not be supported by other compilers, so we suggest to
128use it together with <tt>__has_feature(address_sanitizer)</tt>.
Kostya Serebryanycef57e52012-04-23 09:05:50 +0000[diff] [blame]129Note: currently, this attribute will be lost if the function is inlined.
130
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]131<h2 id="platforms">Supported Platforms</h2>
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]132AddressSanitizer is supported on
Kostya Serebryany460e7a22012-10-19 07:00:46 +0000[diff] [blame]133<ul><li>Linux i386/x86_64 (tested on Ubuntu 10.04 and 12.04).
Alexey Samsonova8ee4412012-09-06 09:49:03 +0000[diff] [blame]134<li>MacOS 10.6, 10.7 and 10.8 (i386/x86_64).
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]135</ul>
Kostya Serebryany460e7a22012-10-19 07:00:46 +0000[diff] [blame]136Support for Linux ARM (and Android ARM) is in progress
Kostya Serebryanyabc31ca2012-03-15 16:20:29 +0000[diff] [blame]137(it may work, but is not guaranteed too).
138
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]139
140<h2 id="limitations">Limitations</h2>
141<ul>
Kostya Serebryanycef57e52012-04-23 09:05:50 +0000[diff] [blame]142<li> AddressSanitizer uses more real memory than a native run.
Alexey Samsonovadea5172012-10-24 13:21:51 +0000[diff] [blame]143Exact overhead depends on the allocations sizes. The smaller the
144allocations you make the bigger the overhead is.
Kostya Serebryanycef57e52012-04-23 09:05:50 +0000[diff] [blame]145<li> AddressSanitizer uses more stack memory. We have seen up to 3x increase.
146<li> On 64-bit platforms AddressSanitizer maps (but not reserves)
14716+ Terabytes of virtual address space.
148This means that tools like <tt>ulimit</tt> may not work as usually expected.
149<li> Static linking is not supported.
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]150</ul>
151
152
153<h2 id="status">Current Status</h2>
Kostya Serebryany219cd6c2012-04-23 10:15:18 +0000[diff] [blame]154AddressSanitizer is fully functional on supported platforms starting from LLVM 3.1.
Alexey Samsonovadea5172012-10-24 13:21:51 +0000[diff] [blame]155The test suite is integrated into CMake build and can be run with
156<tt>make check-asan</tt> command.
Kostya Serebryany2e173222011-12-12 23:22:31 +0000[diff] [blame]157
158<h2 id="moreinfo">More Information</h2>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]159<a href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a>.
160
161
Kostya Serebryany7a31d7b2011-11-28 22:34:10 +0000[diff] [blame]162</div>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]163</body>
164</html>