Home | History | Annotate | Download | only in html
      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
     35 function</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>
     64 on the Valgrind command line.  You don't have to, though, since Memcheck
     65 is 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
     70 problems 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,
     92 often 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
    103 quick summary of what error messages mean.  The precise behaviour of the
    104 error-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">
    110 Invalid 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
    118 which Memcheck reckons it shouldn't.  In this example, the program did a
    119 4-byte read at address 0xBFFFF0E0, somewhere within the system-supplied
    120 library libpng.so.2.1.0.9, which was called from somewhere else in the
    121 same library, called from line 326 of <code class="filename">qpngio.cpp</code>,
    122 and so on.</p>
    123 <p>Memcheck tries to establish what the illegal address might relate
    124 to, since that's often useful.  So, if it points into a block of memory
    125 which has already been freed, you'll be informed of this, and also where
    126 the block was freed.  Likewise, if it should turn out to be just off
    127 the end of a heap block, a common result of off-by-one-errors in
    128 array subscripting, you'll be informed of this fact, and also where the
    129 block 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
    130 but may give a more detailed description of any illegal address.</p>
    131 <p>In this example, Memcheck can't identify the address.  Actually
    132 the address is on the stack, but, for some reason, this is not a valid
    133 stack address -- it is below the stack pointer and that isn't allowed.
    134 In this particular case it's probably caused by GCC generating invalid
    135 code, a known bug in some ancient versions of GCC.</p>
    136 <p>Note that Memcheck only tells you that your program is about to
    137 access memory at an illegal address.  It can't stop the access from
    138 happening.  So, if your program makes an access which normally would
    139 result in a segmentation fault, you program will still suffer the same
    140 fate -- but you will get a message from Memcheck immediately prior to
    141 this.  In this particular example, reading junk on the stack is
    142 non-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">
    149 Conditional 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
    155 uses a value which hasn't been initialised -- in other words, is
    156 undefined.  Here, the undefined value is used somewhere inside the
    157 <code class="function">printf</code> machinery of the C library.  This error was
    158 reported when running the following small program:</p>
    159 <pre class="programlisting">
    160 int 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
    166 junk (uninitialised) data as much as it likes.  Memcheck observes this
    167 and keeps track of the data, but does not complain.  A complaint is
    168 issued only when your program attempts to make use of uninitialised
    169 data in a way that might affect your program's externally-visible behaviour.
    170 In this example, <code class="varname">x</code> is uninitialised.  Memcheck observes
    171 the 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,
    175 and 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
    186 program, use the <code class="option">--track-origins=yes</code> option.  This
    187 makes Memcheck run more slowly, but can make it much easier to track down
    188 the 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
    208 precisely reflect any changes in memory state caused by the system
    209 call.</p>
    210 <p>Here's an example of two system calls with invalid parameters:</p>
    211 <pre class="programlisting">
    212   #include &lt;stdlib.h&gt;
    213   #include &lt;unistd.h&gt;
    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
    237 from the heap block to the standard output, and (b) passed an
    238 uninitialised value to <code class="function">exit</code>.  Note that the first
    239 error 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
    242 refers 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">
    250 Invalid 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
    258 with <code class="function">malloc</code>/<code class="computeroutput">new</code>,
    259 so it can know exactly whether or not the argument to
    260 <code class="function">free</code>/<code class="computeroutput">delete</code> is
    261 legitimate or not.  Here, this test program has freed the same block
    262 twice.  As with the illegal read/write errors, Memcheck attempts to
    263 make sense of the address freed.  If, as here, the address is one
    264 which has previously been freed, you wil be told that -- making
    265 duplicate frees of the same block easy to spot.  You will also get this
    266 message if you try to free a pointer that doesn't point to the start of a
    267 heap 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
    272 function</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">
    277 Mismatched 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 &amp;) (olefilter.cc:272)
    287 </pre>
    288 <p>In <code class="literal">C++</code> it's important to deallocate memory in a
    289 way 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
    304 you do mix these up, but the same program may then crash on a
    305 different platform, Solaris for example.  So it's best to fix it
    306 properly.  According to the KDE folks "it's amazing how many C++
    307 programmers don't know this".</p>
    308 <p>The reason behind the requirement is as follows.  In some C++
    309 implementations, <code class="function">delete[]</code> must be used for
    310 objects allocated by <code class="function">new[]</code> because the compiler
    311 stores the size of the array and the pointer-to-member to the
    312 destructor of the array's content just before the pointer actually
    313 returned.  <code class="function">delete</code> doesn't account for this and will get
    314 confused, 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
    320 memory 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>. 
    326 The blocks pointed to by their <code class="computeroutput">src</code> and
    327 <code class="computeroutput">dst</code> pointers aren't allowed to overlap.
    328 The POSIX standards have wording along the lines "If copying takes place
    329 between objects that overlap, the behavior is undefined." Therefore,
    330 Memcheck 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
    339 get partially overwritten by the copying.</p>
    340 <p>You might think that Memcheck is being overly pedantic reporting
    341 this in the case where <code class="computeroutput">dst</code> is less than
    342 <code class="computeroutput">src</code>.  For example, the obvious way to
    343 implement <code class="function">memcpy</code> is by copying from the first
    344 byte to the last.  However, the optimisation guides of some
    345 architectures recommend copying from the last byte down to the first.
    346 Also, some implementations of <code class="function">memcpy</code> zero
    347 <code class="computeroutput">dst</code> before copying, because zeroing the
    348 destination's cache line(s) can improve performance.</p>
    349 <p>The moral of the story is: if you want to write truly portable
    350 code, don't make any assumptions about the language
    351 implementation.</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
    357 size of the memory block that should be allocated. Clearly, the requested
    358 size should be a non-negative value and is typically not excessively large. 
    359 For instance, it is extremely unlikly that the size of an allocation
    360 request exceeds 2**63 bytes on a 64-bit machine. It is much more likely that
    361 such a value is the result of an erroneous size calculation and is in effect
    362 a negative value (that just happens to appear excessively large because
    363 the bit pattern is interpreted as an unsigned integer).
    364 Such a value is called a "fishy value".
    365 
    366 The <code class="varname">size</code> argument of the following allocation functions
    367 is 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>,
    376 For <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
    386 as "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
    393 calls to
    394 <code class="function">malloc</code>/<code class="function">new</code> et al.
    395 So 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
    398 remaining block, Memcheck determines if the block is reachable from pointers
    399 within the root-set.  The root-set consists of (a) general purpose registers
    400 of all threads, and (b) initialised, aligned, pointer-sized data words in
    401 accessible 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
    404 an "interior-pointer", i.e. a pointer to the middle of the block.  There are
    405 several 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
    435 search to detect the interior pointers corresponding to
    436 the <code class="computeroutput">stdstring</code>,
    437 <code class="computeroutput">length64</code>,
    438 <code class="computeroutput">newarray</code>
    439 and <code class="computeroutput">multipleinheritance</code> cases. If the
    440 heuristic detects that an interior pointer corresponds to such a case,
    441 the block will be considered as reachable by the interior
    442 pointer. In other words, the interior pointer will be treated
    443 as if it were a start pointer.</p>
    444 <p>With that in mind, consider the nine possible cases described by the
    445 following figure.</p>
    446 <pre class="programlisting">
    447      Pointer chain            AAA Leak Case   BBB Leak Case
    448      -------------            -------------   -------------
    449 (1)  RRR ------------&gt; BBB                    DR
    450 (2)  RRR ---&gt; AAA ---&gt; BBB    DR              IR
    451 (3)  RRR               BBB                    DL
    452 (4)  RRR      AAA ---&gt; BBB    DL              IL
    453 (5)  RRR ------?-----&gt; BBB                    (y)DR, (n)DL
    454 (6)  RRR ---&gt; AAA -?-&gt; BBB    DR              (y)IR, (n)DL
    455 (7)  RRR -?-&gt; AAA ---&gt; BBB    (y)DR, (n)DL    (y)IR, (n)IL
    456 (8)  RRR -?-&gt; AAA -?-&gt; BBB    (y)DR, (n)DL    (y,y)IR, (n,y)IL, (_,n)DL
    457 (9)  RRR      AAA -?-&gt; BBB    DL              (y)IL, (n)DL
    458 
    459 Pointer chain legend:
    460 - RRR: a root set node or DR block
    461 - AAA, BBB: heap blocks
    462 - ---&gt;: a start-pointer
    463 - -?-&gt;: an interior-pointer
    464 
    465 Leak 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
    475 merges some of these cases in its output, resulting in the following four
    476 leak 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
    506 not necessarily the best way that leaks could be reported;  in particular,
    507 interior-pointers are treated inconsistently.  It is possible the
    508 categorisation may be improved in the future.)</p>
    509 <p>Furthermore, if suppressions exists for a block, it will be reported
    510 as "suppressed" no matter what which of the above four kinds it belongs
    511 to.</p>
    512 <p>The following is an example leak summary.</p>
    513 <pre class="programlisting">
    514 LEAK 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
    522 reachable, the leak summary details the heuristically reachable subset
    523 of 'still reachable:' per heuristic. In the below example, of the 95
    524 bytes still reachable, 87 bytes (56+7+8+16) have been considered
    525 heuristically reachable.
    526 </p>
    527 <pre class="programlisting">
    528 LEAK 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,
    541 Memcheck will give details for each definitely lost or possibly lost block,
    542 including where it was allocated.  (Actually, it merges results for all
    543 blocks that have the same leak kind and sufficiently similar stack traces
    544 into a single "loss record".  The
    545 <code class="option">--leak-resolution</code> lets you control the
    546 meaning of "sufficiently similar".)  It cannot tell you when or how or why
    547 the pointer to a leaked block was lost; you have to work that out for
    548 yourself.  In general, you should attempt to ensure your programs do not
    549 have any definitely lost or possibly lost blocks at exit.</p>
    550 <p>For example:</p>
    551 <pre class="programlisting">
    552 8 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 
    557 88 (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
    563 that has been definitely lost.  The second case mentions another 8 byte
    564 block that has been definitely lost;  the difference is that a further 80
    565 bytes in other blocks are indirectly lost because of this lost block.
    566 The loss records are not presented in any notable order, so the loss record
    567 numbers aren't particularly meaningful. The loss record numbers can be used
    568 in the Valgrind gdbserver to list the addresses of the leaked blocks and/or give
    569 more details about how a block is still reachable.</p>
    570 <p>The option <code class="option">--show-leak-kinds=&lt;set&gt;</code>
    571 controls the set of leak kinds to show
    572 when <code class="option">--leak-check=full</code> is specified. </p>
    573 <p>The <code class="option">&lt;set&gt;</code> of leak kinds is specified
    574 in 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
    590 addition to the definitely and possibly lost blocks, you can
    591 use <code class="option">--show-leak-kinds=all</code>.  To only show the
    592 reachable and indirectly lost blocks, use
    593 <code class="option">--show-leak-kinds=indirect,reachable</code>.  The reachable
    594 and indirectly lost blocks will then be presented as shown in
    595 the following two examples.</p>
    596 <pre class="programlisting">
    597 64 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 
    602 32 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
    608 severities, an interesting question is: which leaks should be
    609 counted as true "errors" and which should not?
    610 </p>
    611 <p> The answer to this question affects the numbers printed in
    612 the <code class="computeroutput">ERROR SUMMARY</code> line, and also the
    613 effect of the <code class="option">--error-exitcode</code> option.  First, a leak
    614 is only counted as a true "error"
    615 if <code class="option">--leak-check=full</code> is specified.  Then, the
    616 option <code class="option">--errors-for-leak-kinds=&lt;set&gt;</code> controls
    617 the set of leak kinds to consider as errors.  The default value
    618 is <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=&lt;no|summary|yes|full&gt; [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=&lt;low|med|high&gt; [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=&lt;set&gt; [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=&lt;set&gt; [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">&lt;set&gt;</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=&lt;set&gt; [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=&lt;yes|no&gt; </code>
    710     , </span><span class="term">
    711       <code class="option">--show-possibly-lost=&lt;yes|no&gt; </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=&lt;no|yes&gt; [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=&lt;filename&gt; [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=&lt;yes|no&gt; [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=&lt;yes|no&gt; [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=&lt;yes|no&gt; [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=&lt;yes|no&gt; [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=&lt;number&gt; [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=&lt;number&gt; [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=&lt;yes|no&gt; [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=&lt;number&gt;-&lt;number&gt; </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=&lt;yes|no&gt; [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=&lt;hexnumber&gt; </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=&lt;hexnumber&gt; </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">
   1105 Memcheck: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
   1139 information line at this point, which is the name of the offending
   1140 system call parameter. </p>
   1141 <p><code class="computeroutput">Leak</code> errors have an optional
   1142 extra information line, with the following format:</p>
   1143 <pre class="programlisting">
   1144 match-leak-kinds:&lt;set&gt;</pre>
   1145 <p>where <code class="computeroutput">&lt;set&gt;</code> specifies which
   1146 leak kinds are matched by this suppression entry. 
   1147 <code class="computeroutput">&lt;set&gt;</code> is specified in the
   1148 same way as with the option <code class="option">--show-leak-kinds</code>, that is,
   1149 one 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
   1162 entry 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
   1165 line, and therefore may match fewer leaks than you expect.  You may
   1166 want to remove the line before using the generated
   1167 suppressions.</p>
   1168 <p>The other Memcheck error kinds do not have extra lines.</p>
   1169 <p>
   1170 If you give the <code class="option">-v</code> option, Valgrind will print
   1171 the list of used suppressions at the end of execution.
   1172 For a leak suppression, this output gives the number of different
   1173 loss records that match the suppression, and the number of bytes
   1174 and blocks suppressed by the suppression.
   1175 If the run contains multiple leak checks, the number of bytes and blocks
   1176 are reset to zero before each new leak check. Note that the number of different
   1177 loss records is not reset to zero.</p>
   1178 <p>In the example below, in the last leak search, 7 blocks and 96 bytes have
   1179 been 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>
   1186 errors, the first line of the calling context is either the name of
   1187 the function in which the error occurred, or, failing that, the full
   1188 path of the <code class="filename">.so</code> file or executable containing the
   1189 error location.  For <code class="varname">Free</code> errors, the first line is
   1190 the name of the function doing the freeing (eg,
   1191 <code class="function">free</code>, <code class="function">__builtin_vec_delete</code>,
   1192 etc).  For <code class="varname">Overlap</code> errors, the first line is the name of the
   1193 function 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
   1196 calling 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
   1202 what 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
   1207 which is identical to a real CPU, except for one crucial detail.  Every
   1208 bit (literally) of data processed, stored and handled by the real CPU
   1209 has, in the synthetic CPU, an associated "valid-value" bit, which says
   1210 whether or not the accompanying bit has a legitimate value.  In the
   1211 discussions which follow, this bit is referred to as the V (valid-value)
   1212 bit.</p>
   1213 <p>Each byte in the system therefore has a 8 V bits which follow it
   1214 wherever it goes.  For example, when the CPU loads a word-size item (4
   1215 bytes) from memory, it also loads the corresponding 32 V bits from a
   1216 bitmap which stores the V bits for the process' entire address space.
   1217 If the CPU should later write the whole or some part of that value to
   1218 memory at a different address, the relevant V bits will be stored back
   1219 in the V-bit bitmap.</p>
   1220 <p>In short, each bit in the system has (conceptually) an associated V
   1221 bit, which follows it around everywhere, even inside the CPU.  Yes, all the
   1222 CPU's registers (integer, floating point, vector and condition registers)
   1223 have their own V bit vectors.  For this to work, Memcheck uses a great deal
   1224 of compression to represent the V bits compactly.</p>
   1225 <p>Copying values around does not cause Memcheck to check for, or
   1226 report on, errors.  However, when a value is used in a way which might
   1227 conceivably affect your program's externally-visible behaviour,
   1228 the associated V bits are immediately checked.  If any of these indicate
   1229 that the value is undefined (even partially), an error is reported.</p>
   1230 <p>Here's an (admittedly nonsensical) example:</p>
   1231 <pre class="programlisting">
   1232 int i, j;
   1233 int a[10], b[10];
   1234 for ( i = 0; i &lt; 10; i++ ) {
   1235   j = a[i];
   1236   b[i] = j;
   1237 }</pre>
   1238 <p>Memcheck emits no complaints about this, since it merely copies
   1239 uninitialised values from <code class="varname">a[]</code> into
   1240 <code class="varname">b[]</code>, and doesn't use them in a way which could
   1241 affect the behaviour of the program.  However, if
   1242 the loop is changed to:</p>
   1243 <pre class="programlisting">
   1244 for ( i = 0; i &lt; 10; i++ ) {
   1245   j += a[i];
   1246 }
   1247 if ( 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
   1252 uninitialised values.  Note that it <span class="command"><strong>doesn't</strong></span> complain
   1253 at the <code class="varname">j += a[i];</code>, since at that point the
   1254 undefinedness is not "observable".  It's only when a decision has to be
   1255 made as to whether or not to do the <code class="function">printf</code> -- an
   1256 observable action of your program -- that Memcheck complains.</p>
   1257 <p>Most low level operations, such as adds, cause Memcheck to use the
   1258 V bits for the operands to calculate the V bits for the result.  Even if
   1259 the result is partially or wholly undefined, it does not
   1260 complain.</p>
   1261 <p>Checks on definedness only occur in three places: when a value is
   1262 used to generate a memory address, when control flow decision needs to
   1263 be made, and when a system call is detected, Memcheck checks definedness
   1264 of parameters as required.</p>
   1265 <p>If a check should detect undefinedness, an error message is
   1266 issued.  The resulting value is subsequently regarded as well-defined.
   1267 To do otherwise would give long chains of error messages.  In other
   1268 words, once Memcheck reports an undefined value error, it tries to
   1269 avoid reporting further errors derived from that same undefined
   1270 value.</p>
   1271 <p>This sounds overcomplicated.  Why not just check all reads from
   1272 memory, and complain if an undefined value is loaded into a CPU
   1273 register?  Well, that doesn't work well, because perfectly legitimate C
   1274 programs routinely copy uninitialised values around in memory, and we
   1275 don't want endless complaints about that.  Here's the canonical example.
   1276 Consider a struct like this:</p>
   1277 <pre class="programlisting">
   1278 struct S { int x; char c; };
   1279 struct S s1, s2;
   1280 s1.x = 42;
   1281 s1.c = 'z';
   1282 s2 = s1;
   1283 </pre>
   1284 <p>The question to ask is: how large is <code class="varname">struct S</code>,
   1285 in 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
   1287 S</code> occupies 5 bytes?  Wrong.  All non-toy compilers we know
   1288 of will round the size of <code class="varname">struct S</code> up to a whole
   1289 number of words, in this case 8 bytes.  Not doing this forces compilers
   1290 to 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
   1293 be initialised.  For the assignment <code class="varname">s2 = s1</code>, GCC
   1294 generates code to copy all 8 bytes wholesale into <code class="varname">s2</code>
   1295 without regard for their meaning.  If Memcheck simply checked values as
   1296 they came out of memory, it would yelp every time a structure assignment
   1297 like this happened.  So the more complicated behaviour described above
   1298 is necessary.  This allows GCC to copy
   1299 <code class="varname">s1</code> into <code class="varname">s2</code> any way it likes, and a
   1300 warning will only be emitted if the uninitialised values are later
   1301 used.</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
   1307 values is established and maintained without having to say whether the
   1308 program does or does not have the right to access any particular memory
   1309 location.  We now consider the latter question.</p>
   1310 <p>As described above, every bit in memory or in the CPU has an
   1311 associated valid-value (V) bit.  In addition, all bytes in memory, but
   1312 not in the CPU, have an associated valid-address (A) bit.  This
   1313 indicates whether or not the program can legitimately read or write that
   1314 location.  It does not give any indication of the validity of the data
   1315 at that location -- that's the job of the V bits -- only whether or not
   1316 the location may be accessed.</p>
   1317 <p>Every time your program reads or writes memory, Memcheck checks
   1318 the A bits associated with the address.  If any of them indicate an
   1319 invalid address, an error is emitted.  Note that the reads and writes
   1320 themselves 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
   1354 follows:</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
   1404 is:</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
   1435 built-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 &lt;addr&gt; [&lt;len&gt;]</code>
   1440       shows the definedness (V) bits and values for &lt;len&gt; (default 1)
   1441       bytes starting at &lt;addr&gt;.
   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 /&lt;len&gt;xb &lt;addr&gt;'. 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 &amp;string10
   1467 $4 = (char (*)[10]) 0x804a2f0
   1468 (gdb) mo xb 0x804a2f0 10
   1469                   ff      00      ff      00      ff      __      ff      00
   1470 0x804A2F0:      0x3f    0x6e    0x3f    0x65    0x3f    0x??     0x3f    0x65
   1471                   ff      00
   1472 0x804A2F8:      0x3f    0x00
   1473 Address 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 &lt;addr&gt; [&lt;len&gt;]</code>
   1494     shows the definedness (V) bits for &lt;len&gt; (default 1) bytes
   1495     starting at &lt;addr&gt; 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
   1510 ff00ff00 ff__ff00 ff00
   1511 Address 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] &lt;addr&gt;
   1518     [&lt;len&gt;]</code> marks the range of &lt;len&gt; (default 1)
   1519     bytes at &lt;addr&gt; 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
   1538 0000ff00 ff00ff00 ff00
   1539 (gdb) 
   1540 </pre>
   1541 </li>
   1542 <li class="listitem">
   1543 <p><code class="varname">check_memory [addressable|defined] &lt;addr&gt;
   1544     [&lt;len&gt;]</code> checks that the range of &lt;len&gt;
   1545     (default 1) bytes at &lt;addr&gt; has the specified accessibility.
   1546     It then outputs a description of &lt;addr&gt;. 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
   1553 Address 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 &lt;set&gt;|reachable|possibleleak*|definiteleak]
   1562                               [heuristics heur1,heur2,...]
   1563                               [increased*|changed|any]
   1564                               [unlimited*|limited &lt;max_loss_records_output&gt;]
   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">&lt;set&gt;</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">&lt;set&gt;</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 &lt;loss_record_nr&gt;|&lt;loss_record_nr_from&gt;..&lt;loss_record_nr_to&gt;
   1671         [unlimited*|limited &lt;max_blocks&gt;]
   1672         [heuristics heur1,heur2,...]
   1673       </code>
   1674       shows the list of blocks belonging to
   1675       <code class="varname">&lt;loss_record_nr&gt;</code> (or to the loss records range
   1676       <code class="varname">&lt;loss_record_nr_from&gt;..&lt;loss_record_nr_to&gt;</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 &lt;addr&gt; [&lt;len&gt;]</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 &gt; 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>.
   1836 See <code class="filename">memcheck.h</code> for exact details of their
   1837 arguments.</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
   1923 reasons.  Left to itself, Memcheck is unable to understand the
   1924 behaviour of custom allocation schemes as well as it understands the
   1925 standard allocators, and so may miss errors and leaks in your program.  What
   1926 this section describes is a way to give Memcheck enough of a description of
   1927 your custom allocator that it can make at least some sense of what is
   1928 happening.</p>
   1929 <p>There are many different sorts of custom allocator, so Memcheck
   1930 attempts to reason about them using a loose, abstract model.  We
   1931 use the following terminology when describing custom allocation
   1932 systems:</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
   1947 Valgrind mempool client request API is intentionally vague about the
   1948 exact structure of a mempool. There is no specific mention made of
   1949 headers or superblocks. Nevertheless, the following picture may help
   1950 elucidate 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>
   1969 Note that the header and the superblock may be contiguous or
   1970 discontiguous, and there may be multiple superblocks associated with a
   1971 single header; such variations are opaque to Memcheck. The API
   1972 only requires that your allocation scheme can present sensible values
   1973 of "pool", "addr" and "size".</p>
   1974 <p>
   1975 Typically, before making client requests related to mempools, a client
   1976 program will have allocated such a header and superblock for their
   1977 mempool, and marked the superblock NOACCESS using the
   1978 <code class="varname">VALGRIND_MAKE_MEM_NOACCESS</code> client request.</p>
   1979 <p>
   1980 When dealing with mempools, the goal is to maintain a particular
   1981 invariant condition: that Memcheck believes the unallocated portions
   1982 of the pool's superblock (including redzones) are NOACCESS. To
   1983 maintain this invariant, the client program must ensure that the
   1984 superblock starts out in that state; Memcheck cannot make it so, since
   1985 Memcheck never explicitly learns about the superblock of a pool, only
   1986 the allocated chunks within the pool.</p>
   1987 <p>
   1988 Once the header and superblock for a pool are established and properly
   1989 marked, there are a number of client requests programs can use to
   1990 inform 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
   2135 which use the MPI message passing standard.  This support consists of a
   2136 library of wrapper functions for the
   2137 <code class="computeroutput">PMPI_*</code> interface.  When incorporated
   2138 into the application's address space, either by direct linking or by
   2139 <code class="computeroutput">LD_PRELOAD</code>, the wrappers intercept
   2140 calls to <code class="computeroutput">PMPI_Send</code>,
   2141 <code class="computeroutput">PMPI_Recv</code>, etc.  They then
   2142 use client requests to inform Memcheck of memory state changes caused
   2143 by the function being wrapped.  This reduces the number of false
   2144 positives that Memcheck otherwise typically reports for MPI
   2145 applications.</p>
   2146 <p>The wrappers also take the opportunity to carefully check
   2147 size and definedness of buffers passed as arguments to MPI functions, hence
   2148 detecting errors such as passing undefined data to
   2149 <code class="computeroutput">PMPI_Send</code>, or receiving data into a
   2150 buffer which is too small.</p>
   2151 <p>Unlike most of the rest of Valgrind, the wrapper library is subject to a
   2152 BSD-style license, so you can link it into any code base you like.
   2153 See the top of <code class="computeroutput">mpi/libmpiwrap.c</code>
   2154 for 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.
   2159 Valgrind's configure script will look for a suitable
   2160 <code class="computeroutput">mpicc</code> to build it with.  This must be
   2161 the same <code class="computeroutput">mpicc</code> you use to build the
   2162 MPI application you want to debug.  By default, Valgrind tries
   2163 <code class="computeroutput">mpicc</code>, but you can specify a
   2164 different one by using the configure-time option
   2165 <code class="option">--with-mpicc</code>.  Currently the
   2166 wrappers are only buildable with
   2167 <code class="computeroutput">mpicc</code>s which are based on GNU
   2168 GCC or Intel's C++ Compiler.</p>
   2169 <p>Check that the configure script prints a line like this:</p>
   2170 <pre class="programlisting">
   2171 checking 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
   2175 a 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
   2178 install</code>.  The final install tree should then contain
   2179 <code class="computeroutput">libmpiwrap-&lt;platform&gt;.so</code>.
   2180 </p>
   2181 <p>Compile up a test MPI program (eg, MPI hello-world) and try
   2182 this:</p>
   2183 <pre class="programlisting">
   2184 LD_PRELOAD=$prefix/lib/valgrind/libmpiwrap-&lt;platform&gt;.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">
   2189 valgrind MPI wrappers 31901: Active for pid 31901
   2190 valgrind 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
   2193 these, 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
   2195 shared object with soname matching
   2196 <code class="computeroutput">libmpi.so*</code>.  This is known to be
   2197 correct at least for Open MPI and Quadrics MPI, and can easily be
   2198 changed 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
   2204 using the same <code class="computeroutput">mpicc</code> that your
   2205 Valgrind build was configured with.</p>
   2206 <p>
   2207 Use the following basic scheme to run your application on Valgrind with
   2208 the wrappers engaged:</p>
   2209 <pre class="programlisting">
   2210 MPIWRAP_DEBUG=[wrapper-args]                                  \
   2211    LD_PRELOAD=$prefix/lib/valgrind/libmpiwrap-&lt;platform&gt;.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-&lt;platform&gt;.so</code>, you can
   2219 simply link it to your application if desired.  This should not disturb
   2220 native 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
   2227 startup.  The default behaviour is to print a starting banner</p>
   2228 <pre class="programlisting">
   2229 valgrind MPI wrappers 16386: Active for pid 16386
   2230 valgrind 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
   2259 extraneous 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
   2268 first two are not wrapped because they return a 
   2269 <code class="computeroutput">double</code>, which Valgrind's
   2270 function-wrap mechanism cannot handle (but it could easily be
   2271 extended to do so).  <code class="computeroutput">MPI_Pcontrol</code> cannot be
   2272 wrapped 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
   2275 nothing except complain or abort if it is called, depending on
   2276 settings in <code class="computeroutput">MPIWRAP_DEBUG</code> listed
   2277 above.  The following functions have "real", do-something-useful
   2278 wrappers:</p>
   2279 <pre class="programlisting">
   2280 PMPI_Send PMPI_Bsend PMPI_Ssend PMPI_Rsend
   2281 
   2282 PMPI_Recv PMPI_Get_count
   2283 
   2284 PMPI_Isend PMPI_Ibsend PMPI_Issend PMPI_Irsend
   2285 
   2286 PMPI_Irecv
   2287 PMPI_Wait PMPI_Waitall
   2288 PMPI_Test PMPI_Testall
   2289 
   2290 PMPI_Iprobe PMPI_Probe
   2291 
   2292 PMPI_Cancel
   2293 
   2294 PMPI_Sendrecv
   2295 
   2296 PMPI_Type_commit PMPI_Type_free
   2297 
   2298 PMPI_Pack PMPI_Unpack
   2299 
   2300 PMPI_Bcast PMPI_Gather PMPI_Scatter PMPI_Alltoall
   2301 PMPI_Reduce PMPI_Allreduce PMPI_Op_create
   2302 
   2303 PMPI_Comm_create PMPI_Comm_dup PMPI_Comm_free PMPI_Comm_rank PMPI_Comm_size
   2304 
   2305 PMPI_Error_string
   2306 PMPI_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
   2311 at all as there is nothing worth checking, and giving a no-op wrapper
   2312 would reduce performance for no reason.</p>
   2313 <p> Note that the wrapper library itself can itself generate large
   2314 numbers of calls to the MPI implementation, especially when walking
   2315 complex 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.
   2325 The 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
   2333 cover all MPI-1.1 types.  The mechanism (function
   2334 <code class="computeroutput">walk_type</code>) should extend easily to
   2335 cover 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
   2343 of some basic type and a C <code class="computeroutput">int</code>.
   2344 Unfortunately the MPI specification makes it impossible to look inside
   2345 these types and see where the fields are.  Therefore these wrappers
   2346 assume the types are laid out as <code class="computeroutput">struct { float val;
   2347 int loc; }</code> (for
   2348 <code class="computeroutput">MPI_FLOAT_INT</code>), etc, and act
   2349 accordingly.  This appears to be correct at least for Open MPI 1.0.2
   2350 and for Quadrics MPI.</p>
   2351 <p>If <code class="computeroutput">strict</code> is an option specified 
   2352 in <code class="computeroutput">MPIWRAP_DEBUG</code>, the application
   2353 will abort if an unhandled type is encountered.  Otherwise, the 
   2354 application will print a warning message and continue.</p>
   2355 <p>Some effort is made to mark/check memory ranges corresponding to
   2356 arrays of values in a single pass.  This is important for performance
   2357 since asking Valgrind to mark/check any range, no matter how small,
   2358 carries quite a large constant cost.  This optimisation is applied to
   2359 arrays 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
   2363 long</code>, <code class="computeroutput">short</code>,
   2364 <code class="computeroutput">char</code>, and <code class="computeroutput">long
   2365 double</code> on platforms where <code class="computeroutput">sizeof(long
   2366 double) == 8</code>).  For arrays of all other types, the
   2367 wrappers handle each element individually and so there can be a very
   2368 large 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>
   2374 For the most part the wrappers are straightforward.  The only
   2375 significant complexity arises with nonblocking receives.</p>
   2376 <p>The issue is that <code class="computeroutput">MPI_Irecv</code>
   2377 states the recv buffer and returns immediately, giving a handle
   2378 (<code class="computeroutput">MPI_Request</code>) for the transaction.
   2379 Later the user will have to poll for completion with
   2380 <code class="computeroutput">MPI_Wait</code> etc, and when the
   2381 transaction completes successfully, the wrappers have to paint the
   2382 recv buffer.  But the recv buffer details are not presented to
   2383 <code class="computeroutput">MPI_Wait</code> -- only the handle is.  The
   2384 library therefore maintains a shadow table which associates
   2385 uncompleted <code class="computeroutput">MPI_Request</code>s with the
   2386 corresponding buffer address/count/type.  When an operation completes,
   2387 the table is searched for the associated address/count/type info, and
   2388 memory is marked accordingly.</p>
   2389 <p>Access to the table is guarded by a (POSIX pthreads) lock, so as
   2390 to 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
   2394 checks.</p>
   2395 <p>Writing new wrappers should be fairly easy.  The source file is
   2396 <code class="computeroutput">mpi/libmpiwrap.c</code>.  If possible,
   2397 find an existing wrapper for a function of similar behaviour to the
   2398 one you want to wrap, and use it as a starting point.  The wrappers
   2399 are organised in sections in the same order as the MPI 1.1 spec, to
   2400 aid navigation.  When adding a wrapper, remember to comment out the
   2401 definition of the default wrapper in the long list of defaults at the
   2402 bottom 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
   2408 applications.  Because the wrapping is done at the MPI interface,
   2409 there will still potentially be a large number of errors reported in
   2410 the MPI implementation below the interface.  The best you can do is
   2411 try to suppress them.</p>
   2412 <p>You may also find that the input-side (buffer
   2413 length/definedness) checks find errors in your MPI use, for example
   2414 passing too short a buffer to
   2415 <code class="computeroutput">MPI_Recv</code>.</p>
   2416 <p>Functions which are not wrapped may increase the false
   2417 error 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
   2420 which lack proper wrappers but which are nevertheless used.  You can
   2421 then 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
   2425 using a custom (user-defined) reduction function.  In a reduction
   2426 operation, each node notionally sends data to a "central point" which
   2427 uses the specified reduction function to merge the data items into a
   2428 single item.  Hence, in general, data is passed between nodes and fed
   2429 to the reduction function, but the wrapper library cannot mark the
   2430 transferred data as initialised before it is handed to the reduction
   2431 function, because all that happens "inside" the
   2432 <code class="computeroutput">PMPI_Reduce</code> call.  As a result you
   2433 may 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">&lt;&lt;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&gt;&gt;</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