docs/AddressSanitizer.html - platform/external/clang - Gitiles

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
           "http://www.w3.org/TR/html4/strict.dtd">
 <!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
 <html>
 <head>
   <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   <title>AddressSanitizer, a fast memory error detector</title>
   <link type="text/css" rel="stylesheet" href="../menu.css">
   <link type="text/css" rel="stylesheet" href="../content.css">
   <style type="text/css">
     td {
             vertical-align: top;
     }
   </style>
 </head>
 <body>

 <!--#include virtual="../menu.html.incl"-->

 <div id="content">

 <h1>AddressSanitizer</h1>
 <ul>
   <li> <a href="#intro">Introduction</a>
   <li> <a href="#howtobuild">How to Build</a>
   <li> <a href="#usage">Usage</a>
     <ul><li> <a href="#has_feature">__has_feature(address_sanitizer)</a></ul>
     <ul><li> <a href="#no_address_safety_analysis">
         __attribute__((no_address_safety_analysis))</a></ul>
   <li> <a href="#platforms">Supported Platforms</a>
   <li> <a href="#limitations">Limitations</a>
   <li> <a href="#status">Current Status</a>
   <li> <a href="#moreinfo">More Information</a>
 </ul>

 <h2 id="intro">Introduction</h2>
 AddressSanitizer is a fast memory error detector.
 It consists of a compiler instrumentation module and a run-time library.
 The tool can detect the following types of bugs:
 <ul> <li> Out-of-bounds accesses to  heap, stack and globals
   <li> Use-after-free
   <li> Use-after-return (to some extent)
   <li> Double-free, invalid free
 </ul>
 Typical slowdown introduced by AddressSanitizer is <b>2x</b>.

 <h2 id="howtobuild">How to build</h2>
 Follow the <a href="../get_started.html">clang build instructions</a>.
 CMake build is supported.<BR>

 <h2 id="usage">Usage</h2>
 Simply compile and link your program with <tt>-faddress-sanitizer</tt> flag. <BR>
 The AddressSanitizer run-time library should be linked to the final executable,
 so make sure to use <tt>clang</tt> (not <tt>ld</tt>) for the final link step.<BR>
 When linking shared libraries, the AddressSanitizer run-time is not linked,
 so <tt>-Wl,-z,defs</tt> may cause link errors (don't use it with AddressSanitizer). <BR>

 To get a reasonable performance add <tt>-O1</tt> or higher. <BR>
 To get nicer stack traces in error messages add
 <tt>-fno-omit-frame-pointer</tt>. <BR>
 To get perfect stack traces you may need to disable inlining (just use <tt>-O1</tt>) and tail call
 elimination (<tt>-fno-optimize-sibling-calls</tt>).

 <pre>
 % cat example_UseAfterFree.cc
 int main(int argc, char **argv) {
   int *array = new int[100];
   delete [] array;
   return array[argc];  // BOOM
 }
 </pre>

 <pre>
 # Compile and link
 % clang -O1 -g -faddress-sanitizer -fno-omit-frame-pointer example_UseAfterFree.cc
 </pre>
 OR
 <pre>
 # Compile
 % clang -O1 -g -faddress-sanitizer -fno-omit-frame-pointer -c example_UseAfterFree.cc
 # Link
 % clang -g -faddress-sanitizer example_UseAfterFree.o
 </pre>

 If a bug is detected, the program will print an error message to stderr and exit with a
 non-zero exit code.
 Currently, AddressSanitizer does not symbolize its output, so you may need to use a
 separate script to symbolize the result offline (this will be fixed in future).
 <pre>
 % ./a.out 2> log
 % projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log | c++filt
 ==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
 READ of size 4 at 0x7f7ddab8c084 thread T0
     #0 0x403c8c in main example_UseAfterFree.cc:4
     #1 0x7f7ddabcac4d in __libc_start_main ??:0
 0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210)
 freed by thread T0 here:
     #0 0x404704 in operator delete[](void*) ??:0
     #1 0x403c53 in main example_UseAfterFree.cc:4
     #2 0x7f7ddabcac4d in __libc_start_main ??:0
 previously allocated by thread T0 here:
     #0 0x404544 in operator new[](unsigned long) ??:0
     #1 0x403c43 in main example_UseAfterFree.cc:2
     #2 0x7f7ddabcac4d in __libc_start_main ??:0
 ==9442== ABORTING
 </pre>

 <h3 id="has_feature">__has_feature(address_sanitizer)</h3>
 In some cases one may need to execute different code depending on whether
 AddressSanitizer is enabled.
 <a href="LanguageExtensions.html#__has_feature_extension">__has_feature</a>
 can be used for this purpose.
 <pre>
 #if defined(__has_feature)
 # if __has_feature(address_sanitizer)
   code that builds only under AddressSanitizer
 # endif
 #endif
 </pre>

 <h3 id="no_address_safety_analysis">__attribute__((no_address_safety_analysis))</h3>
 Some code should not be instrumented by AddressSanitizer.
 One may use the function attribute
 <a href="LanguageExtensions.html#address_sanitizer">
   <tt>no_address_safety_analysis</tt></a>
 to disable instrumentation of a particular function.
 This attribute may not be supported by other compilers, so we suggest to
 use it together with <tt>__has_feature(address_sanitizer)</tt>.
 Note: currently, this attribute will be lost if the function is inlined.

 <h2 id="platforms">Supported Platforms</h2>
 AddressSanitizer is supported on
 <ul><li>Linux i386/x86_64 (tested on Ubuntu 10.04 and 12.04).
 <li>MacOS 10.6, 10.7 and 10.8 (i386/x86_64).
 </ul>
 Support for Linux ARM (and Android ARM) is in progress
 (it may work, but is not guaranteed too).


 <h2 id="limitations">Limitations</h2>
 <ul>
 <li> AddressSanitizer uses more real memory than a native run.
 Exact overhead depends on the allocations sizes. The smaller the
 allocations you make the bigger the overhead is.
 <li> AddressSanitizer uses more stack memory. We have seen up to 3x increase.
 <li> On 64-bit platforms AddressSanitizer maps (but not reserves)
 16+ Terabytes of virtual address space.
 This means that tools like <tt>ulimit</tt> may not work as usually expected.
 <li> Static linking is not supported.
 </ul>


 <h2 id="status">Current Status</h2>
 AddressSanitizer is fully functional on supported platforms starting from LLVM 3.1.
 The test suite is integrated into CMake build and can be run with
 <tt>make check-asan</tt> command.

 <h2 id="moreinfo">More Information</h2>
 <a href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a>.


 </div>
 </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
	"http://www.w3.org/TR/html4/strict.dtd">
	<!-- Material used from: HTML 4.01 specs: http://www.w3.org/TR/html401/ -->
	<html>
	<head>
	<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
	<title>AddressSanitizer, a fast memory error detector</title>
	<link type="text/css" rel="stylesheet" href="../menu.css">
	<link type="text/css" rel="stylesheet" href="../content.css">
	<style type="text/css">
	td {
	vertical-align: top;
	}
	</style>
	</head>
	<body>

	<!--#include virtual="../menu.html.incl"-->

	<div id="content">

	<h1>AddressSanitizer</h1>
	<ul>
	<li> <a href="#intro">Introduction</a>
	<li> <a href="#howtobuild">How to Build</a>
	<li> <a href="#usage">Usage</a>
	<ul><li> <a href="#has_feature">__has_feature(address_sanitizer)</a></ul>
	<ul><li> <a href="#no_address_safety_analysis">
	__attribute__((no_address_safety_analysis))</a></ul>
	<li> <a href="#platforms">Supported Platforms</a>
	<li> <a href="#limitations">Limitations</a>
	<li> <a href="#status">Current Status</a>
	<li> <a href="#moreinfo">More Information</a>
	</ul>

	<h2 id="intro">Introduction</h2>
	AddressSanitizer is a fast memory error detector.
	It consists of a compiler instrumentation module and a run-time library.
	The tool can detect the following types of bugs:
	<ul> <li> Out-of-bounds accesses to heap, stack and globals
	<li> Use-after-free
	<li> Use-after-return (to some extent)
	<li> Double-free, invalid free
	</ul>
	Typical slowdown introduced by AddressSanitizer is <b>2x</b>.

	<h2 id="howtobuild">How to build</h2>
	Follow the <a href="../get_started.html">clang build instructions</a>.
	CMake build is supported.<BR>

	<h2 id="usage">Usage</h2>
	Simply compile and link your program with <tt>-faddress-sanitizer</tt> flag. <BR>
	The AddressSanitizer run-time library should be linked to the final executable,
	so make sure to use <tt>clang</tt> (not <tt>ld</tt>) for the final link step.<BR>
	When linking shared libraries, the AddressSanitizer run-time is not linked,
	so <tt>-Wl,-z,defs</tt> may cause link errors (don't use it with AddressSanitizer). <BR>

	To get a reasonable performance add <tt>-O1</tt> or higher. <BR>
	To get nicer stack traces in error messages add
	<tt>-fno-omit-frame-pointer</tt>. <BR>
	To get perfect stack traces you may need to disable inlining (just use <tt>-O1</tt>) and tail call
	elimination (<tt>-fno-optimize-sibling-calls</tt>).

	<pre>
	% cat example_UseAfterFree.cc
	int main(int argc, char **argv) {
	int *array = new int[100];
	delete [] array;
	return array[argc]; // BOOM
	}
	</pre>

	<pre>
	# Compile and link
	% clang -O1 -g -faddress-sanitizer -fno-omit-frame-pointer example_UseAfterFree.cc
	</pre>
	OR
	<pre>
	# Compile
	% clang -O1 -g -faddress-sanitizer -fno-omit-frame-pointer -c example_UseAfterFree.cc
	# Link
	% clang -g -faddress-sanitizer example_UseAfterFree.o
	</pre>

	If a bug is detected, the program will print an error message to stderr and exit with a
	non-zero exit code.
	Currently, AddressSanitizer does not symbolize its output, so you may need to use a
	separate script to symbolize the result offline (this will be fixed in future).
	<pre>
	% ./a.out 2> log
	% projects/compiler-rt/lib/asan/scripts/asan_symbolize.py / < log \| c++filt
	==9442== ERROR: AddressSanitizer heap-use-after-free on address 0x7f7ddab8c084 at pc 0x403c8c bp 0x7fff87fb82d0 sp 0x7fff87fb82c8
	READ of size 4 at 0x7f7ddab8c084 thread T0
	#0 0x403c8c in main example_UseAfterFree.cc:4
	#1 0x7f7ddabcac4d in __libc_start_main ??:0
	0x7f7ddab8c084 is located 4 bytes inside of 400-byte region [0x7f7ddab8c080,0x7f7ddab8c210)
	freed by thread T0 here:
	#0 0x404704 in operator delete[](void*) ??:0
	#1 0x403c53 in main example_UseAfterFree.cc:4
	#2 0x7f7ddabcac4d in __libc_start_main ??:0
	previously allocated by thread T0 here:
	#0 0x404544 in operator new[](unsigned long) ??:0
	#1 0x403c43 in main example_UseAfterFree.cc:2
	#2 0x7f7ddabcac4d in __libc_start_main ??:0
	==9442== ABORTING
	</pre>

	<h3 id="has_feature">__has_feature(address_sanitizer)</h3>
	In some cases one may need to execute different code depending on whether
	AddressSanitizer is enabled.
	<a href="LanguageExtensions.html#__has_feature_extension">__has_feature</a>
	can be used for this purpose.
	<pre>
	#if defined(__has_feature)
	# if __has_feature(address_sanitizer)
	code that builds only under AddressSanitizer
	# endif
	#endif
	</pre>

	<h3 id="no_address_safety_analysis">__attribute__((no_address_safety_analysis))</h3>
	Some code should not be instrumented by AddressSanitizer.
	One may use the function attribute
	<a href="LanguageExtensions.html#address_sanitizer">
	<tt>no_address_safety_analysis</tt></a>
	to disable instrumentation of a particular function.
	This attribute may not be supported by other compilers, so we suggest to
	use it together with <tt>__has_feature(address_sanitizer)</tt>.
	Note: currently, this attribute will be lost if the function is inlined.

	<h2 id="platforms">Supported Platforms</h2>
	AddressSanitizer is supported on
	<ul><li>Linux i386/x86_64 (tested on Ubuntu 10.04 and 12.04).
	<li>MacOS 10.6, 10.7 and 10.8 (i386/x86_64).
	</ul>
	Support for Linux ARM (and Android ARM) is in progress
	(it may work, but is not guaranteed too).


	<h2 id="limitations">Limitations</h2>
	<ul>
	<li> AddressSanitizer uses more real memory than a native run.
	Exact overhead depends on the allocations sizes. The smaller the
	allocations you make the bigger the overhead is.
	<li> AddressSanitizer uses more stack memory. We have seen up to 3x increase.
	<li> On 64-bit platforms AddressSanitizer maps (but not reserves)
	16+ Terabytes of virtual address space.
	This means that tools like <tt>ulimit</tt> may not work as usually expected.
	<li> Static linking is not supported.
	</ul>


	<h2 id="status">Current Status</h2>
	AddressSanitizer is fully functional on supported platforms starting from LLVM 3.1.
	The test suite is integrated into CMake build and can be run with
	<tt>make check-asan</tt> command.

	<h2 id="moreinfo">More Information</h2>
	<a href="http://code.google.com/p/address-sanitizer/">http://code.google.com/p/address-sanitizer</a>.


	</div>
	</body>
	</html>