1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 4<title>4.�Memcheck: a memory error detector</title> 5<link rel="stylesheet" type="text/css" href="vg_basic.css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="index.html" title="Valgrind Documentation"> 8<link rel="up" href="manual.html" title="Valgrind User Manual"> 9<link rel="prev" href="manual-core-adv.html" title="3.�Using and understanding the Valgrind core: Advanced Topics"> 10<link rel="next" href="cg-manual.html" title="5.�Cachegrind: a cache and branch-prediction profiler"> 11</head> 12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13<div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr> 14<td width="22px" align="center" valign="middle"><a accesskey="p" href="manual-core-adv.html"><img src="images/prev.png" width="18" height="21" border="0" alt="Prev"></a></td> 15<td width="25px" align="center" valign="middle"><a accesskey="u" href="manual.html"><img src="images/up.png" width="21" height="18" border="0" alt="Up"></a></td> 16<td width="31px" align="center" valign="middle"><a accesskey="h" href="index.html"><img src="images/home.png" width="27" height="20" border="0" alt="Up"></a></td> 17<th align="center" valign="middle">Valgrind User Manual</th> 18<td width="22px" align="center" valign="middle"><a accesskey="n" href="cg-manual.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td> 19</tr></table></div> 20<div class="chapter"> 21<div class="titlepage"><div><div><h1 class="title"> 22<a name="mc-manual"></a>4.�Memcheck: a memory error detector</h1></div></div></div> 23<div class="toc"> 24<p><b>Table of Contents</b></p> 25<dl class="toc"> 26<dt><span class="sect1"><a href="mc-manual.html#mc-manual.overview">4.1. Overview</a></span></dt> 27<dt><span class="sect1"><a href="mc-manual.html#mc-manual.errormsgs">4.2. Explanation of error messages from Memcheck</a></span></dt> 28<dd><dl> 29<dt><span class="sect2"><a href="mc-manual.html#mc-manual.badrw">4.2.1. Illegal read / Illegal write errors</a></span></dt> 30<dt><span class="sect2"><a href="mc-manual.html#mc-manual.uninitvals">4.2.2. Use of uninitialised values</a></span></dt> 31<dt><span class="sect2"><a href="mc-manual.html#mc-manual.bad-syscall-args">4.2.3. Use of uninitialised or unaddressable values in system 32 calls</a></span></dt> 33<dt><span class="sect2"><a href="mc-manual.html#mc-manual.badfrees">4.2.4. Illegal frees</a></span></dt> 34<dt><span class="sect2"><a href="mc-manual.html#mc-manual.rudefn">4.2.5. When a heap block is freed with an inappropriate deallocation 35function</a></span></dt> 36<dt><span class="sect2"><a href="mc-manual.html#mc-manual.overlap">4.2.6. Overlapping source and destination blocks</a></span></dt> 37<dt><span class="sect2"><a href="mc-manual.html#mc-manual.fishyvalue">4.2.7. Fishy argument values</a></span></dt> 38<dt><span class="sect2"><a href="mc-manual.html#mc-manual.leaks">4.2.8. Memory leak detection</a></span></dt> 39</dl></dd> 40<dt><span class="sect1"><a href="mc-manual.html#mc-manual.options">4.3. Memcheck Command-Line Options</a></span></dt> 41<dt><span class="sect1"><a href="mc-manual.html#mc-manual.suppfiles">4.4. Writing suppression files</a></span></dt> 42<dt><span class="sect1"><a href="mc-manual.html#mc-manual.machine">4.5. Details of Memcheck's checking machinery</a></span></dt> 43<dd><dl> 44<dt><span class="sect2"><a href="mc-manual.html#mc-manual.value">4.5.1. Valid-value (V) bits</a></span></dt> 45<dt><span class="sect2"><a href="mc-manual.html#mc-manual.vaddress">4.5.2. Valid-address (A) bits</a></span></dt> 46<dt><span class="sect2"><a href="mc-manual.html#mc-manual.together">4.5.3. Putting it all together</a></span></dt> 47</dl></dd> 48<dt><span class="sect1"><a href="mc-manual.html#mc-manual.monitor-commands">4.6. Memcheck Monitor Commands</a></span></dt> 49<dt><span class="sect1"><a href="mc-manual.html#mc-manual.clientreqs">4.7. Client Requests</a></span></dt> 50<dt><span class="sect1"><a href="mc-manual.html#mc-manual.mempools">4.8. Memory Pools: describing and working with custom allocators</a></span></dt> 51<dt><span class="sect1"><a href="mc-manual.html#mc-manual.mpiwrap">4.9. Debugging MPI Parallel Programs with Valgrind</a></span></dt> 52<dd><dl> 53<dt><span class="sect2"><a href="mc-manual.html#mc-manual.mpiwrap.build">4.9.1. Building and installing the wrappers</a></span></dt> 54<dt><span class="sect2"><a href="mc-manual.html#mc-manual.mpiwrap.gettingstarted">4.9.2. Getting started</a></span></dt> 55<dt><span class="sect2"><a href="mc-manual.html#mc-manual.mpiwrap.controlling">4.9.3. Controlling the wrapper library</a></span></dt> 56<dt><span class="sect2"><a href="mc-manual.html#mc-manual.mpiwrap.limitations.functions">4.9.4. Functions</a></span></dt> 57<dt><span class="sect2"><a href="mc-manual.html#mc-manual.mpiwrap.limitations.types">4.9.5. Types</a></span></dt> 58<dt><span class="sect2"><a href="mc-manual.html#mc-manual.mpiwrap.writingwrappers">4.9.6. Writing new wrappers</a></span></dt> 59<dt><span class="sect2"><a href="mc-manual.html#mc-manual.mpiwrap.whattoexpect">4.9.7. What to expect when using the wrappers</a></span></dt> 60</dl></dd> 61</dl> 62</div> 63<p>To use this tool, you may specify <code class="option">--tool=memcheck</code> 64on the Valgrind command line. You don't have to, though, since Memcheck 65is the default tool.</p> 66<div class="sect1"> 67<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 68<a name="mc-manual.overview"></a>4.1.�Overview</h2></div></div></div> 69<p>Memcheck is a memory error detector. It can detect the following 70problems that are common in C and C++ programs.</p> 71<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 72<li class="listitem"><p>Accessing memory you shouldn't, e.g. overrunning and underrunning 73 heap blocks, overrunning the top of the stack, and accessing memory after 74 it has been freed.</p></li> 75<li class="listitem"><p>Using undefined values, i.e. values that have not been initialised, 76 or that have been derived from other undefined values.</p></li> 77<li class="listitem"><p>Incorrect freeing of heap memory, such as double-freeing heap 78 blocks, or mismatched use of 79 <code class="function">malloc</code>/<code class="computeroutput">new</code>/<code class="computeroutput">new[]</code> 80 versus 81 <code class="function">free</code>/<code class="computeroutput">delete</code>/<code class="computeroutput">delete[]</code></p></li> 82<li class="listitem"><p>Overlapping <code class="computeroutput">src</code> and 83 <code class="computeroutput">dst</code> pointers in 84 <code class="computeroutput">memcpy</code> and related 85 functions.</p></li> 86<li class="listitem"><p>Passing a fishy (presumably negative) value to the 87 <code class="computeroutput">size</code> parameter of a memory 88 allocation function.</p></li> 89<li class="listitem"><p>Memory leaks.</p></li> 90</ul></div> 91<p>Problems like these can be difficult to find by other means, 92often remaining undetected for long periods, then causing occasional, 93 difficult-to-diagnose crashes.</p> 94<p>Memcheck also provides <a class="xref" href="manual-core.html#manual-core.xtree" title="2.9.�Execution Trees">Execution Trees</a> memory 95 profiling using the command line 96 option <code class="computeroutput">--xtree-memory</code> and the monitor command 97 <code class="computeroutput">xtmemory</code>.</p> 98</div> 99<div class="sect1"> 100<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 101<a name="mc-manual.errormsgs"></a>4.2.�Explanation of error messages from Memcheck</h2></div></div></div> 102<p>Memcheck issues a range of error messages. This section presents a 103quick summary of what error messages mean. The precise behaviour of the 104error-checking machinery is described in <a class="xref" href="mc-manual.html#mc-manual.machine" title="4.5.�Details of Memcheck's checking machinery">Details of Memcheck's checking machinery</a>.</p> 105<div class="sect2"> 106<div class="titlepage"><div><div><h3 class="title"> 107<a name="mc-manual.badrw"></a>4.2.1.�Illegal read / Illegal write errors</h3></div></div></div> 108<p>For example:</p> 109<pre class="programlisting"> 110Invalid read of size 4 111 at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9) 112 by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9) 113 by 0x40B07FF4: read_png_image(QImageIO *) (kernel/qpngio.cpp:326) 114 by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621) 115 Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd 116</pre> 117<p>This happens when your program reads or writes memory at a place 118which Memcheck reckons it shouldn't. In this example, the program did a 1194-byte read at address 0xBFFFF0E0, somewhere within the system-supplied 120library libpng.so.2.1.0.9, which was called from somewhere else in the 121same library, called from line 326 of <code class="filename">qpngio.cpp</code>, 122and so on.</p> 123<p>Memcheck tries to establish what the illegal address might relate 124to, since that's often useful. So, if it points into a block of memory 125which has already been freed, you'll be informed of this, and also where 126the block was freed. Likewise, if it should turn out to be just off 127the end of a heap block, a common result of off-by-one-errors in 128array subscripting, you'll be informed of this fact, and also where the 129block was allocated. If you use the <code class="option"><a class="xref" href="manual-core.html#opt.read-var-info">--read-var-info</a></code> option Memcheck will run more slowly 130but may give a more detailed description of any illegal address.</p> 131<p>In this example, Memcheck can't identify the address. Actually 132the address is on the stack, but, for some reason, this is not a valid 133stack address -- it is below the stack pointer and that isn't allowed. 134In this particular case it's probably caused by GCC generating invalid 135code, a known bug in some ancient versions of GCC.</p> 136<p>Note that Memcheck only tells you that your program is about to 137access memory at an illegal address. It can't stop the access from 138happening. So, if your program makes an access which normally would 139result in a segmentation fault, you program will still suffer the same 140fate -- but you will get a message from Memcheck immediately prior to 141this. In this particular example, reading junk on the stack is 142non-fatal, and the program stays alive.</p> 143</div> 144<div class="sect2"> 145<div class="titlepage"><div><div><h3 class="title"> 146<a name="mc-manual.uninitvals"></a>4.2.2.�Use of uninitialised values</h3></div></div></div> 147<p>For example:</p> 148<pre class="programlisting"> 149Conditional jump or move depends on uninitialised value(s) 150 at 0x402DFA94: _IO_vfprintf (_itoa.h:49) 151 by 0x402E8476: _IO_printf (printf.c:36) 152 by 0x8048472: main (tests/manuel1.c:8) 153</pre> 154<p>An uninitialised-value use error is reported when your program 155uses a value which hasn't been initialised -- in other words, is 156undefined. Here, the undefined value is used somewhere inside the 157<code class="function">printf</code> machinery of the C library. This error was 158reported when running the following small program:</p> 159<pre class="programlisting"> 160int main() 161{ 162 int x; 163 printf ("x = %d\n", x); 164}</pre> 165<p>It is important to understand that your program can copy around 166junk (uninitialised) data as much as it likes. Memcheck observes this 167and keeps track of the data, but does not complain. A complaint is 168issued only when your program attempts to make use of uninitialised 169data in a way that might affect your program's externally-visible behaviour. 170In this example, <code class="varname">x</code> is uninitialised. Memcheck observes 171the value being passed to <code class="function">_IO_printf</code> and thence to 172<code class="function">_IO_vfprintf</code>, but makes no comment. However, 173<code class="function">_IO_vfprintf</code> has to examine the value of 174<code class="varname">x</code> so it can turn it into the corresponding ASCII string, 175and it is at this point that Memcheck complains.</p> 176<p>Sources of uninitialised data tend to be:</p> 177<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 178<li class="listitem"><p>Local variables in procedures which have not been initialised, 179 as in the example above.</p></li> 180<li class="listitem"><p>The contents of heap blocks (allocated with 181 <code class="function">malloc</code>, <code class="function">new</code>, or a similar 182 function) before you (or a constructor) write something there. 183 </p></li> 184</ul></div> 185<p>To see information on the sources of uninitialised data in your 186program, use the <code class="option">--track-origins=yes</code> option. This 187makes Memcheck run more slowly, but can make it much easier to track down 188the root causes of uninitialised value errors.</p> 189</div> 190<div class="sect2"> 191<div class="titlepage"><div><div><h3 class="title"> 192<a name="mc-manual.bad-syscall-args"></a>4.2.3.�Use of uninitialised or unaddressable values in system 193 calls</h3></div></div></div> 194<p>Memcheck checks all parameters to system calls: 195</p> 196<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 197<li class="listitem"><p>It checks all the direct parameters themselves, whether they are 198 initialised.</p></li> 199<li class="listitem"><p>Also, if a system call needs to read from a buffer provided by 200 your program, Memcheck checks that the entire buffer is addressable 201 and its contents are initialised.</p></li> 202<li class="listitem"><p>Also, if the system call needs to write to a user-supplied 203 buffer, Memcheck checks that the buffer is addressable.</p></li> 204</ul></div> 205<p> 206</p> 207<p>After the system call, Memcheck updates its tracked information to 208precisely reflect any changes in memory state caused by the system 209call.</p> 210<p>Here's an example of two system calls with invalid parameters:</p> 211<pre class="programlisting"> 212 #include <stdlib.h> 213 #include <unistd.h> 214 int main( void ) 215 { 216 char* arr = malloc(10); 217 int* arr2 = malloc(sizeof(int)); 218 write( 1 /* stdout */, arr, 10 ); 219 exit(arr2[0]); 220 } 221</pre> 222<p>You get these complaints ...</p> 223<pre class="programlisting"> 224 Syscall param write(buf) points to uninitialised byte(s) 225 at 0x25A48723: __write_nocancel (in /lib/tls/libc-2.3.3.so) 226 by 0x259AFAD3: __libc_start_main (in /lib/tls/libc-2.3.3.so) 227 by 0x8048348: (within /auto/homes/njn25/grind/head4/a.out) 228 Address 0x25AB8028 is 0 bytes inside a block of size 10 alloc'd 229 at 0x259852B0: malloc (vg_replace_malloc.c:130) 230 by 0x80483F1: main (a.c:5) 231 232 Syscall param exit(error_code) contains uninitialised byte(s) 233 at 0x25A21B44: __GI__exit (in /lib/tls/libc-2.3.3.so) 234 by 0x8048426: main (a.c:8) 235</pre> 236<p>... because the program has (a) written uninitialised junk 237from the heap block to the standard output, and (b) passed an 238uninitialised value to <code class="function">exit</code>. Note that the first 239error refers to the memory pointed to by 240<code class="computeroutput">buf</code> (not 241<code class="computeroutput">buf</code> itself), but the second error 242refers directly to <code class="computeroutput">exit</code>'s argument 243<code class="computeroutput">arr2[0]</code>.</p> 244</div> 245<div class="sect2"> 246<div class="titlepage"><div><div><h3 class="title"> 247<a name="mc-manual.badfrees"></a>4.2.4.�Illegal frees</h3></div></div></div> 248<p>For example:</p> 249<pre class="programlisting"> 250Invalid free() 251 at 0x4004FFDF: free (vg_clientmalloc.c:577) 252 by 0x80484C7: main (tests/doublefree.c:10) 253 Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd 254 at 0x4004FFDF: free (vg_clientmalloc.c:577) 255 by 0x80484C7: main (tests/doublefree.c:10) 256</pre> 257<p>Memcheck keeps track of the blocks allocated by your program 258with <code class="function">malloc</code>/<code class="computeroutput">new</code>, 259so it can know exactly whether or not the argument to 260<code class="function">free</code>/<code class="computeroutput">delete</code> is 261legitimate or not. Here, this test program has freed the same block 262twice. As with the illegal read/write errors, Memcheck attempts to 263make sense of the address freed. If, as here, the address is one 264which has previously been freed, you wil be told that -- making 265duplicate frees of the same block easy to spot. You will also get this 266message if you try to free a pointer that doesn't point to the start of a 267heap block.</p> 268</div> 269<div class="sect2"> 270<div class="titlepage"><div><div><h3 class="title"> 271<a name="mc-manual.rudefn"></a>4.2.5.�When a heap block is freed with an inappropriate deallocation 272function</h3></div></div></div> 273<p>In the following example, a block allocated with 274<code class="function">new[]</code> has wrongly been deallocated with 275<code class="function">free</code>:</p> 276<pre class="programlisting"> 277Mismatched free() / delete / delete [] 278 at 0x40043249: free (vg_clientfuncs.c:171) 279 by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149) 280 by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60) 281 by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44) 282 Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd 283 at 0x4004318C: operator new[](unsigned int) (vg_clientfuncs.c:152) 284 by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314) 285 by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416) 286 by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272) 287</pre> 288<p>In <code class="literal">C++</code> it's important to deallocate memory in a 289way compatible with how it was allocated. The deal is:</p> 290<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 291<li class="listitem"><p>If allocated with 292 <code class="function">malloc</code>, 293 <code class="function">calloc</code>, 294 <code class="function">realloc</code>, 295 <code class="function">valloc</code> or 296 <code class="function">memalign</code>, you must 297 deallocate with <code class="function">free</code>.</p></li> 298<li class="listitem"><p>If allocated with <code class="function">new</code>, you must deallocate 299 with <code class="function">delete</code>.</p></li> 300<li class="listitem"><p>If allocated with <code class="function">new[]</code>, you must 301 deallocate with <code class="function">delete[]</code>.</p></li> 302</ul></div> 303<p>The worst thing is that on Linux apparently it doesn't matter if 304you do mix these up, but the same program may then crash on a 305different platform, Solaris for example. So it's best to fix it 306properly. According to the KDE folks "it's amazing how many C++ 307programmers don't know this".</p> 308<p>The reason behind the requirement is as follows. In some C++ 309implementations, <code class="function">delete[]</code> must be used for 310objects allocated by <code class="function">new[]</code> because the compiler 311stores the size of the array and the pointer-to-member to the 312destructor of the array's content just before the pointer actually 313returned. <code class="function">delete</code> doesn't account for this and will get 314confused, possibly corrupting the heap.</p> 315</div> 316<div class="sect2"> 317<div class="titlepage"><div><div><h3 class="title"> 318<a name="mc-manual.overlap"></a>4.2.6.�Overlapping source and destination blocks</h3></div></div></div> 319<p>The following C library functions copy some data from one 320memory block to another (or something similar): 321<code class="function">memcpy</code>, 322<code class="function">strcpy</code>, 323<code class="function">strncpy</code>, 324<code class="function">strcat</code>, 325<code class="function">strncat</code>. 326The blocks pointed to by their <code class="computeroutput">src</code> and 327<code class="computeroutput">dst</code> pointers aren't allowed to overlap. 328The POSIX standards have wording along the lines "If copying takes place 329between objects that overlap, the behavior is undefined." Therefore, 330Memcheck checks for this. 331</p> 332<p>For example:</p> 333<pre class="programlisting"> 334==27492== Source and destination overlap in memcpy(0xbffff294, 0xbffff280, 21) 335==27492== at 0x40026CDC: memcpy (mc_replace_strmem.c:71) 336==27492== by 0x804865A: main (overlap.c:40) 337</pre> 338<p>You don't want the two blocks to overlap because one of them could 339get partially overwritten by the copying.</p> 340<p>You might think that Memcheck is being overly pedantic reporting 341this in the case where <code class="computeroutput">dst</code> is less than 342<code class="computeroutput">src</code>. For example, the obvious way to 343implement <code class="function">memcpy</code> is by copying from the first 344byte to the last. However, the optimisation guides of some 345architectures recommend copying from the last byte down to the first. 346Also, some implementations of <code class="function">memcpy</code> zero 347<code class="computeroutput">dst</code> before copying, because zeroing the 348destination's cache line(s) can improve performance.</p> 349<p>The moral of the story is: if you want to write truly portable 350code, don't make any assumptions about the language 351implementation.</p> 352</div> 353<div class="sect2"> 354<div class="titlepage"><div><div><h3 class="title"> 355<a name="mc-manual.fishyvalue"></a>4.2.7.�Fishy argument values</h3></div></div></div> 356<p>All memory allocation functions take an argument specifying the 357size of the memory block that should be allocated. Clearly, the requested 358size should be a non-negative value and is typically not excessively large. 359For instance, it is extremely unlikly that the size of an allocation 360request exceeds 2**63 bytes on a 64-bit machine. It is much more likely that 361such a value is the result of an erroneous size calculation and is in effect 362a negative value (that just happens to appear excessively large because 363the bit pattern is interpreted as an unsigned integer). 364Such a value is called a "fishy value". 365 366The <code class="varname">size</code> argument of the following allocation functions 367is checked for being fishy: 368<code class="function">malloc</code>, 369<code class="function">calloc</code>, 370<code class="function">realloc</code>, 371<code class="function">memalign</code>, 372<code class="function">new</code>, 373<code class="function">new []</code>. 374<code class="function">__builtin_new</code>, 375<code class="function">__builtin_vec_new</code>, 376For <code class="function">calloc</code> both arguments are being checked. 377</p> 378<p>For example:</p> 379<pre class="programlisting"> 380==32233== Argument 'size' of function malloc has a fishy (possibly negative) value: -3 381==32233== at 0x4C2CFA7: malloc (vg_replace_malloc.c:298) 382==32233== by 0x400555: foo (fishy.c:15) 383==32233== by 0x400583: main (fishy.c:23) 384</pre> 385<p>In earlier Valgrind versions those values were being referred to 386as "silly arguments" and no back-trace was included. 387</p> 388</div> 389<div class="sect2"> 390<div class="titlepage"><div><div><h3 class="title"> 391<a name="mc-manual.leaks"></a>4.2.8.�Memory leak detection</h3></div></div></div> 392<p>Memcheck keeps track of all heap blocks issued in response to 393calls to 394<code class="function">malloc</code>/<code class="function">new</code> et al. 395So when the program exits, it knows which blocks have not been freed. 396</p> 397<p>If <code class="option">--leak-check</code> is set appropriately, for each 398remaining block, Memcheck determines if the block is reachable from pointers 399within the root-set. The root-set consists of (a) general purpose registers 400of all threads, and (b) initialised, aligned, pointer-sized data words in 401accessible client memory, including stacks.</p> 402<p>There are two ways a block can be reached. The first is with a 403"start-pointer", i.e. a pointer to the start of the block. The second is with 404an "interior-pointer", i.e. a pointer to the middle of the block. There are 405several ways we know of that an interior-pointer can occur:</p> 406<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 407<li class="listitem"><p>The pointer might have originally been a start-pointer and have been 408 moved along deliberately (or not deliberately) by the program. In 409 particular, this can happen if your program uses tagged pointers, i.e. 410 if it uses the bottom one, two or three bits of a pointer, which are 411 normally always zero due to alignment, in order to store extra 412 information.</p></li> 413<li class="listitem"><p>It might be a random junk value in memory, entirely unrelated, just 414 a coincidence.</p></li> 415<li class="listitem"><p>It might be a pointer to the inner char array of a C++ 416 <code class="computeroutput">std::string</code>. For example, some 417 compilers add 3 words at the beginning of the std::string to 418 store the length, the capacity and a reference count before the 419 memory containing the array of characters. They return a pointer 420 just after these 3 words, pointing at the char array.</p></li> 421<li class="listitem"><p>Some code might allocate a block of memory, and use the first 8 422 bytes to store (block size - 8) as a 64bit number. 423 <code class="computeroutput">sqlite3MemMalloc</code> does this.</p></li> 424<li class="listitem"><p>It might be a pointer to an array of C++ objects (which possess 425 destructors) allocated with <code class="computeroutput">new[]</code>. In 426 this case, some compilers store a "magic cookie" containing the array 427 length at the start of the allocated block, and return a pointer to just 428 past that magic cookie, i.e. an interior-pointer. 429 See <a class="ulink" href="http://theory.uwinnipeg.ca/gnu/gcc/gxxint_14.html" target="_top">this 430 page</a> for more information.</p></li> 431<li class="listitem"><p>It might be a pointer to an inner part of a C++ object using 432 multiple inheritance. </p></li> 433</ul></div> 434<p>You can optionally activate heuristics to use during the leak 435search to detect the interior pointers corresponding to 436the <code class="computeroutput">stdstring</code>, 437<code class="computeroutput">length64</code>, 438<code class="computeroutput">newarray</code> 439and <code class="computeroutput">multipleinheritance</code> cases. If the 440heuristic detects that an interior pointer corresponds to such a case, 441the block will be considered as reachable by the interior 442pointer. In other words, the interior pointer will be treated 443as if it were a start pointer.</p> 444<p>With that in mind, consider the nine possible cases described by the 445following figure.</p> 446<pre class="programlisting"> 447 Pointer chain AAA Leak Case BBB Leak Case 448 ------------- ------------- ------------- 449(1) RRR ------------> BBB DR 450(2) RRR ---> AAA ---> BBB DR IR 451(3) RRR BBB DL 452(4) RRR AAA ---> BBB DL IL 453(5) RRR ------?-----> BBB (y)DR, (n)DL 454(6) RRR ---> AAA -?-> BBB DR (y)IR, (n)DL 455(7) RRR -?-> AAA ---> BBB (y)DR, (n)DL (y)IR, (n)IL 456(8) RRR -?-> AAA -?-> BBB (y)DR, (n)DL (y,y)IR, (n,y)IL, (_,n)DL 457(9) RRR AAA -?-> BBB DL (y)IL, (n)DL 458 459Pointer chain legend: 460- RRR: a root set node or DR block 461- AAA, BBB: heap blocks 462- --->: a start-pointer 463- -?->: an interior-pointer 464 465Leak Case legend: 466- DR: Directly reachable 467- IR: Indirectly reachable 468- DL: Directly lost 469- IL: Indirectly lost 470- (y)XY: it's XY if the interior-pointer is a real pointer 471- (n)XY: it's XY if the interior-pointer is not a real pointer 472- (_)XY: it's XY in either case 473</pre> 474<p>Every possible case can be reduced to one of the above nine. Memcheck 475merges some of these cases in its output, resulting in the following four 476leak kinds.</p> 477<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 478<li class="listitem"><p>"Still reachable". This covers cases 1 and 2 (for the BBB blocks) 479 above. A start-pointer or chain of start-pointers to the block is 480 found. Since the block is still pointed at, the programmer could, at 481 least in principle, have freed it before program exit. "Still reachable" 482 blocks are very common and arguably not a problem. So, by default, 483 Memcheck won't report such blocks individually.</p></li> 484<li class="listitem"><p>"Definitely lost". This covers case 3 (for the BBB blocks) above. 485 This means that no pointer to the block can be found. The block is 486 classified as "lost", because the programmer could not possibly have 487 freed it at program exit, since no pointer to it exists. This is likely 488 a symptom of having lost the pointer at some earlier point in the 489 program. Such cases should be fixed by the programmer.</p></li> 490<li class="listitem"><p>"Indirectly lost". This covers cases 4 and 9 (for the BBB blocks) 491 above. This means that the block is lost, not because there are no 492 pointers to it, but rather because all the blocks that point to it are 493 themselves lost. For example, if you have a binary tree and the root 494 node is lost, all its children nodes will be indirectly lost. Because 495 the problem will disappear if the definitely lost block that caused the 496 indirect leak is fixed, Memcheck won't report such blocks individually 497 by default.</p></li> 498<li class="listitem"><p>"Possibly lost". This covers cases 5--8 (for the BBB blocks) 499 above. This means that a chain of one or more pointers to the block has 500 been found, but at least one of the pointers is an interior-pointer. 501 This could just be a random value in memory that happens to point into a 502 block, and so you shouldn't consider this ok unless you know you have 503 interior-pointers.</p></li> 504</ul></div> 505<p>(Note: This mapping of the nine possible cases onto four leak kinds is 506not necessarily the best way that leaks could be reported; in particular, 507interior-pointers are treated inconsistently. It is possible the 508categorisation may be improved in the future.)</p> 509<p>Furthermore, if suppressions exists for a block, it will be reported 510as "suppressed" no matter what which of the above four kinds it belongs 511to.</p> 512<p>The following is an example leak summary.</p> 513<pre class="programlisting"> 514LEAK SUMMARY: 515 definitely lost: 48 bytes in 3 blocks. 516 indirectly lost: 32 bytes in 2 blocks. 517 possibly lost: 96 bytes in 6 blocks. 518 still reachable: 64 bytes in 4 blocks. 519 suppressed: 0 bytes in 0 blocks. 520</pre> 521<p>If heuristics have been used to consider some blocks as 522reachable, the leak summary details the heuristically reachable subset 523of 'still reachable:' per heuristic. In the below example, of the 95 524bytes still reachable, 87 bytes (56+7+8+16) have been considered 525heuristically reachable. 526</p> 527<pre class="programlisting"> 528LEAK SUMMARY: 529 definitely lost: 4 bytes in 1 blocks 530 indirectly lost: 0 bytes in 0 blocks 531 possibly lost: 0 bytes in 0 blocks 532 still reachable: 95 bytes in 6 blocks 533 of which reachable via heuristic: 534 stdstring : 56 bytes in 2 blocks 535 length64 : 16 bytes in 1 blocks 536 newarray : 7 bytes in 1 blocks 537 multipleinheritance: 8 bytes in 1 blocks 538 suppressed: 0 bytes in 0 blocks 539</pre> 540<p>If <code class="option">--leak-check=full</code> is specified, 541Memcheck will give details for each definitely lost or possibly lost block, 542including where it was allocated. (Actually, it merges results for all 543blocks that have the same leak kind and sufficiently similar stack traces 544into a single "loss record". The 545<code class="option">--leak-resolution</code> lets you control the 546meaning of "sufficiently similar".) It cannot tell you when or how or why 547the pointer to a leaked block was lost; you have to work that out for 548yourself. In general, you should attempt to ensure your programs do not 549have any definitely lost or possibly lost blocks at exit.</p> 550<p>For example:</p> 551<pre class="programlisting"> 5528 bytes in 1 blocks are definitely lost in loss record 1 of 14 553 at 0x........: malloc (vg_replace_malloc.c:...) 554 by 0x........: mk (leak-tree.c:11) 555 by 0x........: main (leak-tree.c:39) 556 55788 (8 direct, 80 indirect) bytes in 1 blocks are definitely lost in loss record 13 of 14 558 at 0x........: malloc (vg_replace_malloc.c:...) 559 by 0x........: mk (leak-tree.c:11) 560 by 0x........: main (leak-tree.c:25) 561</pre> 562<p>The first message describes a simple case of a single 8 byte block 563that has been definitely lost. The second case mentions another 8 byte 564block that has been definitely lost; the difference is that a further 80 565bytes in other blocks are indirectly lost because of this lost block. 566The loss records are not presented in any notable order, so the loss record 567numbers aren't particularly meaningful. The loss record numbers can be used 568in the Valgrind gdbserver to list the addresses of the leaked blocks and/or give 569more details about how a block is still reachable.</p> 570<p>The option <code class="option">--show-leak-kinds=<set></code> 571controls the set of leak kinds to show 572when <code class="option">--leak-check=full</code> is specified. </p> 573<p>The <code class="option"><set></code> of leak kinds is specified 574in one of the following ways: 575 576</p> 577<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 578<li class="listitem"><p>a comma separated list of one or more of 579 <code class="option">definite indirect possible reachable</code>.</p></li> 580<li class="listitem"><p><code class="option">all</code> to specify the complete set (all leak kinds).</p></li> 581<li class="listitem"><p><code class="option">none</code> for the empty set.</p></li> 582</ul></div> 583<p> 584 585</p> 586<p> The default value for the leak kinds to show is 587 <code class="option">--show-leak-kinds=definite,possible</code>. 588</p> 589<p>To also show the reachable and indirectly lost blocks in 590addition to the definitely and possibly lost blocks, you can 591use <code class="option">--show-leak-kinds=all</code>. To only show the 592reachable and indirectly lost blocks, use 593<code class="option">--show-leak-kinds=indirect,reachable</code>. The reachable 594and indirectly lost blocks will then be presented as shown in 595the following two examples.</p> 596<pre class="programlisting"> 59764 bytes in 4 blocks are still reachable in loss record 2 of 4 598 at 0x........: malloc (vg_replace_malloc.c:177) 599 by 0x........: mk (leak-cases.c:52) 600 by 0x........: main (leak-cases.c:74) 601 60232 bytes in 2 blocks are indirectly lost in loss record 1 of 4 603 at 0x........: malloc (vg_replace_malloc.c:177) 604 by 0x........: mk (leak-cases.c:52) 605 by 0x........: main (leak-cases.c:80) 606</pre> 607<p>Because there are different kinds of leaks with different 608severities, an interesting question is: which leaks should be 609counted as true "errors" and which should not? 610</p> 611<p> The answer to this question affects the numbers printed in 612the <code class="computeroutput">ERROR SUMMARY</code> line, and also the 613effect of the <code class="option">--error-exitcode</code> option. First, a leak 614is only counted as a true "error" 615if <code class="option">--leak-check=full</code> is specified. Then, the 616option <code class="option">--errors-for-leak-kinds=<set></code> controls 617the set of leak kinds to consider as errors. The default value 618is <code class="option">--errors-for-leak-kinds=definite,possible</code> 619</p> 620</div> 621</div> 622<div class="sect1"> 623<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 624<a name="mc-manual.options"></a>4.3.�Memcheck Command-Line Options</h2></div></div></div> 625<div class="variablelist"> 626<a name="mc.opts.list"></a><dl class="variablelist"> 627<dt> 628<a name="opt.leak-check"></a><span class="term"> 629 <code class="option">--leak-check=<no|summary|yes|full> [default: summary] </code> 630 </span> 631</dt> 632<dd><p>When enabled, search for memory leaks when the client 633 program finishes. If set to <code class="varname">summary</code>, it says how 634 many leaks occurred. If set to <code class="varname">full</code> or 635 <code class="varname">yes</code>, each individual leak will be shown 636 in detail and/or counted as an error, as specified by the options 637 <code class="option">--show-leak-kinds</code> and 638 <code class="option">--errors-for-leak-kinds</code>. </p></dd> 639<dt> 640<a name="opt.leak-resolution"></a><span class="term"> 641 <code class="option">--leak-resolution=<low|med|high> [default: high] </code> 642 </span> 643</dt> 644<dd> 645<p>When doing leak checking, determines how willing 646 Memcheck is to consider different backtraces to 647 be the same for the purposes of merging multiple leaks into a single 648 leak report. When set to <code class="varname">low</code>, only the first 649 two entries need match. When <code class="varname">med</code>, four entries 650 have to match. When <code class="varname">high</code>, all entries need to 651 match.</p> 652<p>For hardcore leak debugging, you probably want to use 653 <code class="option">--leak-resolution=high</code> together with 654 <code class="option">--num-callers=40</code> or some such large number. 655 </p> 656<p>Note that the <code class="option">--leak-resolution</code> setting 657 does not affect Memcheck's ability to find 658 leaks. It only changes how the results are presented.</p> 659</dd> 660<dt> 661<a name="opt.show-leak-kinds"></a><span class="term"> 662 <code class="option">--show-leak-kinds=<set> [default: definite,possible] </code> 663 </span> 664</dt> 665<dd> 666<p>Specifies the leak kinds to show in a <code class="varname">full</code> 667 leak search, in one of the following ways: </p> 668<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 669<li class="listitem"><p>a comma separated list of one or more of 670 <code class="option">definite indirect possible reachable</code>.</p></li> 671<li class="listitem"><p><code class="option">all</code> to specify the complete set (all leak kinds). 672 It is equivalent to 673 <code class="option">--show-leak-kinds=definite,indirect,possible,reachable</code>.</p></li> 674<li class="listitem"><p><code class="option">none</code> for the empty set.</p></li> 675</ul></div> 676</dd> 677<dt> 678<a name="opt.errors-for-leak-kinds"></a><span class="term"> 679 <code class="option">--errors-for-leak-kinds=<set> [default: definite,possible] </code> 680 </span> 681</dt> 682<dd><p>Specifies the leak kinds to count as errors in a 683 <code class="varname">full</code> leak search. The 684 <code class="option"><set></code> is specified similarly to 685 <code class="option">--show-leak-kinds</code> 686 </p></dd> 687<dt> 688<a name="opt.leak-check-heuristics"></a><span class="term"> 689 <code class="option">--leak-check-heuristics=<set> [default: all] </code> 690 </span> 691</dt> 692<dd> 693<p>Specifies the set of leak check heuristics to be used 694 during leak searches. The heuristics control which interior pointers 695 to a block cause it to be considered as reachable. 696 The heuristic set is specified in one of the following ways:</p> 697<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 698<li class="listitem"><p>a comma separated list of one or more of 699 <code class="option">stdstring length64 newarray multipleinheritance</code>.</p></li> 700<li class="listitem"><p><code class="option">all</code> to activate the complete set of 701 heuristics. 702 It is equivalent to 703 <code class="option">--leak-check-heuristics=stdstring,length64,newarray,multipleinheritance</code>.</p></li> 704<li class="listitem"><p><code class="option">none</code> for the empty set.</p></li> 705</ul></div> 706</dd> 707<dt> 708<a name="opt.show-reachable"></a><span class="term"> 709 <code class="option">--show-reachable=<yes|no> </code> 710 , </span><span class="term"> 711 <code class="option">--show-possibly-lost=<yes|no> </code> 712 </span> 713</dt> 714<dd> 715<p>These options provide an alternative way to specify the leak kinds to show: 716 </p> 717<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 718<li class="listitem"><p> 719 <code class="option">--show-reachable=no --show-possibly-lost=yes</code> is equivalent to 720 <code class="option">--show-leak-kinds=definite,possible</code>. 721 </p></li> 722<li class="listitem"><p> 723 <code class="option">--show-reachable=no --show-possibly-lost=no</code> is equivalent to 724 <code class="option">--show-leak-kinds=definite</code>. 725 </p></li> 726<li class="listitem"><p> 727 <code class="option">--show-reachable=yes</code> is equivalent to 728 <code class="option">--show-leak-kinds=all</code>. 729 </p></li> 730</ul></div> 731</dd> 732<dt> 733<a name="opt.xtree-leak"></a><span class="term"> 734 <code class="option">--xtree-leak=<no|yes> [no] </code> 735 </span> 736</dt> 737<dd> 738<p>If set to yes, the results for the leak search done at exit will be 739 output in a 'Callgrind Format' execution tree file. Note that this 740 automatically sets the option <code class="option">--leak-check=full</code>. 741 The produced file 742 will contain the following events:</p> 743<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 744<li class="listitem"><p><code class="option">RB</code> : Reachable Bytes</p></li> 745<li class="listitem"><p><code class="option">PB</code> : Possibly lost Bytes</p></li> 746<li class="listitem"><p><code class="option">IB</code> : Indirectly lost Bytes</p></li> 747<li class="listitem"><p><code class="option">DB</code> : Definitely lost Bytes (direct plus indirect)</p></li> 748<li class="listitem"><p><code class="option">DIB</code> : Definitely Indirectly lost Bytes (subset of DB)</p></li> 749<li class="listitem"><p><code class="option">RBk</code> : reachable Blocks</p></li> 750<li class="listitem"><p><code class="option">PBk</code> : Possibly lost Blocks</p></li> 751<li class="listitem"><p><code class="option">IBk</code> : Indirectly lost Blocks</p></li> 752<li class="listitem"><p><code class="option">DBk</code> : Definitely lost Blocks</p></li> 753</ul></div> 754<p>The increase or decrease for all events above will also be output in 755 the file to provide the delta (increase or decrease� between 2 756 successive leak searches. For example, <code class="option">iRB</code> is the 757 increase of the <code class="option">RB</code> event, <code class="option">dPBk</code> is the 758 decrease of <code class="option">PBk</code> event. The values for the increase and 759 decrease events will be zero for the first leak search done.</p> 760<p>See <a class="xref" href="manual-core.html#manual-core.xtree" title="2.9.�Execution Trees">Execution Trees</a> for a detailed explanation 761 about execution trees.</p> 762</dd> 763<dt> 764<a name="opt.xtree-leak-file"></a><span class="term"> 765 <code class="option">--xtree-leak-file=<filename> [default: 766 xtleak.kcg.%p] </code> 767 </span> 768</dt> 769<dd> 770<p>Specifies that Valgrind should produce the xtree leak 771 report in the specified file. Any <code class="option">%p</code>, 772 <code class="option">%q</code> or <code class="option">%n</code> sequences appearing in 773 the filename are expanded 774 in exactly the same way as they are for <code class="option">--log-file</code>. 775 See the description of <a class="xref" href="manual-core.html#opt.log-file">--log-file</a> 776 for details. </p> 777<p>See <a class="xref" href="manual-core.html#manual-core.xtree" title="2.9.�Execution Trees">Execution Trees</a> 778 for a detailed explanation about execution trees formats. </p> 779</dd> 780<dt> 781<a name="opt.undef-value-errors"></a><span class="term"> 782 <code class="option">--undef-value-errors=<yes|no> [default: yes] </code> 783 </span> 784</dt> 785<dd><p>Controls whether Memcheck reports 786 uses of undefined value errors. Set this to 787 <code class="varname">no</code> if you don't want to see undefined value 788 errors. It also has the side effect of speeding up 789 Memcheck somewhat. 790 </p></dd> 791<dt> 792<a name="opt.track-origins"></a><span class="term"> 793 <code class="option">--track-origins=<yes|no> [default: no] </code> 794 </span> 795</dt> 796<dd> 797<p>Controls whether Memcheck tracks 798 the origin of uninitialised values. By default, it does not, 799 which means that although it can tell you that an 800 uninitialised value is being used in a dangerous way, it 801 cannot tell you where the uninitialised value came from. This 802 often makes it difficult to track down the root problem. 803 </p> 804<p>When set 805 to <code class="varname">yes</code>, Memcheck keeps 806 track of the origins of all uninitialised values. Then, when 807 an uninitialised value error is 808 reported, Memcheck will try to show the 809 origin of the value. An origin can be one of the following 810 four places: a heap block, a stack allocation, a client 811 request, or miscellaneous other sources (eg, a call 812 to <code class="varname">brk</code>). 813 </p> 814<p>For uninitialised values originating from a heap 815 block, Memcheck shows where the block was 816 allocated. For uninitialised values originating from a stack 817 allocation, Memcheck can tell you which 818 function allocated the value, but no more than that -- typically 819 it shows you the source location of the opening brace of the 820 function. So you should carefully check that all of the 821 function's local variables are initialised properly. 822 </p> 823<p>Performance overhead: origin tracking is expensive. It 824 halves Memcheck's speed and increases 825 memory use by a minimum of 100MB, and possibly more. 826 Nevertheless it can drastically reduce the effort required to 827 identify the root cause of uninitialised value errors, and so 828 is often a programmer productivity win, despite running 829 more slowly. 830 </p> 831<p>Accuracy: Memcheck tracks origins 832 quite accurately. To avoid very large space and time 833 overheads, some approximations are made. It is possible, 834 although unlikely, that Memcheck will report an incorrect origin, or 835 not be able to identify any origin. 836 </p> 837<p>Note that the combination 838 <code class="option">--track-origins=yes</code> 839 and <code class="option">--undef-value-errors=no</code> is 840 nonsensical. Memcheck checks for and 841 rejects this combination at startup. 842 </p> 843</dd> 844<dt> 845<a name="opt.partial-loads-ok"></a><span class="term"> 846 <code class="option">--partial-loads-ok=<yes|no> [default: yes] </code> 847 </span> 848</dt> 849<dd> 850<p>Controls how Memcheck handles 32-, 64-, 128- and 256-bit 851 naturally aligned loads from addresses for which some bytes are 852 addressable and others are not. When <code class="varname">yes</code>, such 853 loads do not produce an address error. Instead, loaded bytes 854 originating from illegal addresses are marked as uninitialised, and 855 those corresponding to legal addresses are handled in the normal 856 way.</p> 857<p>When <code class="varname">no</code>, loads from partially invalid 858 addresses are treated the same as loads from completely invalid 859 addresses: an illegal-address error is issued, and the resulting 860 bytes are marked as initialised.</p> 861<p>Note that code that behaves in this way is in violation of 862 the ISO C/C++ standards, and should be considered broken. If 863 at all possible, such code should be fixed.</p> 864</dd> 865<dt> 866<a name="opt.expensive-definedness-checks"></a><span class="term"> 867 <code class="option">--expensive-definedness-checks=<yes|no> [default: no] </code> 868 </span> 869</dt> 870<dd><p>Controls whether Memcheck should employ more precise but also more 871 expensive (time consuming) algorithms when checking the definedness of a 872 value. The default setting is not to do that and it is usually 873 sufficient. However, for highly optimised code valgrind may sometimes 874 incorrectly complain. 875 Invoking valgrind with <code class="option">--expensive-definedness-checks=yes</code> 876 helps but comes at a performance cost. Runtime degradation of 877 25% have been observed but the extra cost depends a lot on the 878 application at hand. 879 </p></dd> 880<dt> 881<a name="opt.keep-stacktraces"></a><span class="term"> 882 <code class="option">--keep-stacktraces=alloc|free|alloc-and-free|alloc-then-free|none [default: alloc-and-free] </code> 883 </span> 884</dt> 885<dd> 886<p>Controls which stack trace(s) to keep for malloc'd and/or 887 free'd blocks. 888 </p> 889<p>With <code class="varname">alloc-then-free</code>, a stack trace is 890 recorded at allocation time, and is associated with the block. 891 When the block is freed, a second stack trace is recorded, and 892 this replaces the allocation stack trace. As a result, any "use 893 after free" errors relating to this block can only show a stack 894 trace for where the block was freed. 895 </p> 896<p>With <code class="varname">alloc-and-free</code>, both allocation 897 and the deallocation stack traces for the block are stored. 898 Hence a "use after free" error will 899 show both, which may make the error easier to diagnose. 900 Compared to <code class="varname">alloc-then-free</code>, this setting 901 slightly increases Valgrind's memory use as the block contains two 902 references instead of one. 903 </p> 904<p>With <code class="varname">alloc</code>, only the allocation stack 905 trace is recorded (and reported). With <code class="varname">free</code>, 906 only the deallocation stack trace is recorded (and reported). 907 These values somewhat decrease Valgrind's memory and cpu usage. 908 They can be useful depending on the error types you are 909 searching for and the level of detail you need to analyse 910 them. For example, if you are only interested in memory leak 911 errors, it is sufficient to record the allocation stack traces. 912 </p> 913<p>With <code class="varname">none</code>, no stack traces are recorded 914 for malloc and free operations. If your program allocates a lot 915 of blocks and/or allocates/frees from many different stack 916 traces, this can significantly decrease cpu and/or memory 917 required. Of course, few details will be reported for errors 918 related to heap blocks. 919 </p> 920<p>Note that once a stack trace is recorded, Valgrind keeps 921 the stack trace in memory even if it is not referenced by any 922 block. Some programs (for example, recursive algorithms) can 923 generate a huge number of stack traces. If Valgrind uses too 924 much memory in such circumstances, you can reduce the memory 925 required with the options <code class="varname">--keep-stacktraces</code> 926 and/or by using a smaller value for the 927 option <code class="varname">--num-callers</code>. 928 </p> 929<p>If you want to use 930 <code class="computeroutput">--xtree-memory=full</code> memory profiling 931 (see <a class="xref" href="manual-core.html#manual-core.xtree" title="2.9.�Execution Trees">Execution Trees</a> ), then you cannot 932 specify <code class="varname">--keep-stacktraces=free</code> 933 or <code class="varname">--keep-stacktraces=none</code>.</p> 934</dd> 935<dt> 936<a name="opt.freelist-vol"></a><span class="term"> 937 <code class="option">--freelist-vol=<number> [default: 20000000] </code> 938 </span> 939</dt> 940<dd> 941<p>When the client program releases memory using 942 <code class="function">free</code> (in <code class="literal">C</code>) or 943 <code class="computeroutput">delete</code> 944 (<code class="literal">C++</code>), that memory is not immediately made 945 available for re-allocation. Instead, it is marked inaccessible 946 and placed in a queue of freed blocks. The purpose is to defer as 947 long as possible the point at which freed-up memory comes back 948 into circulation. This increases the chance that 949 Memcheck will be able to detect invalid 950 accesses to blocks for some significant period of time after they 951 have been freed.</p> 952<p>This option specifies the maximum total size, in bytes, of the 953 blocks in the queue. The default value is twenty million bytes. 954 Increasing this increases the total amount of memory used by 955 Memcheck but may detect invalid uses of freed 956 blocks which would otherwise go undetected.</p> 957</dd> 958<dt> 959<a name="opt.freelist-big-blocks"></a><span class="term"> 960 <code class="option">--freelist-big-blocks=<number> [default: 1000000] </code> 961 </span> 962</dt> 963<dd> 964<p>When making blocks from the queue of freed blocks available 965 for re-allocation, Memcheck will in priority re-circulate the blocks 966 with a size greater or equal to <code class="option">--freelist-big-blocks</code>. 967 This ensures that freeing big blocks (in particular freeing blocks bigger than 968 <code class="option">--freelist-vol</code>) does not immediately lead to a re-circulation 969 of all (or a lot of) the small blocks in the free list. In other words, 970 this option increases the likelihood to discover dangling pointers 971 for the "small" blocks, even when big blocks are freed.</p> 972<p>Setting a value of 0 means that all the blocks are re-circulated 973 in a FIFO order. </p> 974</dd> 975<dt> 976<a name="opt.workaround-gcc296-bugs"></a><span class="term"> 977 <code class="option">--workaround-gcc296-bugs=<yes|no> [default: no] </code> 978 </span> 979</dt> 980<dd> 981<p>When enabled, assume that reads and writes some small 982 distance below the stack pointer are due to bugs in GCC 2.96, and 983 does not report them. The "small distance" is 256 bytes by 984 default. Note that GCC 2.96 is the default compiler on some ancient 985 Linux distributions (RedHat 7.X) and so you may need to use this 986 option. Do not use it if you do not have to, as it can cause real 987 errors to be overlooked. A better alternative is to use a more 988 recent GCC in which this bug is fixed.</p> 989<p>You may also need to use this option when working with 990 GCC 3.X or 4.X on 32-bit PowerPC Linux. This is because 991 GCC generates code which occasionally accesses below the 992 stack pointer, particularly for floating-point to/from integer 993 conversions. This is in violation of the 32-bit PowerPC ELF 994 specification, which makes no provision for locations below the 995 stack pointer to be accessible.</p> 996<p>This option is deprecated as of version 3.12 and may be 997 removed from future versions. You should instead use 998 <code class="option">--ignore-range-below-sp</code> to specify the exact 999 range of offsets below the stack pointer that should be ignored. 1000 A suitable equivalent 1001 is <code class="option">--ignore-range-below-sp=1024-1</code>. 1002 </p> 1003</dd> 1004<dt> 1005<a name="opt.ignore-range-below-sp"></a><span class="term"> 1006 <code class="option">--ignore-range-below-sp=<number>-<number> </code> 1007 </span> 1008</dt> 1009<dd><p>This is a more general replacement for the deprecated 1010 <code class="option">--workaround-gcc296-bugs</code> option. When 1011 specified, it causes Memcheck not to report errors for accesses 1012 at the specified offsets below the stack pointer. The two 1013 offsets must be positive decimal numbers and -- somewhat 1014 counterintuitively -- the first one must be larger, in order to 1015 imply a non-wraparound address range to ignore. For example, 1016 to ignore 4 byte accesses at 8192 bytes below the stack 1017 pointer, 1018 use <code class="option">--ignore-range-below-sp=8192-8189</code>. Only 1019 one range may be specified. 1020 </p></dd> 1021<dt> 1022<a name="opt.show-mismatched-frees"></a><span class="term"> 1023 <code class="option">--show-mismatched-frees=<yes|no> [default: yes] </code> 1024 </span> 1025</dt> 1026<dd> 1027<p>When enabled, Memcheck checks that heap blocks are 1028 deallocated using a function that matches the allocating 1029 function. That is, it expects <code class="varname">free</code> to be 1030 used to deallocate blocks allocated 1031 by <code class="varname">malloc</code>, <code class="varname">delete</code> for 1032 blocks allocated by <code class="varname">new</code>, 1033 and <code class="varname">delete[]</code> for blocks allocated 1034 by <code class="varname">new[]</code>. If a mismatch is detected, an 1035 error is reported. This is in general important because in some 1036 environments, freeing with a non-matching function can cause 1037 crashes.</p> 1038<p>There is however a scenario where such mismatches cannot 1039 be avoided. That is when the user provides implementations of 1040 <code class="varname">new</code>/<code class="varname">new[]</code> that 1041 call <code class="varname">malloc</code> and 1042 of <code class="varname">delete</code>/<code class="varname">delete[]</code> that 1043 call <code class="varname">free</code>, and these functions are 1044 asymmetrically inlined. For example, imagine 1045 that <code class="varname">delete[]</code> is inlined 1046 but <code class="varname">new[]</code> is not. The result is that 1047 Memcheck "sees" all <code class="varname">delete[]</code> calls as direct 1048 calls to <code class="varname">free</code>, even when the program source 1049 contains no mismatched calls.</p> 1050<p>This causes a lot of confusing and irrelevant error 1051 reports. <code class="varname">--show-mismatched-frees=no</code> disables 1052 these checks. It is not generally advisable to disable them, 1053 though, because you may miss real errors as a result.</p> 1054</dd> 1055<dt> 1056<a name="opt.ignore-ranges"></a><span class="term"> 1057 <code class="option">--ignore-ranges=0xPP-0xQQ[,0xRR-0xSS] </code> 1058 </span> 1059</dt> 1060<dd><p>Any ranges listed in this option (and multiple ranges can be 1061 specified, separated by commas) will be ignored by Memcheck's 1062 addressability checking.</p></dd> 1063<dt> 1064<a name="opt.malloc-fill"></a><span class="term"> 1065 <code class="option">--malloc-fill=<hexnumber> </code> 1066 </span> 1067</dt> 1068<dd><p>Fills blocks allocated 1069 by <code class="computeroutput">malloc</code>, 1070 <code class="computeroutput">new</code>, etc, but not 1071 by <code class="computeroutput">calloc</code>, with the specified 1072 byte. This can be useful when trying to shake out obscure 1073 memory corruption problems. The allocated area is still 1074 regarded by Memcheck as undefined -- this option only affects its 1075 contents. Note that <code class="option">--malloc-fill</code> does not 1076 affect a block of memory when it is used as argument 1077 to client requests VALGRIND_MEMPOOL_ALLOC or 1078 VALGRIND_MALLOCLIKE_BLOCK. 1079 </p></dd> 1080<dt> 1081<a name="opt.free-fill"></a><span class="term"> 1082 <code class="option">--free-fill=<hexnumber> </code> 1083 </span> 1084</dt> 1085<dd><p>Fills blocks freed 1086 by <code class="computeroutput">free</code>, 1087 <code class="computeroutput">delete</code>, etc, with the 1088 specified byte value. This can be useful when trying to shake out 1089 obscure memory corruption problems. The freed area is still 1090 regarded by Memcheck as not valid for access -- this option only 1091 affects its contents. Note that <code class="option">--free-fill</code> does not 1092 affect a block of memory when it is used as argument to 1093 client requests VALGRIND_MEMPOOL_FREE or VALGRIND_FREELIKE_BLOCK. 1094 </p></dd> 1095</dl> 1096</div> 1097</div> 1098<div class="sect1"> 1099<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1100<a name="mc-manual.suppfiles"></a>4.4.�Writing suppression files</h2></div></div></div> 1101<p>The basic suppression format is described in 1102<a class="xref" href="manual-core.html#manual-core.suppress" title="2.5.�Suppressing errors">Suppressing errors</a>.</p> 1103<p>The suppression-type (second) line should have the form:</p> 1104<pre class="programlisting"> 1105Memcheck:suppression_type</pre> 1106<p>The Memcheck suppression types are as follows:</p> 1107<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1108<li class="listitem"><p><code class="varname">Value1</code>, 1109 <code class="varname">Value2</code>, 1110 <code class="varname">Value4</code>, 1111 <code class="varname">Value8</code>, 1112 <code class="varname">Value16</code>, 1113 meaning an uninitialised-value error when 1114 using a value of 1, 2, 4, 8 or 16 bytes.</p></li> 1115<li class="listitem"><p><code class="varname">Cond</code> (or its old 1116 name, <code class="varname">Value0</code>), meaning use 1117 of an uninitialised CPU condition code.</p></li> 1118<li class="listitem"><p><code class="varname">Addr1</code>, 1119 <code class="varname">Addr2</code>, 1120 <code class="varname">Addr4</code>, 1121 <code class="varname">Addr8</code>, 1122 <code class="varname">Addr16</code>, 1123 meaning an invalid address during a 1124 memory access of 1, 2, 4, 8 or 16 bytes respectively.</p></li> 1125<li class="listitem"><p><code class="varname">Jump</code>, meaning an 1126 jump to an unaddressable location error.</p></li> 1127<li class="listitem"><p><code class="varname">Param</code>, meaning an 1128 invalid system call parameter error.</p></li> 1129<li class="listitem"><p><code class="varname">Free</code>, meaning an 1130 invalid or mismatching free.</p></li> 1131<li class="listitem"><p><code class="varname">Overlap</code>, meaning a 1132 <code class="computeroutput">src</code> / 1133 <code class="computeroutput">dst</code> overlap in 1134 <code class="function">memcpy</code> or a similar function.</p></li> 1135<li class="listitem"><p><code class="varname">Leak</code>, meaning 1136 a memory leak.</p></li> 1137</ul></div> 1138<p><code class="computeroutput">Param</code> errors have a mandatory extra 1139information line at this point, which is the name of the offending 1140system call parameter. </p> 1141<p><code class="computeroutput">Leak</code> errors have an optional 1142extra information line, with the following format:</p> 1143<pre class="programlisting"> 1144match-leak-kinds:<set></pre> 1145<p>where <code class="computeroutput"><set></code> specifies which 1146leak kinds are matched by this suppression entry. 1147<code class="computeroutput"><set></code> is specified in the 1148same way as with the option <code class="option">--show-leak-kinds</code>, that is, 1149one of the following:</p> 1150<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1151<li class="listitem">a comma separated list of one or more of 1152 <code class="option">definite indirect possible reachable</code>. 1153 </li> 1154<li class="listitem"> 1155<code class="option">all</code> to specify the complete set (all leak kinds). 1156 </li> 1157<li class="listitem"> 1158<code class="option">none</code> for the empty set. 1159 </li> 1160</ul></div> 1161<p>If this optional extra line is not present, the suppression 1162entry will match all leak kinds.</p> 1163<p>Be aware that leak suppressions that are created using 1164<code class="option">--gen-suppressions</code> will contain this optional extra 1165line, and therefore may match fewer leaks than you expect. You may 1166want to remove the line before using the generated 1167suppressions.</p> 1168<p>The other Memcheck error kinds do not have extra lines.</p> 1169<p> 1170If you give the <code class="option">-v</code> option, Valgrind will print 1171the list of used suppressions at the end of execution. 1172For a leak suppression, this output gives the number of different 1173loss records that match the suppression, and the number of bytes 1174and blocks suppressed by the suppression. 1175If the run contains multiple leak checks, the number of bytes and blocks 1176are reset to zero before each new leak check. Note that the number of different 1177loss records is not reset to zero.</p> 1178<p>In the example below, in the last leak search, 7 blocks and 96 bytes have 1179been suppressed by a suppression with the name 1180<code class="option">some_leak_suppression</code>:</p> 1181<pre class="programlisting"> 1182--21041-- used_suppression: 10 some_other_leak_suppression s.supp:14 suppressed: 12,400 bytes in 1 blocks 1183--21041-- used_suppression: 39 some_leak_suppression s.supp:2 suppressed: 96 bytes in 7 blocks 1184</pre> 1185<p>For <code class="varname">ValueN</code> and <code class="varname">AddrN</code> 1186errors, the first line of the calling context is either the name of 1187the function in which the error occurred, or, failing that, the full 1188path of the <code class="filename">.so</code> file or executable containing the 1189error location. For <code class="varname">Free</code> errors, the first line is 1190the name of the function doing the freeing (eg, 1191<code class="function">free</code>, <code class="function">__builtin_vec_delete</code>, 1192etc). For <code class="varname">Overlap</code> errors, the first line is the name of the 1193function with the overlapping arguments (eg. 1194<code class="function">memcpy</code>, <code class="function">strcpy</code>, etc).</p> 1195<p>The last part of any suppression specifies the rest of the 1196calling context that needs to be matched.</p> 1197</div> 1198<div class="sect1"> 1199<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1200<a name="mc-manual.machine"></a>4.5.�Details of Memcheck's checking machinery</h2></div></div></div> 1201<p>Read this section if you want to know, in detail, exactly 1202what and how Memcheck is checking.</p> 1203<div class="sect2"> 1204<div class="titlepage"><div><div><h3 class="title"> 1205<a name="mc-manual.value"></a>4.5.1.�Valid-value (V) bits</h3></div></div></div> 1206<p>It is simplest to think of Memcheck implementing a synthetic CPU 1207which is identical to a real CPU, except for one crucial detail. Every 1208bit (literally) of data processed, stored and handled by the real CPU 1209has, in the synthetic CPU, an associated "valid-value" bit, which says 1210whether or not the accompanying bit has a legitimate value. In the 1211discussions which follow, this bit is referred to as the V (valid-value) 1212bit.</p> 1213<p>Each byte in the system therefore has a 8 V bits which follow it 1214wherever it goes. For example, when the CPU loads a word-size item (4 1215bytes) from memory, it also loads the corresponding 32 V bits from a 1216bitmap which stores the V bits for the process' entire address space. 1217If the CPU should later write the whole or some part of that value to 1218memory at a different address, the relevant V bits will be stored back 1219in the V-bit bitmap.</p> 1220<p>In short, each bit in the system has (conceptually) an associated V 1221bit, which follows it around everywhere, even inside the CPU. Yes, all the 1222CPU's registers (integer, floating point, vector and condition registers) 1223have their own V bit vectors. For this to work, Memcheck uses a great deal 1224of compression to represent the V bits compactly.</p> 1225<p>Copying values around does not cause Memcheck to check for, or 1226report on, errors. However, when a value is used in a way which might 1227conceivably affect your program's externally-visible behaviour, 1228the associated V bits are immediately checked. If any of these indicate 1229that the value is undefined (even partially), an error is reported.</p> 1230<p>Here's an (admittedly nonsensical) example:</p> 1231<pre class="programlisting"> 1232int i, j; 1233int a[10], b[10]; 1234for ( i = 0; i < 10; i++ ) { 1235 j = a[i]; 1236 b[i] = j; 1237}</pre> 1238<p>Memcheck emits no complaints about this, since it merely copies 1239uninitialised values from <code class="varname">a[]</code> into 1240<code class="varname">b[]</code>, and doesn't use them in a way which could 1241affect the behaviour of the program. However, if 1242the loop is changed to:</p> 1243<pre class="programlisting"> 1244for ( i = 0; i < 10; i++ ) { 1245 j += a[i]; 1246} 1247if ( j == 77 ) 1248 printf("hello there\n"); 1249</pre> 1250<p>then Memcheck will complain, at the 1251<code class="computeroutput">if</code>, that the condition depends on 1252uninitialised values. Note that it <span class="command"><strong>doesn't</strong></span> complain 1253at the <code class="varname">j += a[i];</code>, since at that point the 1254undefinedness is not "observable". It's only when a decision has to be 1255made as to whether or not to do the <code class="function">printf</code> -- an 1256observable action of your program -- that Memcheck complains.</p> 1257<p>Most low level operations, such as adds, cause Memcheck to use the 1258V bits for the operands to calculate the V bits for the result. Even if 1259the result is partially or wholly undefined, it does not 1260complain.</p> 1261<p>Checks on definedness only occur in three places: when a value is 1262used to generate a memory address, when control flow decision needs to 1263be made, and when a system call is detected, Memcheck checks definedness 1264of parameters as required.</p> 1265<p>If a check should detect undefinedness, an error message is 1266issued. The resulting value is subsequently regarded as well-defined. 1267To do otherwise would give long chains of error messages. In other 1268words, once Memcheck reports an undefined value error, it tries to 1269avoid reporting further errors derived from that same undefined 1270value.</p> 1271<p>This sounds overcomplicated. Why not just check all reads from 1272memory, and complain if an undefined value is loaded into a CPU 1273register? Well, that doesn't work well, because perfectly legitimate C 1274programs routinely copy uninitialised values around in memory, and we 1275don't want endless complaints about that. Here's the canonical example. 1276Consider a struct like this:</p> 1277<pre class="programlisting"> 1278struct S { int x; char c; }; 1279struct S s1, s2; 1280s1.x = 42; 1281s1.c = 'z'; 1282s2 = s1; 1283</pre> 1284<p>The question to ask is: how large is <code class="varname">struct S</code>, 1285in bytes? An <code class="varname">int</code> is 4 bytes and a 1286<code class="varname">char</code> one byte, so perhaps a <code class="varname">struct 1287S</code> occupies 5 bytes? Wrong. All non-toy compilers we know 1288of will round the size of <code class="varname">struct S</code> up to a whole 1289number of words, in this case 8 bytes. Not doing this forces compilers 1290to generate truly appalling code for accessing arrays of 1291<code class="varname">struct S</code>'s on some architectures.</p> 1292<p>So <code class="varname">s1</code> occupies 8 bytes, yet only 5 of them will 1293be initialised. For the assignment <code class="varname">s2 = s1</code>, GCC 1294generates code to copy all 8 bytes wholesale into <code class="varname">s2</code> 1295without regard for their meaning. If Memcheck simply checked values as 1296they came out of memory, it would yelp every time a structure assignment 1297like this happened. So the more complicated behaviour described above 1298is necessary. This allows GCC to copy 1299<code class="varname">s1</code> into <code class="varname">s2</code> any way it likes, and a 1300warning will only be emitted if the uninitialised values are later 1301used.</p> 1302</div> 1303<div class="sect2"> 1304<div class="titlepage"><div><div><h3 class="title"> 1305<a name="mc-manual.vaddress"></a>4.5.2.�Valid-address (A) bits</h3></div></div></div> 1306<p>Notice that the previous subsection describes how the validity of 1307values is established and maintained without having to say whether the 1308program does or does not have the right to access any particular memory 1309location. We now consider the latter question.</p> 1310<p>As described above, every bit in memory or in the CPU has an 1311associated valid-value (V) bit. In addition, all bytes in memory, but 1312not in the CPU, have an associated valid-address (A) bit. This 1313indicates whether or not the program can legitimately read or write that 1314location. It does not give any indication of the validity of the data 1315at that location -- that's the job of the V bits -- only whether or not 1316the location may be accessed.</p> 1317<p>Every time your program reads or writes memory, Memcheck checks 1318the A bits associated with the address. If any of them indicate an 1319invalid address, an error is emitted. Note that the reads and writes 1320themselves do not change the A bits, only consult them.</p> 1321<p>So how do the A bits get set/cleared? Like this:</p> 1322<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1323<li class="listitem"><p>When the program starts, all the global data areas are 1324 marked as accessible.</p></li> 1325<li class="listitem"><p>When the program does 1326 <code class="function">malloc</code>/<code class="computeroutput">new</code>, 1327 the A bits for exactly the area allocated, and not a byte more, 1328 are marked as accessible. Upon freeing the area the A bits are 1329 changed to indicate inaccessibility.</p></li> 1330<li class="listitem"><p>When the stack pointer register (<code class="literal">SP</code>) moves 1331 up or down, A bits are set. The rule is that the area from 1332 <code class="literal">SP</code> up to the base of the stack is marked as 1333 accessible, and below <code class="literal">SP</code> is inaccessible. (If 1334 that sounds illogical, bear in mind that the stack grows down, not 1335 up, on almost all Unix systems, including GNU/Linux.) Tracking 1336 <code class="literal">SP</code> like this has the useful side-effect that the 1337 section of stack used by a function for local variables etc is 1338 automatically marked accessible on function entry and inaccessible 1339 on exit.</p></li> 1340<li class="listitem"><p>When doing system calls, A bits are changed appropriately. 1341 For example, <code class="literal">mmap</code> 1342 magically makes files appear in the process' 1343 address space, so the A bits must be updated if <code class="literal">mmap</code> 1344 succeeds.</p></li> 1345<li class="listitem"><p>Optionally, your program can tell Memcheck about such changes 1346 explicitly, using the client request mechanism described 1347 above.</p></li> 1348</ul></div> 1349</div> 1350<div class="sect2"> 1351<div class="titlepage"><div><div><h3 class="title"> 1352<a name="mc-manual.together"></a>4.5.3.�Putting it all together</h3></div></div></div> 1353<p>Memcheck's checking machinery can be summarised as 1354follows:</p> 1355<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1356<li class="listitem"><p>Each byte in memory has 8 associated V (valid-value) bits, 1357 saying whether or not the byte has a defined value, and a single A 1358 (valid-address) bit, saying whether or not the program currently has 1359 the right to read/write that address. As mentioned above, heavy 1360 use of compression means the overhead is typically around 25%.</p></li> 1361<li class="listitem"><p>When memory is read or written, the relevant A bits are 1362 consulted. If they indicate an invalid address, Memcheck emits an 1363 Invalid read or Invalid write error.</p></li> 1364<li class="listitem"><p>When memory is read into the CPU's registers, the relevant V 1365 bits are fetched from memory and stored in the simulated CPU. They 1366 are not consulted.</p></li> 1367<li class="listitem"><p>When a register is written out to memory, the V bits for that 1368 register are written back to memory too.</p></li> 1369<li class="listitem"><p>When values in CPU registers are used to generate a memory 1370 address, or to determine the outcome of a conditional branch, the V 1371 bits for those values are checked, and an error emitted if any of 1372 them are undefined.</p></li> 1373<li class="listitem"><p>When values in CPU registers are used for any other purpose, 1374 Memcheck computes the V bits for the result, but does not check 1375 them.</p></li> 1376<li class="listitem"><p>Once the V bits for a value in the CPU have been checked, they 1377 are then set to indicate validity. This avoids long chains of 1378 errors.</p></li> 1379<li class="listitem"> 1380<p>When values are loaded from memory, Memcheck checks the A bits 1381 for that location and issues an illegal-address warning if needed. 1382 In that case, the V bits loaded are forced to indicate Valid, 1383 despite the location being invalid.</p> 1384<p>This apparently strange choice reduces the amount of confusing 1385 information presented to the user. It avoids the unpleasant 1386 phenomenon in which memory is read from a place which is both 1387 unaddressable and contains invalid values, and, as a result, you get 1388 not only an invalid-address (read/write) error, but also a 1389 potentially large set of uninitialised-value errors, one for every 1390 time the value is used.</p> 1391<p>There is a hazy boundary case to do with multi-byte loads from 1392 addresses which are partially valid and partially invalid. See 1393 details of the option <code class="option">--partial-loads-ok</code> for details. 1394 </p> 1395</li> 1396</ul></div> 1397<p>Memcheck intercepts calls to <code class="function">malloc</code>, 1398<code class="function">calloc</code>, <code class="function">realloc</code>, 1399<code class="function">valloc</code>, <code class="function">memalign</code>, 1400<code class="function">free</code>, <code class="computeroutput">new</code>, 1401<code class="computeroutput">new[]</code>, 1402<code class="computeroutput">delete</code> and 1403<code class="computeroutput">delete[]</code>. The behaviour you get 1404is:</p> 1405<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1406<li class="listitem"><p><code class="function">malloc</code>/<code class="function">new</code>/<code class="computeroutput">new[]</code>: 1407 the returned memory is marked as addressable but not having valid 1408 values. This means you have to write to it before you can read 1409 it.</p></li> 1410<li class="listitem"><p><code class="function">calloc</code>: returned memory is marked both 1411 addressable and valid, since <code class="function">calloc</code> clears 1412 the area to zero.</p></li> 1413<li class="listitem"><p><code class="function">realloc</code>: if the new size is larger than 1414 the old, the new section is addressable but invalid, as with 1415 <code class="function">malloc</code>. If the new size is smaller, the 1416 dropped-off section is marked as unaddressable. You may only pass to 1417 <code class="function">realloc</code> a pointer previously issued to you by 1418 <code class="function">malloc</code>/<code class="function">calloc</code>/<code class="function">realloc</code>.</p></li> 1419<li class="listitem"><p><code class="function">free</code>/<code class="computeroutput">delete</code>/<code class="computeroutput">delete[]</code>: 1420 you may only pass to these functions a pointer previously issued 1421 to you by the corresponding allocation function. Otherwise, 1422 Memcheck complains. If the pointer is indeed valid, Memcheck 1423 marks the entire area it points at as unaddressable, and places 1424 the block in the freed-blocks-queue. The aim is to defer as long 1425 as possible reallocation of this block. Until that happens, all 1426 attempts to access it will elicit an invalid-address error, as you 1427 would hope.</p></li> 1428</ul></div> 1429</div> 1430</div> 1431<div class="sect1"> 1432<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1433<a name="mc-manual.monitor-commands"></a>4.6.�Memcheck Monitor Commands</h2></div></div></div> 1434<p>The Memcheck tool provides monitor commands handled by Valgrind's 1435built-in gdbserver (see <a class="xref" href="manual-core-adv.html#manual-core-adv.gdbserver-commandhandling" title="3.2.5.�Monitor command handling by the Valgrind gdbserver">Monitor command handling by the Valgrind gdbserver</a>). 1436</p> 1437<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1438<li class="listitem"> 1439<p><code class="varname">xb <addr> [<len>]</code> 1440 shows the definedness (V) bits and values for <len> (default 1) 1441 bytes starting at <addr>. 1442 For each 8 bytes, two lines are output. 1443 </p> 1444<p> 1445 The first line shows the validity bits for 8 bytes. 1446 The definedness of each byte in the range is given using two hexadecimal 1447 digits. These hexadecimal digits encode the validity of each bit of the 1448 corresponding byte, 1449 using 0 if the bit is defined and 1 if the bit is undefined. 1450 If a byte is not addressable, its validity bits are replaced 1451 by <code class="varname">__</code> (a double underscore). 1452 </p> 1453<p> 1454 The second line shows the values of the bytes below the corresponding 1455 validity bits. The format used to show the bytes data is similar to the 1456 GDB command 'x /<len>xb <addr>'. The value for a non 1457 addressable bytes is shown as ?? (two question marks). 1458 </p> 1459<p> 1460 In the following example, <code class="varname">string10</code> is an array 1461 of 10 characters, in which the even numbered bytes are 1462 undefined. In the below example, the byte corresponding 1463 to <code class="varname">string10[5]</code> is not addressable. 1464 </p> 1465<pre class="programlisting"> 1466(gdb) p &string10 1467$4 = (char (*)[10]) 0x804a2f0 1468(gdb) mo xb 0x804a2f0 10 1469 ff 00 ff 00 ff __ ff 00 14700x804A2F0: 0x3f 0x6e 0x3f 0x65 0x3f 0x?? 0x3f 0x65 1471 ff 00 14720x804A2F8: 0x3f 0x00 1473Address 0x804A2F0 len 10 has 1 bytes unaddressable 1474(gdb) 1475</pre> 1476<p> The command xb cannot be used with registers. To get 1477 the validity bits of a register, you must start Valgrind with the 1478 option <code class="option">--vgdb-shadow-registers=yes</code>. The validity 1479 bits of a register can then be obtained by printing the 'shadow 1' 1480 corresponding register. In the below x86 example, the register 1481 eax has all its bits undefined, while the register ebx is fully 1482 defined. 1483 </p> 1484<pre class="programlisting"> 1485(gdb) p /x $eaxs1 1486$9 = 0xffffffff 1487(gdb) p /x $ebxs1 1488$10 = 0x0 1489(gdb) 1490</pre> 1491</li> 1492<li class="listitem"> 1493<p><code class="varname">get_vbits <addr> [<len>]</code> 1494 shows the definedness (V) bits for <len> (default 1) bytes 1495 starting at <addr> using the same convention as the 1496 <code class="varname">xb</code> command. <code class="varname">get_vbits</code> only 1497 shows the V bits (grouped by 4 bytes). It does not show the values. 1498 If you want to associate V bits with the corresponding byte values, the 1499 <code class="varname">xb</code> command will be easier to use, in particular 1500 on little endian computers when associating undefined parts of an integer 1501 with their V bits values. 1502 </p> 1503<p> 1504 The following example shows the result of <code class="varname">get_vibts</code> 1505 on the <code class="varname">string10</code> used in the <code class="varname">xb</code> 1506 command explanation. 1507 </p> 1508<pre class="programlisting"> 1509(gdb) monitor get_vbits 0x804a2f0 10 1510ff00ff00 ff__ff00 ff00 1511Address 0x804A2F0 len 10 has 1 bytes unaddressable 1512(gdb) 1513</pre> 1514</li> 1515<li class="listitem"> 1516<p><code class="varname">make_memory 1517 [noaccess|undefined|defined|Definedifaddressable] <addr> 1518 [<len>]</code> marks the range of <len> (default 1) 1519 bytes at <addr> as having the given status. Parameter 1520 <code class="varname">noaccess</code> marks the range as non-accessible, so 1521 Memcheck will report an error on any access to it. 1522 <code class="varname">undefined</code> or <code class="varname">defined</code> mark 1523 the area as accessible, but Memcheck regards the bytes in it 1524 respectively as having undefined or defined values. 1525 <code class="varname">Definedifaddressable</code> marks as defined, bytes in 1526 the range which are already addressible, but makes no change to 1527 the status of bytes in the range which are not addressible. Note 1528 that the first letter of <code class="varname">Definedifaddressable</code> 1529 is an uppercase D to avoid confusion with <code class="varname">defined</code>. 1530 </p> 1531<p> 1532 In the following example, the first byte of the 1533 <code class="varname">string10</code> is marked as defined: 1534 </p> 1535<pre class="programlisting"> 1536(gdb) monitor make_memory defined 0x8049e28 1 1537(gdb) monitor get_vbits 0x8049e28 10 15380000ff00 ff00ff00 ff00 1539(gdb) 1540</pre> 1541</li> 1542<li class="listitem"> 1543<p><code class="varname">check_memory [addressable|defined] <addr> 1544 [<len>]</code> checks that the range of <len> 1545 (default 1) bytes at <addr> has the specified accessibility. 1546 It then outputs a description of <addr>. In the following 1547 example, a detailed description is available because the 1548 option <code class="option">--read-var-info=yes</code> was given at Valgrind 1549 startup: 1550 </p> 1551<pre class="programlisting"> 1552(gdb) monitor check_memory defined 0x8049e28 1 1553Address 0x8049E28 len 1 defined 1554==14698== Location 0x8049e28 is 0 bytes inside string10[0], 1555==14698== declared at prog.c:10, in frame #0 of thread 1 1556(gdb) 1557</pre> 1558</li> 1559<li class="listitem"> 1560<p><code class="varname">leak_check [full*|summary|xtleak] 1561 [kinds <set>|reachable|possibleleak*|definiteleak] 1562 [heuristics heur1,heur2,...] 1563 [increased*|changed|any] 1564 [unlimited*|limited <max_loss_records_output>] 1565 </code> 1566 performs a leak check. The <code class="varname">*</code> in the arguments 1567 indicates the default values. </p> 1568<p> If the <code class="varname">[full*|summary|xtleak]</code> argument is 1569 <code class="varname">summary</code>, only a summary of the leak search is given; 1570 otherwise a full leak report is produced. A full leak report gives 1571 detailed information for each leak: the stack trace where the leaked blocks 1572 were allocated, the number of blocks leaked and their total size. When a 1573 full report is requested, the next two arguments further specify what 1574 kind of leaks to report. A leak's details are shown if they match 1575 both the second and third argument. A full leak report might 1576 output detailed information for many leaks. The nr of leaks for 1577 which information is output can be controlled using 1578 the <code class="varname">limited</code> argument followed by the maximum nr 1579 of leak records to output. If this maximum is reached, the leak 1580 search outputs the records with the biggest number of bytes. 1581 </p> 1582<p>The value <code class="varname">xtleak</code> also produces a full leak report, 1583 but output it as an xtree in a file xtleak.kcg.%p.%n (see <a class="xref" href="manual-core.html#opt.log-file">--log-file</a>). 1584 See <a class="xref" href="manual-core.html#manual-core.xtree" title="2.9.�Execution Trees">Execution Trees</a> 1585 for a detailed explanation about execution trees formats. 1586 See <a class="xref" href="mc-manual.html#opt.xtree-leak">--xtree-leak</a> for the description of the events 1587 in a xtree leak file. 1588 </p> 1589<p>The <code class="varname">kinds</code> argument controls what kind of blocks 1590 are shown for a <code class="varname">full</code> leak search. The set of leak kinds 1591 to show can be specified using a <code class="varname"><set></code> similarly 1592 to the command line option <code class="option">--show-leak-kinds</code>. 1593 Alternatively, the value <code class="varname">definiteleak</code> 1594 is equivalent to <code class="varname">kinds definite</code>, the 1595 value <code class="varname">possibleleak</code> is equivalent to 1596 <code class="varname">kinds definite,possible</code> : it will also show 1597 possibly leaked blocks, .i.e those for which only an interior 1598 pointer was found. The value <code class="varname">reachable</code> will 1599 show all block categories (i.e. is equivalent to <code class="varname">kinds 1600 all</code>). 1601 </p> 1602<p>The <code class="varname">heuristics</code> argument controls the heuristics 1603 used during the leak search. The set of heuristics to use can be specified 1604 using a <code class="varname"><set></code> similarly 1605 to the command line option <code class="option">--leak-check-heuristics</code>. 1606 The default value for the <code class="varname">heuristics</code> argument is 1607 <code class="varname">heuristics none</code>. 1608 </p> 1609<p>The <code class="varname">[increased*|changed|any]</code> argument controls what 1610 kinds of changes are shown for a <code class="varname">full</code> leak search. The 1611 value <code class="varname">increased</code> specifies that only block 1612 allocation stacks with an increased number of leaked bytes or 1613 blocks since the previous leak check should be shown. The 1614 value <code class="varname">changed</code> specifies that allocation stacks 1615 with any change since the previous leak check should be shown. 1616 The value <code class="varname">any</code> specifies that all leak entries 1617 should be shown, regardless of any increase or decrease. When 1618 If <code class="varname">increased</code> or <code class="varname">changed</code> are 1619 specified, the leak report entries will show the delta relative to 1620 the previous leak report. 1621 </p> 1622<p>The following example shows usage of the 1623 <code class="varname">leak_check</code> monitor command on 1624 the <code class="varname">memcheck/tests/leak-cases.c</code> regression 1625 test. The first command outputs one entry having an increase in 1626 the leaked bytes. The second command is the same as the first 1627 command, but uses the abbreviated forms accepted by GDB and the 1628 Valgrind gdbserver. It only outputs the summary information, as 1629 there was no increase since the previous leak search.</p> 1630<pre class="programlisting"> 1631(gdb) monitor leak_check full possibleleak increased 1632==19520== 16 (+16) bytes in 1 (+1) blocks are possibly lost in loss record 9 of 12 1633==19520== at 0x40070B4: malloc (vg_replace_malloc.c:263) 1634==19520== by 0x80484D5: mk (leak-cases.c:52) 1635==19520== by 0x804855F: f (leak-cases.c:81) 1636==19520== by 0x80488E0: main (leak-cases.c:107) 1637==19520== 1638==19520== LEAK SUMMARY: 1639==19520== definitely lost: 32 (+0) bytes in 2 (+0) blocks 1640==19520== indirectly lost: 16 (+0) bytes in 1 (+0) blocks 1641==19520== possibly lost: 32 (+16) bytes in 2 (+1) blocks 1642==19520== still reachable: 96 (+16) bytes in 6 (+1) blocks 1643==19520== suppressed: 0 (+0) bytes in 0 (+0) blocks 1644==19520== Reachable blocks (those to which a pointer was found) are not shown. 1645==19520== To see them, add 'reachable any' args to leak_check 1646==19520== 1647(gdb) mo l 1648==19520== LEAK SUMMARY: 1649==19520== definitely lost: 32 (+0) bytes in 2 (+0) blocks 1650==19520== indirectly lost: 16 (+0) bytes in 1 (+0) blocks 1651==19520== possibly lost: 32 (+0) bytes in 2 (+0) blocks 1652==19520== still reachable: 96 (+0) bytes in 6 (+0) blocks 1653==19520== suppressed: 0 (+0) bytes in 0 (+0) blocks 1654==19520== Reachable blocks (those to which a pointer was found) are not shown. 1655==19520== To see them, add 'reachable any' args to leak_check 1656==19520== 1657(gdb) 1658</pre> 1659<p>Note that when using Valgrind's gdbserver, it is not 1660 necessary to rerun 1661 with <code class="option">--leak-check=full</code> 1662 <code class="option">--show-reachable=yes</code> to see the reachable 1663 blocks. You can obtain the same information without rerunning by 1664 using the GDB command <code class="computeroutput">monitor leak_check full 1665 reachable any</code> (or, using 1666 abbreviation: <code class="computeroutput">mo l f r a</code>). 1667 </p> 1668</li> 1669<li class="listitem"> 1670<p><code class="varname">block_list <loss_record_nr>|<loss_record_nr_from>..<loss_record_nr_to> 1671 [unlimited*|limited <max_blocks>] 1672 [heuristics heur1,heur2,...] 1673 </code> 1674 shows the list of blocks belonging to 1675 <code class="varname"><loss_record_nr></code> (or to the loss records range 1676 <code class="varname"><loss_record_nr_from>..<loss_record_nr_to></code>). 1677 The nr of blocks to print can be controlled using the 1678 <code class="varname">limited</code> argument followed by the maximum nr 1679 of blocks to output. 1680 If one or more heuristics are given, only prints the loss records 1681 and blocks found via one of the given <code class="varname">heur1,heur2,...</code> 1682 heuristics. 1683 </p> 1684<p> A leak search merges the allocated blocks in loss records : 1685 a loss record re-groups all blocks having the same state (for 1686 example, Definitely Lost) and the same allocation backtrace. 1687 Each loss record is identified in the leak search result 1688 by a loss record number. 1689 The <code class="varname">block_list</code> command shows the loss record information 1690 followed by the addresses and sizes of the blocks which have been 1691 merged in the loss record. If a block was found using an heuristic, the block size 1692 is followed by the heuristic. 1693 </p> 1694<p> If a directly lost block causes some other blocks to be indirectly 1695 lost, the block_list command will also show these indirectly lost blocks. 1696 The indirectly lost blocks will be indented according to the level of indirection 1697 between the directly lost block and the indirectly lost block(s). 1698 Each indirectly lost block is followed by the reference of its loss record. 1699 </p> 1700<p> The block_list command can be used on the results of a leak search as long 1701 as no block has been freed after this leak search: as soon as the program frees 1702 a block, a new leak search is needed before block_list can be used again. 1703 </p> 1704<p> 1705 In the below example, the program leaks a tree structure by losing the pointer to 1706 the block A (top of the tree). 1707 So, the block A is directly lost, causing an indirect 1708 loss of blocks B to G. The first block_list command shows the loss record of A 1709 (a definitely lost block with address 0x4028028, size 16). The addresses and sizes 1710 of the indirectly lost blocks due to block A are shown below the block A. 1711 The second command shows the details of one of the indirect loss records output 1712 by the first command. 1713 </p> 1714<pre class="programlisting"> 1715 A 1716 / \ 1717 B C 1718 / \ / \ 1719 D E F G 1720</pre> 1721<pre class="programlisting"> 1722(gdb) bt 1723#0 main () at leak-tree.c:69 1724(gdb) monitor leak_check full any 1725==19552== 112 (16 direct, 96 indirect) bytes in 1 blocks are definitely lost in loss record 7 of 7 1726==19552== at 0x40070B4: malloc (vg_replace_malloc.c:263) 1727==19552== by 0x80484D5: mk (leak-tree.c:28) 1728==19552== by 0x80484FC: f (leak-tree.c:41) 1729==19552== by 0x8048856: main (leak-tree.c:63) 1730==19552== 1731==19552== LEAK SUMMARY: 1732==19552== definitely lost: 16 bytes in 1 blocks 1733==19552== indirectly lost: 96 bytes in 6 blocks 1734==19552== possibly lost: 0 bytes in 0 blocks 1735==19552== still reachable: 0 bytes in 0 blocks 1736==19552== suppressed: 0 bytes in 0 blocks 1737==19552== 1738(gdb) monitor block_list 7 1739==19552== 112 (16 direct, 96 indirect) bytes in 1 blocks are definitely lost in loss record 7 of 7 1740==19552== at 0x40070B4: malloc (vg_replace_malloc.c:263) 1741==19552== by 0x80484D5: mk (leak-tree.c:28) 1742==19552== by 0x80484FC: f (leak-tree.c:41) 1743==19552== by 0x8048856: main (leak-tree.c:63) 1744==19552== 0x4028028[16] 1745==19552== 0x4028068[16] indirect loss record 1 1746==19552== 0x40280E8[16] indirect loss record 3 1747==19552== 0x4028128[16] indirect loss record 4 1748==19552== 0x40280A8[16] indirect loss record 2 1749==19552== 0x4028168[16] indirect loss record 5 1750==19552== 0x40281A8[16] indirect loss record 6 1751(gdb) mo b 2 1752==19552== 16 bytes in 1 blocks are indirectly lost in loss record 2 of 7 1753==19552== at 0x40070B4: malloc (vg_replace_malloc.c:263) 1754==19552== by 0x80484D5: mk (leak-tree.c:28) 1755==19552== by 0x8048519: f (leak-tree.c:43) 1756==19552== by 0x8048856: main (leak-tree.c:63) 1757==19552== 0x40280A8[16] 1758==19552== 0x4028168[16] indirect loss record 5 1759==19552== 0x40281A8[16] indirect loss record 6 1760(gdb) 1761 1762</pre> 1763</li> 1764<li class="listitem"> 1765<p><code class="varname">who_points_at <addr> [<len>]</code> 1766 shows all the locations where a pointer to addr is found. 1767 If len is equal to 1, the command only shows the locations pointing 1768 exactly at addr (i.e. the "start pointers" to addr). 1769 If len is > 1, "interior pointers" pointing at the len first bytes 1770 will also be shown. 1771 </p> 1772<p>The locations searched for are the same as the locations 1773 used in the leak search. So, <code class="varname">who_points_at</code> can a.o. 1774 be used to show why the leak search still can reach a block, or can 1775 search for dangling pointers to a freed block. 1776 Each location pointing at addr (or pointing inside addr if interior pointers 1777 are being searched for) will be described. 1778 </p> 1779<p>In the below example, the pointers to the 'tree block A' (see example 1780 in command <code class="varname">block_list</code>) is shown before the tree was leaked. 1781 The descriptions are detailed as the option <code class="option">--read-var-info=yes</code> 1782 was given at Valgrind startup. The second call shows the pointers (start and interior 1783 pointers) to block G. The block G (0x40281A8) is reachable via block C (0x40280a8) 1784 and register ECX of tid 1 (tid is the Valgrind thread id). 1785 It is "interior reachable" via the register EBX. 1786 </p> 1787<pre class="programlisting"> 1788(gdb) monitor who_points_at 0x4028028 1789==20852== Searching for pointers to 0x4028028 1790==20852== *0x8049e20 points at 0x4028028 1791==20852== Location 0x8049e20 is 0 bytes inside global var "t" 1792==20852== declared at leak-tree.c:35 1793(gdb) monitor who_points_at 0x40281A8 16 1794==20852== Searching for pointers pointing in 16 bytes from 0x40281a8 1795==20852== *0x40280ac points at 0x40281a8 1796==20852== Address 0x40280ac is 4 bytes inside a block of size 16 alloc'd 1797==20852== at 0x40070B4: malloc (vg_replace_malloc.c:263) 1798==20852== by 0x80484D5: mk (leak-tree.c:28) 1799==20852== by 0x8048519: f (leak-tree.c:43) 1800==20852== by 0x8048856: main (leak-tree.c:63) 1801==20852== tid 1 register ECX points at 0x40281a8 1802==20852== tid 1 register EBX interior points at 2 bytes inside 0x40281a8 1803(gdb) 1804</pre> 1805<p> When <code class="varname">who_points_at</code> finds an interior pointer, 1806 it will report the heuristic(s) with which this interior pointer 1807 will be considered as reachable. Note that this is done independently 1808 of the value of the option <code class="option">--leak-check-heuristics</code>. 1809 In the below example, the loss record 6 indicates a possibly lost 1810 block. <code class="varname">who_points_at</code> reports that there is an interior 1811 pointer pointing in this block, and that the block can be considered 1812 reachable using the heuristic 1813 <code class="computeroutput">multipleinheritance</code>. 1814 </p> 1815<pre class="programlisting"> 1816(gdb) monitor block_list 6 1817==3748== 8 bytes in 1 blocks are possibly lost in loss record 6 of 7 1818==3748== at 0x4007D77: operator new(unsigned int) (vg_replace_malloc.c:313) 1819==3748== by 0x8048954: main (leak_cpp_interior.cpp:43) 1820==3748== 0x402A0E0[8] 1821(gdb) monitor who_points_at 0x402A0E0 8 1822==3748== Searching for pointers pointing in 8 bytes from 0x402a0e0 1823==3748== *0xbe8ee078 interior points at 4 bytes inside 0x402a0e0 1824==3748== Address 0xbe8ee078 is on thread 1's stack 1825==3748== block at 0x402a0e0 considered reachable by ptr 0x402a0e4 using multipleinheritance heuristic 1826(gdb) 1827</pre> 1828</li> 1829</ul></div> 1830</div> 1831<div class="sect1"> 1832<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1833<a name="mc-manual.clientreqs"></a>4.7.�Client Requests</h2></div></div></div> 1834<p>The following client requests are defined in 1835<code class="filename">memcheck.h</code>. 1836See <code class="filename">memcheck.h</code> for exact details of their 1837arguments.</p> 1838<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1839<li class="listitem"><p><code class="varname">VALGRIND_MAKE_MEM_NOACCESS</code>, 1840 <code class="varname">VALGRIND_MAKE_MEM_UNDEFINED</code> and 1841 <code class="varname">VALGRIND_MAKE_MEM_DEFINED</code>. 1842 These mark address ranges as completely inaccessible, 1843 accessible but containing undefined data, and accessible and 1844 containing defined data, respectively. They return -1, when 1845 run on Valgrind and 0 otherwise.</p></li> 1846<li class="listitem"><p><code class="varname">VALGRIND_MAKE_MEM_DEFINED_IF_ADDRESSABLE</code>. 1847 This is just like <code class="varname">VALGRIND_MAKE_MEM_DEFINED</code> but only 1848 affects those bytes that are already addressable.</p></li> 1849<li class="listitem"><p><code class="varname">VALGRIND_CHECK_MEM_IS_ADDRESSABLE</code> and 1850 <code class="varname">VALGRIND_CHECK_MEM_IS_DEFINED</code>: check immediately 1851 whether or not the given address range has the relevant property, 1852 and if not, print an error message. Also, for the convenience of 1853 the client, returns zero if the relevant property holds; otherwise, 1854 the returned value is the address of the first byte for which the 1855 property is not true. Always returns 0 when not run on 1856 Valgrind.</p></li> 1857<li class="listitem"><p><code class="varname">VALGRIND_CHECK_VALUE_IS_DEFINED</code>: a quick and easy 1858 way to find out whether Valgrind thinks a particular value 1859 (lvalue, to be precise) is addressable and defined. Prints an error 1860 message if not. It has no return value.</p></li> 1861<li class="listitem"><p><code class="varname">VALGRIND_DO_LEAK_CHECK</code>: does a full memory leak 1862 check (like <code class="option">--leak-check=full</code>) right now. 1863 This is useful for incrementally checking for leaks between arbitrary 1864 places in the program's execution. It has no return value.</p></li> 1865<li class="listitem"><p><code class="varname">VALGRIND_DO_ADDED_LEAK_CHECK</code>: same as 1866 <code class="varname"> VALGRIND_DO_LEAK_CHECK</code> but only shows the 1867 entries for which there was an increase in leaked bytes or leaked 1868 number of blocks since the previous leak search. It has no return 1869 value.</p></li> 1870<li class="listitem"><p><code class="varname">VALGRIND_DO_CHANGED_LEAK_CHECK</code>: same as 1871 <code class="varname">VALGRIND_DO_LEAK_CHECK</code> but only shows the 1872 entries for which there was an increase or decrease in leaked 1873 bytes or leaked number of blocks since the previous leak search. It 1874 has no return value.</p></li> 1875<li class="listitem"><p><code class="varname">VALGRIND_DO_QUICK_LEAK_CHECK</code>: like 1876 <code class="varname">VALGRIND_DO_LEAK_CHECK</code>, except it produces only a leak 1877 summary (like <code class="option">--leak-check=summary</code>). 1878 It has no return value.</p></li> 1879<li class="listitem"><p><code class="varname">VALGRIND_COUNT_LEAKS</code>: fills in the four 1880 arguments with the number of bytes of memory found by the previous 1881 leak check to be leaked (i.e. the sum of direct leaks and indirect leaks), 1882 dubious, reachable and suppressed. This is useful in test harness code, 1883 after calling <code class="varname">VALGRIND_DO_LEAK_CHECK</code> or 1884 <code class="varname">VALGRIND_DO_QUICK_LEAK_CHECK</code>.</p></li> 1885<li class="listitem"><p><code class="varname">VALGRIND_COUNT_LEAK_BLOCKS</code>: identical to 1886 <code class="varname">VALGRIND_COUNT_LEAKS</code> except that it returns the 1887 number of blocks rather than the number of bytes in each 1888 category.</p></li> 1889<li class="listitem"><p><code class="varname">VALGRIND_GET_VBITS</code> and 1890 <code class="varname">VALGRIND_SET_VBITS</code>: allow you to get and set the 1891 V (validity) bits for an address range. You should probably only 1892 set V bits that you have got with 1893 <code class="varname">VALGRIND_GET_VBITS</code>. Only for those who really 1894 know what they are doing.</p></li> 1895<li class="listitem"> 1896<p><code class="varname">VALGRIND_CREATE_BLOCK</code> and 1897 <code class="varname">VALGRIND_DISCARD</code>. <code class="varname">VALGRIND_CREATE_BLOCK</code> 1898 takes an address, a number of bytes and a character string. The 1899 specified address range is then associated with that string. When 1900 Memcheck reports an invalid access to an address in the range, it 1901 will describe it in terms of this block rather than in terms of 1902 any other block it knows about. Note that the use of this macro 1903 does not actually change the state of memory in any way -- it 1904 merely gives a name for the range. 1905 </p> 1906<p>At some point you may want Memcheck to stop reporting errors 1907 in terms of the block named 1908 by <code class="varname">VALGRIND_CREATE_BLOCK</code>. To make this 1909 possible, <code class="varname">VALGRIND_CREATE_BLOCK</code> returns a 1910 "block handle", which is a C <code class="varname">int</code> value. You 1911 can pass this block handle to <code class="varname">VALGRIND_DISCARD</code>. 1912 After doing so, Valgrind will no longer relate addressing errors 1913 in the specified range to the block. Passing invalid handles to 1914 <code class="varname">VALGRIND_DISCARD</code> is harmless. 1915 </p> 1916</li> 1917</ul></div> 1918</div> 1919<div class="sect1"> 1920<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 1921<a name="mc-manual.mempools"></a>4.8.�Memory Pools: describing and working with custom allocators</h2></div></div></div> 1922<p>Some programs use custom memory allocators, often for performance 1923reasons. Left to itself, Memcheck is unable to understand the 1924behaviour of custom allocation schemes as well as it understands the 1925standard allocators, and so may miss errors and leaks in your program. What 1926this section describes is a way to give Memcheck enough of a description of 1927your custom allocator that it can make at least some sense of what is 1928happening.</p> 1929<p>There are many different sorts of custom allocator, so Memcheck 1930attempts to reason about them using a loose, abstract model. We 1931use the following terminology when describing custom allocation 1932systems:</p> 1933<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1934<li class="listitem"><p>Custom allocation involves a set of independent "memory pools". 1935 </p></li> 1936<li class="listitem"><p>Memcheck's notion of a a memory pool consists of a single "anchor 1937 address" and a set of non-overlapping "chunks" associated with the 1938 anchor address.</p></li> 1939<li class="listitem"><p>Typically a pool's anchor address is the address of a 1940 book-keeping "header" structure.</p></li> 1941<li class="listitem"><p>Typically the pool's chunks are drawn from a contiguous 1942 "superblock" acquired through the system 1943 <code class="function">malloc</code> or 1944 <code class="function">mmap</code>.</p></li> 1945</ul></div> 1946<p>Keep in mind that the last two points above say "typically": the 1947Valgrind mempool client request API is intentionally vague about the 1948exact structure of a mempool. There is no specific mention made of 1949headers or superblocks. Nevertheless, the following picture may help 1950elucidate the intention of the terms in the API:</p> 1951<pre class="programlisting"> 1952 "pool" 1953 (anchor address) 1954 | 1955 v 1956 +--------+---+ 1957 | header | o | 1958 +--------+-|-+ 1959 | 1960 v superblock 1961 +------+---+--------------+---+------------------+ 1962 | |rzB| allocation |rzB| | 1963 +------+---+--------------+---+------------------+ 1964 ^ ^ 1965 | | 1966 "addr" "addr"+"size" 1967</pre> 1968<p> 1969Note that the header and the superblock may be contiguous or 1970discontiguous, and there may be multiple superblocks associated with a 1971single header; such variations are opaque to Memcheck. The API 1972only requires that your allocation scheme can present sensible values 1973of "pool", "addr" and "size".</p> 1974<p> 1975Typically, before making client requests related to mempools, a client 1976program will have allocated such a header and superblock for their 1977mempool, and marked the superblock NOACCESS using the 1978<code class="varname">VALGRIND_MAKE_MEM_NOACCESS</code> client request.</p> 1979<p> 1980When dealing with mempools, the goal is to maintain a particular 1981invariant condition: that Memcheck believes the unallocated portions 1982of the pool's superblock (including redzones) are NOACCESS. To 1983maintain this invariant, the client program must ensure that the 1984superblock starts out in that state; Memcheck cannot make it so, since 1985Memcheck never explicitly learns about the superblock of a pool, only 1986the allocated chunks within the pool.</p> 1987<p> 1988Once the header and superblock for a pool are established and properly 1989marked, there are a number of client requests programs can use to 1990inform Memcheck about changes to the state of a mempool:</p> 1991<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 1992<li class="listitem"> 1993<p> 1994 <code class="varname">VALGRIND_CREATE_MEMPOOL(pool, rzB, is_zeroed)</code>: 1995 This request registers the address <code class="varname">pool</code> as the anchor 1996 address for a memory pool. It also provides a size 1997 <code class="varname">rzB</code>, specifying how large the redzones placed around 1998 chunks allocated from the pool should be. Finally, it provides an 1999 <code class="varname">is_zeroed</code> argument that specifies whether the pool's 2000 chunks are zeroed (more precisely: defined) when allocated. 2001 </p> 2002<p> 2003 Upon completion of this request, no chunks are associated with the 2004 pool. The request simply tells Memcheck that the pool exists, so that 2005 subsequent calls can refer to it as a pool. 2006 </p> 2007</li> 2008<li class="listitem"> 2009<p> 2010 <code class="varname">VALGRIND_CREATE_MEMPOOL_EXT(pool, rzB, is_zeroed, flags)</code>: 2011 Create a memory pool with some flags (that can 2012 be OR-ed together) specifying extended behaviour. When flags is 2013 zero, the behaviour is identical to 2014 <code class="varname">VALGRIND_CREATE_MEMPOOL</code>.</p> 2015<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> 2016<li class="listitem"><p> The flag <code class="varname">VALGRIND_MEMPOOL_METAPOOL</code> 2017 specifies that the pieces of memory associated with the pool 2018 using <code class="varname">VALGRIND_MEMPOOL_ALLOC</code> will be used 2019 by the application as superblocks to dole out MALLOC_LIKE 2020 blocks using <code class="varname">VALGRIND_MALLOCLIKE_BLOCK</code>. 2021 In other words, a meta pool is a "2 levels" pool : first 2022 level is the blocks described 2023 by <code class="varname">VALGRIND_MEMPOOL_ALLOC</code>. The second 2024 level blocks are described 2025 using <code class="varname">VALGRIND_MALLOCLIKE_BLOCK</code>. Note 2026 that the association between the pool and the second level 2027 blocks is implicit : second level blocks will be located 2028 inside first level blocks. It is necessary to use 2029 the <code class="varname">VALGRIND_MEMPOOL_METAPOOL</code> flag for 2030 such 2 levels pools, as otherwise valgrind will detect 2031 overlapping memory blocks, and will abort execution 2032 (e.g. during leak search). 2033 </p></li> 2034<li class="listitem"><p> 2035 <code class="varname">VALGRIND_MEMPOOL_AUTO_FREE</code>. Such a meta 2036 pool can also be marked as an 'auto free' pool using the 2037 flag <code class="varname">VALGRIND_MEMPOOL_AUTO_FREE</code>, which 2038 must be OR-ed together with 2039 the <code class="varname">VALGRIND_MEMPOOL_METAPOOL</code>. For an 2040 'auto free' pool, <code class="varname">VALGRIND_MEMPOOL_FREE</code> 2041 will automatically free the second level blocks that are 2042 contained inside the first level block freed 2043 with <code class="varname">VALGRIND_MEMPOOL_FREE</code>. In other 2044 words, calling <code class="varname">VALGRIND_MEMPOOL_FREE</code> will 2045 cause implicit calls 2046 to <code class="varname">VALGRIND_FREELIKE_BLOCK</code> for all the 2047 second level blocks included in the first level block. 2048 Note: it is an error to use 2049 the <code class="varname">VALGRIND_MEMPOOL_AUTO_FREE</code> flag 2050 without the 2051 <code class="varname">VALGRIND_MEMPOOL_METAPOOL</code> flag. 2052 </p></li> 2053</ul></div> 2054</li> 2055<li class="listitem"><p><code class="varname">VALGRIND_DESTROY_MEMPOOL(pool)</code>: 2056 This request tells Memcheck that a pool is being torn down. Memcheck 2057 then removes all records of chunks associated with the pool, as well 2058 as its record of the pool's existence. While destroying its records of 2059 a mempool, Memcheck resets the redzones of any live chunks in the pool 2060 to NOACCESS. 2061 </p></li> 2062<li class="listitem"><p><code class="varname">VALGRIND_MEMPOOL_ALLOC(pool, addr, size)</code>: 2063 This request informs Memcheck that a <code class="varname">size</code>-byte chunk 2064 has been allocated at <code class="varname">addr</code>, and associates the chunk with the 2065 specified 2066 <code class="varname">pool</code>. If the pool was created with nonzero 2067 <code class="varname">rzB</code> redzones, Memcheck will mark the 2068 <code class="varname">rzB</code> bytes before and after the chunk as NOACCESS. If 2069 the pool was created with the <code class="varname">is_zeroed</code> argument set, 2070 Memcheck will mark the chunk as DEFINED, otherwise Memcheck will mark 2071 the chunk as UNDEFINED. 2072 </p></li> 2073<li class="listitem"><p><code class="varname">VALGRIND_MEMPOOL_FREE(pool, addr)</code>: 2074 This request informs Memcheck that the chunk at <code class="varname">addr</code> 2075 should no longer be considered allocated. Memcheck will mark the chunk 2076 associated with <code class="varname">addr</code> as NOACCESS, and delete its 2077 record of the chunk's existence. 2078 </p></li> 2079<li class="listitem"> 2080<p><code class="varname">VALGRIND_MEMPOOL_TRIM(pool, addr, size)</code>: 2081 This request trims the chunks associated with <code class="varname">pool</code>. 2082 The request only operates on chunks associated with 2083 <code class="varname">pool</code>. Trimming is formally defined as:</p> 2084<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> 2085<li class="listitem"><p> All chunks entirely inside the range 2086 <code class="varname">addr..(addr+size-1)</code> are preserved.</p></li> 2087<li class="listitem"><p>All chunks entirely outside the range 2088 <code class="varname">addr..(addr+size-1)</code> are discarded, as though 2089 <code class="varname">VALGRIND_MEMPOOL_FREE</code> was called on them. </p></li> 2090<li class="listitem"><p>All other chunks must intersect with the range 2091 <code class="varname">addr..(addr+size-1)</code>; areas outside the 2092 intersection are marked as NOACCESS, as though they had been 2093 independently freed with 2094 <code class="varname">VALGRIND_MEMPOOL_FREE</code>.</p></li> 2095</ul></div> 2096<p>This is a somewhat rare request, but can be useful in 2097 implementing the type of mass-free operations common in custom 2098 LIFO allocators.</p> 2099</li> 2100<li class="listitem"> 2101<p><code class="varname">VALGRIND_MOVE_MEMPOOL(poolA, poolB)</code>: This 2102 request informs Memcheck that the pool previously anchored at 2103 address <code class="varname">poolA</code> has moved to anchor address 2104 <code class="varname">poolB</code>. This is a rare request, typically only needed 2105 if you <code class="function">realloc</code> the header of a mempool.</p> 2106<p>No memory-status bits are altered by this request.</p> 2107</li> 2108<li class="listitem"> 2109<p> 2110 <code class="varname">VALGRIND_MEMPOOL_CHANGE(pool, addrA, addrB, 2111 size)</code>: This request informs Memcheck that the chunk 2112 previously allocated at address <code class="varname">addrA</code> within 2113 <code class="varname">pool</code> has been moved and/or resized, and should be 2114 changed to cover the region <code class="varname">addrB..(addrB+size-1)</code>. This 2115 is a rare request, typically only needed if you 2116 <code class="function">realloc</code> a superblock or wish to extend a chunk 2117 without changing its memory-status bits. 2118 </p> 2119<p>No memory-status bits are altered by this request. 2120 </p> 2121</li> 2122<li class="listitem"><p><code class="varname">VALGRIND_MEMPOOL_EXISTS(pool)</code>: 2123 This request informs the caller whether or not Memcheck is currently 2124 tracking a mempool at anchor address <code class="varname">pool</code>. It 2125 evaluates to 1 when there is a mempool associated with that address, 0 2126 otherwise. This is a rare request, only useful in circumstances when 2127 client code might have lost track of the set of active mempools. 2128 </p></li> 2129</ul></div> 2130</div> 2131<div class="sect1"> 2132<div class="titlepage"><div><div><h2 class="title" style="clear: both"> 2133<a name="mc-manual.mpiwrap"></a>4.9.�Debugging MPI Parallel Programs with Valgrind</h2></div></div></div> 2134<p>Memcheck supports debugging of distributed-memory applications 2135which use the MPI message passing standard. This support consists of a 2136library of wrapper functions for the 2137<code class="computeroutput">PMPI_*</code> interface. When incorporated 2138into the application's address space, either by direct linking or by 2139<code class="computeroutput">LD_PRELOAD</code>, the wrappers intercept 2140calls to <code class="computeroutput">PMPI_Send</code>, 2141<code class="computeroutput">PMPI_Recv</code>, etc. They then 2142use client requests to inform Memcheck of memory state changes caused 2143by the function being wrapped. This reduces the number of false 2144positives that Memcheck otherwise typically reports for MPI 2145applications.</p> 2146<p>The wrappers also take the opportunity to carefully check 2147size and definedness of buffers passed as arguments to MPI functions, hence 2148detecting errors such as passing undefined data to 2149<code class="computeroutput">PMPI_Send</code>, or receiving data into a 2150buffer which is too small.</p> 2151<p>Unlike most of the rest of Valgrind, the wrapper library is subject to a 2152BSD-style license, so you can link it into any code base you like. 2153See the top of <code class="computeroutput">mpi/libmpiwrap.c</code> 2154for license details.</p> 2155<div class="sect2"> 2156<div class="titlepage"><div><div><h3 class="title"> 2157<a name="mc-manual.mpiwrap.build"></a>4.9.1.�Building and installing the wrappers</h3></div></div></div> 2158<p> The wrapper library will be built automatically if possible. 2159Valgrind's configure script will look for a suitable 2160<code class="computeroutput">mpicc</code> to build it with. This must be 2161the same <code class="computeroutput">mpicc</code> you use to build the 2162MPI application you want to debug. By default, Valgrind tries 2163<code class="computeroutput">mpicc</code>, but you can specify a 2164different one by using the configure-time option 2165<code class="option">--with-mpicc</code>. Currently the 2166wrappers are only buildable with 2167<code class="computeroutput">mpicc</code>s which are based on GNU 2168GCC or Intel's C++ Compiler.</p> 2169<p>Check that the configure script prints a line like this:</p> 2170<pre class="programlisting"> 2171checking for usable MPI2-compliant mpicc and mpi.h... yes, mpicc 2172</pre> 2173<p>If it says <code class="computeroutput">... no</code>, your 2174<code class="computeroutput">mpicc</code> has failed to compile and link 2175a test MPI2 program.</p> 2176<p>If the configure test succeeds, continue in the usual way with 2177<code class="computeroutput">make</code> and <code class="computeroutput">make 2178install</code>. The final install tree should then contain 2179<code class="computeroutput">libmpiwrap-<platform>.so</code>. 2180</p> 2181<p>Compile up a test MPI program (eg, MPI hello-world) and try 2182this:</p> 2183<pre class="programlisting"> 2184LD_PRELOAD=$prefix/lib/valgrind/libmpiwrap-<platform>.so \ 2185 mpirun [args] $prefix/bin/valgrind ./hello 2186</pre> 2187<p>You should see something similar to the following</p> 2188<pre class="programlisting"> 2189valgrind MPI wrappers 31901: Active for pid 31901 2190valgrind MPI wrappers 31901: Try MPIWRAP_DEBUG=help for possible options 2191</pre> 2192<p>repeated for every process in the group. If you do not see 2193these, there is an build/installation problem of some kind.</p> 2194<p> The MPI functions to be wrapped are assumed to be in an ELF 2195shared object with soname matching 2196<code class="computeroutput">libmpi.so*</code>. This is known to be 2197correct at least for Open MPI and Quadrics MPI, and can easily be 2198changed if required.</p> 2199</div> 2200<div class="sect2"> 2201<div class="titlepage"><div><div><h3 class="title"> 2202<a name="mc-manual.mpiwrap.gettingstarted"></a>4.9.2.�Getting started</h3></div></div></div> 2203<p>Compile your MPI application as usual, taking care to link it 2204using the same <code class="computeroutput">mpicc</code> that your 2205Valgrind build was configured with.</p> 2206<p> 2207Use the following basic scheme to run your application on Valgrind with 2208the wrappers engaged:</p> 2209<pre class="programlisting"> 2210MPIWRAP_DEBUG=[wrapper-args] \ 2211 LD_PRELOAD=$prefix/lib/valgrind/libmpiwrap-<platform>.so \ 2212 mpirun [mpirun-args] \ 2213 $prefix/bin/valgrind [valgrind-args] \ 2214 [application] [app-args] 2215</pre> 2216<p>As an alternative to 2217<code class="computeroutput">LD_PRELOAD</code>ing 2218<code class="computeroutput">libmpiwrap-<platform>.so</code>, you can 2219simply link it to your application if desired. This should not disturb 2220native behaviour of your application in any way.</p> 2221</div> 2222<div class="sect2"> 2223<div class="titlepage"><div><div><h3 class="title"> 2224<a name="mc-manual.mpiwrap.controlling"></a>4.9.3.�Controlling the wrapper library</h3></div></div></div> 2225<p>Environment variable 2226<code class="computeroutput">MPIWRAP_DEBUG</code> is consulted at 2227startup. The default behaviour is to print a starting banner</p> 2228<pre class="programlisting"> 2229valgrind MPI wrappers 16386: Active for pid 16386 2230valgrind MPI wrappers 16386: Try MPIWRAP_DEBUG=help for possible options 2231</pre> 2232<p> and then be relatively quiet.</p> 2233<p>You can give a list of comma-separated options in 2234<code class="computeroutput">MPIWRAP_DEBUG</code>. These are</p> 2235<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 2236<li class="listitem"><p><code class="computeroutput">verbose</code>: 2237 show entries/exits of all wrappers. Also show extra 2238 debugging info, such as the status of outstanding 2239 <code class="computeroutput">MPI_Request</code>s resulting 2240 from uncompleted <code class="computeroutput">MPI_Irecv</code>s.</p></li> 2241<li class="listitem"><p><code class="computeroutput">quiet</code>: 2242 opposite of <code class="computeroutput">verbose</code>, only print 2243 anything when the wrappers want 2244 to report a detected programming error, or in case of catastrophic 2245 failure of the wrappers.</p></li> 2246<li class="listitem"><p><code class="computeroutput">warn</code>: 2247 by default, functions which lack proper wrappers 2248 are not commented on, just silently 2249 ignored. This causes a warning to be printed for each unwrapped 2250 function used, up to a maximum of three warnings per function.</p></li> 2251<li class="listitem"><p><code class="computeroutput">strict</code>: 2252 print an error message and abort the program if 2253 a function lacking a wrapper is used.</p></li> 2254</ul></div> 2255<p> If you want to use Valgrind's XML output facility 2256(<code class="option">--xml=yes</code>), you should pass 2257<code class="computeroutput">quiet</code> in 2258<code class="computeroutput">MPIWRAP_DEBUG</code> so as to get rid of any 2259extraneous printing from the wrappers.</p> 2260</div> 2261<div class="sect2"> 2262<div class="titlepage"><div><div><h3 class="title"> 2263<a name="mc-manual.mpiwrap.limitations.functions"></a>4.9.4.�Functions</h3></div></div></div> 2264<p>All MPI2 functions except 2265<code class="computeroutput">MPI_Wtick</code>, 2266<code class="computeroutput">MPI_Wtime</code> and 2267<code class="computeroutput">MPI_Pcontrol</code> have wrappers. The 2268first two are not wrapped because they return a 2269<code class="computeroutput">double</code>, which Valgrind's 2270function-wrap mechanism cannot handle (but it could easily be 2271extended to do so). <code class="computeroutput">MPI_Pcontrol</code> cannot be 2272wrapped as it has variable arity: 2273<code class="computeroutput">int MPI_Pcontrol(const int level, ...)</code></p> 2274<p>Most functions are wrapped with a default wrapper which does 2275nothing except complain or abort if it is called, depending on 2276settings in <code class="computeroutput">MPIWRAP_DEBUG</code> listed 2277above. The following functions have "real", do-something-useful 2278wrappers:</p> 2279<pre class="programlisting"> 2280PMPI_Send PMPI_Bsend PMPI_Ssend PMPI_Rsend 2281 2282PMPI_Recv PMPI_Get_count 2283 2284PMPI_Isend PMPI_Ibsend PMPI_Issend PMPI_Irsend 2285 2286PMPI_Irecv 2287PMPI_Wait PMPI_Waitall 2288PMPI_Test PMPI_Testall 2289 2290PMPI_Iprobe PMPI_Probe 2291 2292PMPI_Cancel 2293 2294PMPI_Sendrecv 2295 2296PMPI_Type_commit PMPI_Type_free 2297 2298PMPI_Pack PMPI_Unpack 2299 2300PMPI_Bcast PMPI_Gather PMPI_Scatter PMPI_Alltoall 2301PMPI_Reduce PMPI_Allreduce PMPI_Op_create 2302 2303PMPI_Comm_create PMPI_Comm_dup PMPI_Comm_free PMPI_Comm_rank PMPI_Comm_size 2304 2305PMPI_Error_string 2306PMPI_Init PMPI_Initialized PMPI_Finalize 2307</pre> 2308<p> A few functions such as 2309<code class="computeroutput">PMPI_Address</code> are listed as 2310<code class="computeroutput">HAS_NO_WRAPPER</code>. They have no wrapper 2311at all as there is nothing worth checking, and giving a no-op wrapper 2312would reduce performance for no reason.</p> 2313<p> Note that the wrapper library itself can itself generate large 2314numbers of calls to the MPI implementation, especially when walking 2315complex types. The most common functions called are 2316<code class="computeroutput">PMPI_Extent</code>, 2317<code class="computeroutput">PMPI_Type_get_envelope</code>, 2318<code class="computeroutput">PMPI_Type_get_contents</code>, and 2319<code class="computeroutput">PMPI_Type_free</code>. </p> 2320</div> 2321<div class="sect2"> 2322<div class="titlepage"><div><div><h3 class="title"> 2323<a name="mc-manual.mpiwrap.limitations.types"></a>4.9.5.�Types</h3></div></div></div> 2324<p> MPI-1.1 structured types are supported, and walked exactly. 2325The currently supported combiners are 2326<code class="computeroutput">MPI_COMBINER_NAMED</code>, 2327<code class="computeroutput">MPI_COMBINER_CONTIGUOUS</code>, 2328<code class="computeroutput">MPI_COMBINER_VECTOR</code>, 2329<code class="computeroutput">MPI_COMBINER_HVECTOR</code> 2330<code class="computeroutput">MPI_COMBINER_INDEXED</code>, 2331<code class="computeroutput">MPI_COMBINER_HINDEXED</code> and 2332<code class="computeroutput">MPI_COMBINER_STRUCT</code>. This should 2333cover all MPI-1.1 types. The mechanism (function 2334<code class="computeroutput">walk_type</code>) should extend easily to 2335cover MPI2 combiners.</p> 2336<p>MPI defines some named structured types 2337(<code class="computeroutput">MPI_FLOAT_INT</code>, 2338<code class="computeroutput">MPI_DOUBLE_INT</code>, 2339<code class="computeroutput">MPI_LONG_INT</code>, 2340<code class="computeroutput">MPI_2INT</code>, 2341<code class="computeroutput">MPI_SHORT_INT</code>, 2342<code class="computeroutput">MPI_LONG_DOUBLE_INT</code>) which are pairs 2343of some basic type and a C <code class="computeroutput">int</code>. 2344Unfortunately the MPI specification makes it impossible to look inside 2345these types and see where the fields are. Therefore these wrappers 2346assume the types are laid out as <code class="computeroutput">struct { float val; 2347int loc; }</code> (for 2348<code class="computeroutput">MPI_FLOAT_INT</code>), etc, and act 2349accordingly. This appears to be correct at least for Open MPI 1.0.2 2350and for Quadrics MPI.</p> 2351<p>If <code class="computeroutput">strict</code> is an option specified 2352in <code class="computeroutput">MPIWRAP_DEBUG</code>, the application 2353will abort if an unhandled type is encountered. Otherwise, the 2354application will print a warning message and continue.</p> 2355<p>Some effort is made to mark/check memory ranges corresponding to 2356arrays of values in a single pass. This is important for performance 2357since asking Valgrind to mark/check any range, no matter how small, 2358carries quite a large constant cost. This optimisation is applied to 2359arrays of primitive types (<code class="computeroutput">double</code>, 2360<code class="computeroutput">float</code>, 2361<code class="computeroutput">int</code>, 2362<code class="computeroutput">long</code>, <code class="computeroutput">long 2363long</code>, <code class="computeroutput">short</code>, 2364<code class="computeroutput">char</code>, and <code class="computeroutput">long 2365double</code> on platforms where <code class="computeroutput">sizeof(long 2366double) == 8</code>). For arrays of all other types, the 2367wrappers handle each element individually and so there can be a very 2368large performance cost.</p> 2369</div> 2370<div class="sect2"> 2371<div class="titlepage"><div><div><h3 class="title"> 2372<a name="mc-manual.mpiwrap.writingwrappers"></a>4.9.6.�Writing new wrappers</h3></div></div></div> 2373<p> 2374For the most part the wrappers are straightforward. The only 2375significant complexity arises with nonblocking receives.</p> 2376<p>The issue is that <code class="computeroutput">MPI_Irecv</code> 2377states the recv buffer and returns immediately, giving a handle 2378(<code class="computeroutput">MPI_Request</code>) for the transaction. 2379Later the user will have to poll for completion with 2380<code class="computeroutput">MPI_Wait</code> etc, and when the 2381transaction completes successfully, the wrappers have to paint the 2382recv buffer. But the recv buffer details are not presented to 2383<code class="computeroutput">MPI_Wait</code> -- only the handle is. The 2384library therefore maintains a shadow table which associates 2385uncompleted <code class="computeroutput">MPI_Request</code>s with the 2386corresponding buffer address/count/type. When an operation completes, 2387the table is searched for the associated address/count/type info, and 2388memory is marked accordingly.</p> 2389<p>Access to the table is guarded by a (POSIX pthreads) lock, so as 2390to make the library thread-safe.</p> 2391<p>The table is allocated with 2392<code class="computeroutput">malloc</code> and never 2393<code class="computeroutput">free</code>d, so it will show up in leak 2394checks.</p> 2395<p>Writing new wrappers should be fairly easy. The source file is 2396<code class="computeroutput">mpi/libmpiwrap.c</code>. If possible, 2397find an existing wrapper for a function of similar behaviour to the 2398one you want to wrap, and use it as a starting point. The wrappers 2399are organised in sections in the same order as the MPI 1.1 spec, to 2400aid navigation. When adding a wrapper, remember to comment out the 2401definition of the default wrapper in the long list of defaults at the 2402bottom of the file (do not remove it, just comment it out).</p> 2403</div> 2404<div class="sect2"> 2405<div class="titlepage"><div><div><h3 class="title"> 2406<a name="mc-manual.mpiwrap.whattoexpect"></a>4.9.7.�What to expect when using the wrappers</h3></div></div></div> 2407<p>The wrappers should reduce Memcheck's false-error rate on MPI 2408applications. Because the wrapping is done at the MPI interface, 2409there will still potentially be a large number of errors reported in 2410the MPI implementation below the interface. The best you can do is 2411try to suppress them.</p> 2412<p>You may also find that the input-side (buffer 2413length/definedness) checks find errors in your MPI use, for example 2414passing too short a buffer to 2415<code class="computeroutput">MPI_Recv</code>.</p> 2416<p>Functions which are not wrapped may increase the false 2417error rate. A possible approach is to run with 2418<code class="computeroutput">MPI_DEBUG</code> containing 2419<code class="computeroutput">warn</code>. This will show you functions 2420which lack proper wrappers but which are nevertheless used. You can 2421then write wrappers for them. 2422</p> 2423<p>A known source of potential false errors are the 2424<code class="computeroutput">PMPI_Reduce</code> family of functions, when 2425using a custom (user-defined) reduction function. In a reduction 2426operation, each node notionally sends data to a "central point" which 2427uses the specified reduction function to merge the data items into a 2428single item. Hence, in general, data is passed between nodes and fed 2429to the reduction function, but the wrapper library cannot mark the 2430transferred data as initialised before it is handed to the reduction 2431function, because all that happens "inside" the 2432<code class="computeroutput">PMPI_Reduce</code> call. As a result you 2433may see false positives reported in your reduction function.</p> 2434</div> 2435</div> 2436</div> 2437<div> 2438<br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer"> 2439<tr> 2440<td rowspan="2" width="40%" align="left"> 2441<a accesskey="p" href="manual-core-adv.html"><<�3.�Using and understanding the Valgrind core: Advanced Topics</a>�</td> 2442<td width="20%" align="center"><a accesskey="u" href="manual.html">Up</a></td> 2443<td rowspan="2" width="40%" align="right">�<a accesskey="n" href="cg-manual.html">5.�Cachegrind: a cache and branch-prediction profiler�>></a> 2444</td> 2445</tr> 2446<tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr> 2447</table> 2448</div> 2449</body> 2450</html> 2451
