Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / clang / b87699353a1a802f69e85ae2a125300de423ea09 / . / docs / AddressSanitizer.html
blob: c6a1850f462aefd449333b79c92680c1375e1cda [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>
25 <li> <a href="usage">Usage</a>
26 <ul><li> <a href="has_feature">__has_feature(address_sanitizer)</a></ul>
27 <li> <a href="platforms">Supported Platforms</a>
28 <li> <a href="limitations">Limitations</a>
29 <li> <a href="status">Current Status</a>
30</ul>
31
32<h2 id="intro">Introduction</h2>
33AddressSanitizer is a fast memory error detector.
34It consists of a compiler instrumentation module and a run-time library.
35The tool can detect the following types of bugs:
36<ul> <li> Out-of-bounds accesses to <ul><li>heap <li>stack <li>globals</ul>
37 <li> Use-after-free
38 <li> Use-after-return (to some extent)
39 <li> Double-free
40</ul>
41Typical slowdown introduced by AddressSanitizer is <b>2x</b>.
42
43<h2 id="intro">Usage</h2>
Kostya Serebryanyb8769932011-12-02 00:24:42 +0000[diff] [blame^]44In order to use AddressSanitizer simply compile and link your program with
45<tt>-faddress-sanitizer</tt> flag.
46To get a reasonable performance add <tt>-O1</tt> or higher.
47If a bug is detected, the program will print an error message and exit with a
48non-zero exit code.
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]49
50<h3 id="has_feature">__has_feature(address_sanitizer)</h3>
51In some cases one may need to execute different code depending on whether
52AddressSanitizer is enabled.
53<a href="LanguageExtensions.html#__has_feature_extension">__has_feature</a>
54can be used for this purpose.
55<pre>
56#if defined(__has_feature) && __has_feature(address_sanitizer)
57 code that runs only under AddressSanitizer
58#else
59 code that does not run under AddressSanitizer
60#endif
61</pre>
62
63<h2 id="platforms">Supported Platforms</h2>
64AddressSanitizer is supported on the following platforms:
65<ul> <li>Linux <ul> <li> i386 <li> x86_64 <li> ARM </ul>
66 <li>Darwin <ul> <li> i386 <li> x86_64 </ul>
67</ul>
68
69<h2 id="limitations">Limitations</h2>
70<ul>
71 <li> AddressSanitizer uses more real memory than a native run.
72 How much -- depends on the allocations sizes. The smaller the
73 allocations you make the bigger the overhead.
74 <li> On 64-bit platforms AddressSanitizer maps (but not reserves)
75 16+ Terabytes of virtual address space.
76 This means that tools like <tt>ulimit</tt> may not work as usually expected.
77 <li> Static linking is not supported.
78</ul>
79
80
81<h2 id="status">Current Status</h2>
82AddressSanitizer is work-in-progress and is not yet fully functional in the LLVM/Clang head.
83For the up-to-date usable version and full documentation refer to
84<a href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a>.
85
86
Kostya Serebryany7a31d7b2011-11-28 22:34:10 +0000[diff] [blame]87</div>
Kostya Serebryanyce98c9b2011-11-28 20:51:02 +0000[diff] [blame]88</body>
89</html>