1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
4<title>4.�Memcheck: a memory error detector</title>
5<link rel="stylesheet" type="text/css" href="vg_basic.css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
7<link rel="home" href="index.html" title="Valgrind Documentation">
8<link rel="up" href="manual.html" title="Valgrind User Manual">
9<link rel="prev" href="manual-core-adv.html" title="3.�Using and understanding the Valgrind core: Advanced Topics">
10<link rel="next" href="cg-manual.html" title="5.�Cachegrind: a cache and branch-prediction profiler">
11</head>
12<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13<div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr>
14<td width="22px" align="center" valign="middle"><a accesskey="p" href="manual-core-adv.html"><img src="images/prev.png" width="18" height="21" border="0" alt="Prev"></a></td>
15<td width="25px" align="center" valign="middle"><a accesskey="u" href="manual.html"><img src="images/up.png" width="21" height="18" border="0" alt="Up"></a></td>
16<td width="31px" align="center" valign="middle"><a accesskey="h" href="index.html"><img src="images/home.png" width="27" height="20" border="0" alt="Up"></a></td>
17<th align="center" valign="middle">Valgrind User Manual</th>
18<td width="22px" align="center" valign="middle"><a accesskey="n" href="cg-manual.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td>
19</tr></table></div>
20<div class="chapter">
21<div class="titlepage"><div><div><h1 class="title">
22<a name="mc-manual"></a>4.�Memcheck: a memory error detector</h1></div></div></div>
23<div class="toc">
24<p><b>Table of Contents</b></p>
25<dl class="toc">
26<dt><span class="sect1"><a href="mc-manual.html#mc-manual.overview">4.1. Overview</a></span></dt>
27<dt><span class="sect1"><a href="mc-manual.html#mc-manual.errormsgs">4.2. Explanation of error messages from Memcheck</a></span></dt>
28<dd><dl>
29<dt><span class="sect2"><a href="mc-manual.html#mc-manual.badrw">4.2.1. Illegal read / Illegal write errors</a></span></dt>
30<dt><span class="sect2"><a href="mc-manual.html#mc-manual.uninitvals">4.2.2. Use of uninitialised values</a></span></dt>
31<dt><span class="sect2"><a href="mc-manual.html#mc-manual.bad-syscall-args">4.2.3. Use of uninitialised or unaddressable values in system
32       calls</a></span></dt>
33<dt><span class="sect2"><a href="mc-manual.html#mc-manual.badfrees">4.2.4. Illegal frees</a></span></dt>
34<dt><span class="sect2"><a href="mc-manual.html#mc-manual.rudefn">4.2.5. When a heap block is freed with an inappropriate deallocation
35function</a></span></dt>
36<dt><span class="sect2"><a href="mc-manual.html#mc-manual.overlap">4.2.6. Overlapping source and destination blocks</a></span></dt>
37<dt><span class="sect2"><a href="mc-manual.html#mc-manual.fishyvalue">4.2.7. Fishy argument values</a></span></dt>
38<dt><span class="sect2"><a href="mc-manual.html#mc-manual.leaks">4.2.8. Memory leak detection</a></span></dt>
39</dl></dd>
40<dt><span class="sect1"><a href="mc-manual.html#mc-manual.options">4.3. Memcheck Command-Line Options</a></span></dt>
41<dt><span class="sect1"><a href="mc-manual.html#mc-manual.suppfiles">4.4. Writing suppression files</a></span></dt>
42<dt><span class="sect1"><a href="mc-manual.html#mc-manual.machine">4.5. Details of Memcheck's checking machinery</a></span></dt>
43<dd><dl>
44<dt><span class="sect2"><a href="mc-manual.html#mc-manual.value">4.5.1. Valid-value (V) bits</a></span></dt>
45<dt><span class="sect2"><a href="mc-manual.html#mc-manual.vaddress">4.5.2. Valid-address (A) bits</a></span></dt>
46<dt><span class="sect2"><a href="mc-manual.html#mc-manual.together">4.5.3. Putting it all together</a></span></dt>
47</dl></dd>
48<dt><span class="sect1"><a href="mc-manual.html#mc-manual.monitor-commands">4.6. Memcheck Monitor Commands</a></span></dt>
49<dt><span class="sect1"><a href="mc-manual.html#mc-manual.clientreqs">4.7. Client Requests</a></span></dt>
50<dt><span class="sect1"><a href="mc-manual.html#mc-manual.mempools">4.8. Memory Pools: describing and working with custom allocators</a></span></dt>
51<dt><span class="sect1"><a href="mc-manual.html#mc-manual.mpiwrap">4.9. Debugging MPI Parallel Programs with Valgrind</a></span></dt>
52<dd><dl>
53<dt><span class="sect2"><a href="mc-manual.html#mc-manual.mpiwrap.build">4.9.1. Building and installing the wrappers</a></span></dt>
54<dt><span class="sect2"><a href="mc-manual.html#mc-manual.mpiwrap.gettingstarted">4.9.2. Getting started</a></span></dt>
55<dt><span class="sect2"><a href="mc-manual.html#mc-manual.mpiwrap.controlling">4.9.3. Controlling the wrapper library</a></span></dt>
56<dt><span class="sect2"><a href="mc-manual.html#mc-manual.mpiwrap.limitations.functions">4.9.4. Functions</a></span></dt>
57<dt><span class="sect2"><a href="mc-manual.html#mc-manual.mpiwrap.limitations.types">4.9.5. Types</a></span></dt>
58<dt><span class="sect2"><a href="mc-manual.html#mc-manual.mpiwrap.writingwrappers">4.9.6. Writing new wrappers</a></span></dt>
59<dt><span class="sect2"><a href="mc-manual.html#mc-manual.mpiwrap.whattoexpect">4.9.7. What to expect when using the wrappers</a></span></dt>
60</dl></dd>
61</dl>
62</div>
63<p>To use this tool, you may specify <code class="option">--tool=memcheck</code>
64on the Valgrind command line.  You don't have to, though, since Memcheck
65is the default tool.</p>
66<div class="sect1">
67<div class="titlepage"><div><div><h2 class="title" style="clear: both">
68<a name="mc-manual.overview"></a>4.1.�Overview</h2></div></div></div>
69<p>Memcheck is a memory error detector.  It can detect the following
70problems that are common in C and C++ programs.</p>
71<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
72<li class="listitem"><p>Accessing memory you shouldn't, e.g. overrunning and underrunning
73    heap blocks, overrunning the top of the stack, and accessing memory after
74    it has been freed.</p></li>
75<li class="listitem"><p>Using undefined values, i.e. values that have not been initialised,
76    or that have been derived from other undefined values.</p></li>
77<li class="listitem"><p>Incorrect freeing of heap memory, such as double-freeing heap
78    blocks, or mismatched use of
79    <code class="function">malloc</code>/<code class="computeroutput">new</code>/<code class="computeroutput">new[]</code>
80    versus
81    <code class="function">free</code>/<code class="computeroutput">delete</code>/<code class="computeroutput">delete[]</code></p></li>
82<li class="listitem"><p>Overlapping <code class="computeroutput">src</code> and
83    <code class="computeroutput">dst</code> pointers in
84    <code class="computeroutput">memcpy</code> and related
85    functions.</p></li>
86<li class="listitem"><p>Passing a fishy (presumably negative) value to the
87    <code class="computeroutput">size</code> parameter of a memory
88    allocation function.</p></li>
89<li class="listitem"><p>Memory leaks.</p></li>
90</ul></div>
91<p>Problems like these can be difficult to find by other means,
92often remaining undetected for long periods, then causing occasional,
93  difficult-to-diagnose crashes.</p>
94<p>Memcheck also provides <a class="xref" href="manual-core.html#manual-core.xtree" title="2.9.�Execution Trees">Execution Trees</a> memory
95  profiling using the command line
96  option <code class="computeroutput">--xtree-memory</code> and the monitor command
97   <code class="computeroutput">xtmemory</code>.</p>
98</div>
99<div class="sect1">
100<div class="titlepage"><div><div><h2 class="title" style="clear: both">
101<a name="mc-manual.errormsgs"></a>4.2.�Explanation of error messages from Memcheck</h2></div></div></div>
102<p>Memcheck issues a range of error messages.  This section presents a
103quick summary of what error messages mean.  The precise behaviour of the
104error-checking machinery is described in <a class="xref" href="mc-manual.html#mc-manual.machine" title="4.5.�Details of Memcheck's checking machinery">Details of Memcheck's checking machinery</a>.</p>
105<div class="sect2">
106<div class="titlepage"><div><div><h3 class="title">
107<a name="mc-manual.badrw"></a>4.2.1.�Illegal read / Illegal write errors</h3></div></div></div>
108<p>For example:</p>
109<pre class="programlisting">
110Invalid read of size 4
111   at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9)
112   by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9)
113   by 0x40B07FF4: read_png_image(QImageIO *) (kernel/qpngio.cpp:326)
114   by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621)
115 Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd
116</pre>
117<p>This happens when your program reads or writes memory at a place
118which Memcheck reckons it shouldn't.  In this example, the program did a
1194-byte read at address 0xBFFFF0E0, somewhere within the system-supplied
120library libpng.so.2.1.0.9, which was called from somewhere else in the
121same library, called from line 326 of <code class="filename">qpngio.cpp</code>,
122and so on.</p>
123<p>Memcheck tries to establish what the illegal address might relate
124to, since that's often useful.  So, if it points into a block of memory
125which has already been freed, you'll be informed of this, and also where
126the block was freed.  Likewise, if it should turn out to be just off
127the end of a heap block, a common result of off-by-one-errors in
128array subscripting, you'll be informed of this fact, and also where the
129block was allocated.  If you use the <code class="option"><a class="xref" href="manual-core.html#opt.read-var-info">--read-var-info</a></code> option Memcheck will run more slowly
130but may give a more detailed description of any illegal address.</p>
131<p>In this example, Memcheck can't identify the address.  Actually
132the address is on the stack, but, for some reason, this is not a valid
133stack address -- it is below the stack pointer and that isn't allowed.
134In this particular case it's probably caused by GCC generating invalid
135code, a known bug in some ancient versions of GCC.</p>
136<p>Note that Memcheck only tells you that your program is about to
137access memory at an illegal address.  It can't stop the access from
138happening.  So, if your program makes an access which normally would
139result in a segmentation fault, you program will still suffer the same
140fate -- but you will get a message from Memcheck immediately prior to
141this.  In this particular example, reading junk on the stack is
142non-fatal, and the program stays alive.</p>
143</div>
144<div class="sect2">
145<div class="titlepage"><div><div><h3 class="title">
146<a name="mc-manual.uninitvals"></a>4.2.2.�Use of uninitialised values</h3></div></div></div>
147<p>For example:</p>
148<pre class="programlisting">
149Conditional jump or move depends on uninitialised value(s)
150   at 0x402DFA94: _IO_vfprintf (_itoa.h:49)
151   by 0x402E8476: _IO_printf (printf.c:36)
152   by 0x8048472: main (tests/manuel1.c:8)
153</pre>
154<p>An uninitialised-value use error is reported when your program
155uses a value which hasn't been initialised -- in other words, is
156undefined.  Here, the undefined value is used somewhere inside the
157<code class="function">printf</code> machinery of the C library.  This error was
158reported when running the following small program:</p>
159<pre class="programlisting">
160int main()
161{
162  int x;
163  printf ("x = %d\n", x);
164}</pre>
165<p>It is important to understand that your program can copy around
166junk (uninitialised) data as much as it likes.  Memcheck observes this
167and keeps track of the data, but does not complain.  A complaint is
168issued only when your program attempts to make use of uninitialised
169data in a way that might affect your program's externally-visible behaviour.
170In this example, <code class="varname">x</code> is uninitialised.  Memcheck observes
171the value being passed to <code class="function">_IO_printf</code> and thence to
172<code class="function">_IO_vfprintf</code>, but makes no comment.  However,
173<code class="function">_IO_vfprintf</code> has to examine the value of
174<code class="varname">x</code> so it can turn it into the corresponding ASCII string,
175and it is at this point that Memcheck complains.</p>
176<p>Sources of uninitialised data tend to be:</p>
177<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
178<li class="listitem"><p>Local variables in procedures which have not been initialised,
179    as in the example above.</p></li>
180<li class="listitem"><p>The contents of heap blocks (allocated with
181    <code class="function">malloc</code>, <code class="function">new</code>, or a similar
182    function) before you (or a constructor) write something there.
183    </p></li>
184</ul></div>
185<p>To see information on the sources of uninitialised data in your
186program, use the <code class="option">--track-origins=yes</code> option.  This
187makes Memcheck run more slowly, but can make it much easier to track down
188the root causes of uninitialised value errors.</p>
189</div>
190<div class="sect2">
191<div class="titlepage"><div><div><h3 class="title">
192<a name="mc-manual.bad-syscall-args"></a>4.2.3.�Use of uninitialised or unaddressable values in system
193       calls</h3></div></div></div>
194<p>Memcheck checks all parameters to system calls:
195</p>
196<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
197<li class="listitem"><p>It checks all the direct parameters themselves, whether they are
198    initialised.</p></li>
199<li class="listitem"><p>Also, if a system call needs to read from a buffer provided by
200    your program, Memcheck checks that the entire buffer is addressable
201    and its contents are initialised.</p></li>
202<li class="listitem"><p>Also, if the system call needs to write to a user-supplied
203    buffer, Memcheck checks that the buffer is addressable.</p></li>
204</ul></div>
205<p>
206</p>
207<p>After the system call, Memcheck updates its tracked information to
208precisely reflect any changes in memory state caused by the system
209call.</p>
210<p>Here's an example of two system calls with invalid parameters:</p>
211<pre class="programlisting">
212  #include &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
237from the heap block to the standard output, and (b) passed an
238uninitialised value to <code class="function">exit</code>.  Note that the first
239error refers to the memory pointed to by
240<code class="computeroutput">buf</code> (not
241<code class="computeroutput">buf</code> itself), but the second error
242refers directly to <code class="computeroutput">exit</code>'s argument
243<code class="computeroutput">arr2[0]</code>.</p>
244</div>
245<div class="sect2">
246<div class="titlepage"><div><div><h3 class="title">
247<a name="mc-manual.badfrees"></a>4.2.4.�Illegal frees</h3></div></div></div>
248<p>For example:</p>
249<pre class="programlisting">
250Invalid free()
251   at 0x4004FFDF: free (vg_clientmalloc.c:577)
252   by 0x80484C7: main (tests/doublefree.c:10)
253 Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd
254   at 0x4004FFDF: free (vg_clientmalloc.c:577)
255   by 0x80484C7: main (tests/doublefree.c:10)
256</pre>
257<p>Memcheck keeps track of the blocks allocated by your program
258with <code class="function">malloc</code>/<code class="computeroutput">new</code>,
259so it can know exactly whether or not the argument to
260<code class="function">free</code>/<code class="computeroutput">delete</code> is
261legitimate or not.  Here, this test program has freed the same block
262twice.  As with the illegal read/write errors, Memcheck attempts to
263make sense of the address freed.  If, as here, the address is one
264which has previously been freed, you wil be told that -- making
265duplicate frees of the same block easy to spot.  You will also get this
266message if you try to free a pointer that doesn't point to the start of a
267heap block.</p>
268</div>
269<div class="sect2">
270<div class="titlepage"><div><div><h3 class="title">
271<a name="mc-manual.rudefn"></a>4.2.5.�When a heap block is freed with an inappropriate deallocation
272function</h3></div></div></div>
273<p>In the following example, a block allocated with
274<code class="function">new[]</code> has wrongly been deallocated with
275<code class="function">free</code>:</p>
276<pre class="programlisting">
277Mismatched free() / delete / delete []
278   at 0x40043249: free (vg_clientfuncs.c:171)
279   by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149)
280   by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60)
281   by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44)
282 Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd
283   at 0x4004318C: operator new[](unsigned int) (vg_clientfuncs.c:152)
284   by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314)
285   by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416)
286   by 0x4C21788F: OLEFilter::convert(QCString const &amp;) (olefilter.cc:272)
287</pre>
288<p>In <code class="literal">C++</code> it's important to deallocate memory in a
289way compatible with how it was allocated.  The deal is:</p>
290<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
291<li class="listitem"><p>If allocated with
292    <code class="function">malloc</code>,
293    <code class="function">calloc</code>,
294    <code class="function">realloc</code>,
295    <code class="function">valloc</code> or
296    <code class="function">memalign</code>, you must
297    deallocate with <code class="function">free</code>.</p></li>
298<li class="listitem"><p>If allocated with <code class="function">new</code>, you must deallocate
299   with <code class="function">delete</code>.</p></li>
300<li class="listitem"><p>If allocated with <code class="function">new[]</code>, you must
301    deallocate with <code class="function">delete[]</code>.</p></li>
302</ul></div>
303<p>The worst thing is that on Linux apparently it doesn't matter if
304you do mix these up, but the same program may then crash on a
305different platform, Solaris for example.  So it's best to fix it
306properly.  According to the KDE folks "it's amazing how many C++
307programmers don't know this".</p>
308<p>The reason behind the requirement is as follows.  In some C++
309implementations, <code class="function">delete[]</code> must be used for
310objects allocated by <code class="function">new[]</code> because the compiler
311stores the size of the array and the pointer-to-member to the
312destructor of the array's content just before the pointer actually
313returned.  <code class="function">delete</code> doesn't account for this and will get
314confused, possibly corrupting the heap.</p>
315</div>
316<div class="sect2">
317<div class="titlepage"><div><div><h3 class="title">
318<a name="mc-manual.overlap"></a>4.2.6.�Overlapping source and destination blocks</h3></div></div></div>
319<p>The following C library functions copy some data from one
320memory block to another (or something similar):
321<code class="function">memcpy</code>,
322<code class="function">strcpy</code>,
323<code class="function">strncpy</code>,
324<code class="function">strcat</code>,
325<code class="function">strncat</code>.
326The blocks pointed to by their <code class="computeroutput">src</code> and
327<code class="computeroutput">dst</code> pointers aren't allowed to overlap.
328The POSIX standards have wording along the lines "If copying takes place
329between objects that overlap, the behavior is undefined." Therefore,
330Memcheck checks for this.
331</p>
332<p>For example:</p>
333<pre class="programlisting">
334==27492== Source and destination overlap in memcpy(0xbffff294, 0xbffff280, 21)
335==27492==    at 0x40026CDC: memcpy (mc_replace_strmem.c:71)
336==27492==    by 0x804865A: main (overlap.c:40)
337</pre>
338<p>You don't want the two blocks to overlap because one of them could
339get partially overwritten by the copying.</p>
340<p>You might think that Memcheck is being overly pedantic reporting
341this in the case where <code class="computeroutput">dst</code> is less than
342<code class="computeroutput">src</code>.  For example, the obvious way to
343implement <code class="function">memcpy</code> is by copying from the first
344byte to the last.  However, the optimisation guides of some
345architectures recommend copying from the last byte down to the first.
346Also, some implementations of <code class="function">memcpy</code> zero
347<code class="computeroutput">dst</code> before copying, because zeroing the
348destination's cache line(s) can improve performance.</p>
349<p>The moral of the story is: if you want to write truly portable
350code, don't make any assumptions about the language
351implementation.</p>
352</div>
353<div class="sect2">
354<div class="titlepage"><div><div><h3 class="title">
355<a name="mc-manual.fishyvalue"></a>4.2.7.�Fishy argument values</h3></div></div></div>
356<p>All memory allocation functions take an argument specifying the
357size of the memory block that should be allocated. Clearly, the requested
358size should be a non-negative value and is typically not excessively large.
359For instance, it is extremely unlikly that the size of an allocation
360request exceeds 2**63 bytes on a 64-bit machine. It is much more likely that
361such a value is the result of an erroneous size calculation and is in effect
362a negative value (that just happens to appear excessively large because
363the bit pattern is interpreted as an unsigned integer).
364Such a value is called a "fishy value".
365
366The <code class="varname">size</code> argument of the following allocation functions
367is checked for being fishy:
368<code class="function">malloc</code>,
369<code class="function">calloc</code>,
370<code class="function">realloc</code>,
371<code class="function">memalign</code>,
372<code class="function">new</code>,
373<code class="function">new []</code>.
374<code class="function">__builtin_new</code>,
375<code class="function">__builtin_vec_new</code>,
376For <code class="function">calloc</code> both arguments are being checked.
377</p>
378<p>For example:</p>
379<pre class="programlisting">
380==32233== Argument 'size' of function malloc has a fishy (possibly negative) value: -3
381==32233==    at 0x4C2CFA7: malloc (vg_replace_malloc.c:298)
382==32233==    by 0x400555: foo (fishy.c:15)
383==32233==    by 0x400583: main (fishy.c:23)
384</pre>
385<p>In earlier Valgrind versions those values were being referred to
386as "silly arguments" and no back-trace was included.
387</p>
388</div>
389<div class="sect2">
390<div class="titlepage"><div><div><h3 class="title">
391<a name="mc-manual.leaks"></a>4.2.8.�Memory leak detection</h3></div></div></div>
392<p>Memcheck keeps track of all heap blocks issued in response to
393calls to
394<code class="function">malloc</code>/<code class="function">new</code> et al.
395So when the program exits, it knows which blocks have not been freed.
396</p>
397<p>If <code class="option">--leak-check</code> is set appropriately, for each
398remaining block, Memcheck determines if the block is reachable from pointers
399within the root-set.  The root-set consists of (a) general purpose registers
400of all threads, and (b) initialised, aligned, pointer-sized data words in
401accessible client memory, including stacks.</p>
402<p>There are two ways a block can be reached.  The first is with a
403"start-pointer", i.e. a pointer to the start of the block.  The second is with
404an "interior-pointer", i.e. a pointer to the middle of the block.  There are
405several ways we know of that an interior-pointer can occur:</p>
406<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
407<li class="listitem"><p>The pointer might have originally been a start-pointer and have been
408    moved along deliberately (or not deliberately) by the program.  In
409    particular, this can happen if your program uses tagged pointers, i.e.
410    if it uses the bottom one, two or three bits of a pointer, which are
411    normally always zero due to alignment, in order to store extra
412    information.</p></li>
413<li class="listitem"><p>It might be a random junk value in memory, entirely unrelated, just
414    a coincidence.</p></li>
415<li class="listitem"><p>It might be a pointer to the inner char array of a C++
416    <code class="computeroutput">std::string</code>.  For example, some
417    compilers add 3 words at the beginning of the std::string to
418    store the length, the capacity and a reference count before the
419    memory containing the array of characters. They return a pointer
420    just after these 3 words, pointing at the char array.</p></li>
421<li class="listitem"><p>Some code might allocate a block of memory, and use the first 8
422    bytes to store (block size - 8) as a 64bit number.
423    <code class="computeroutput">sqlite3MemMalloc</code> does this.</p></li>
424<li class="listitem"><p>It might be a pointer to an array of C++ objects (which possess
425    destructors) allocated with <code class="computeroutput">new[]</code>.  In
426    this case, some compilers store a "magic cookie" containing the array
427    length at the start of the allocated block, and return a pointer to just
428    past that magic cookie, i.e. an interior-pointer.
429    See <a class="ulink" href="http://theory.uwinnipeg.ca/gnu/gcc/gxxint_14.html" target="_top">this
430    page</a> for more information.</p></li>
431<li class="listitem"><p>It might be a pointer to an inner part of a C++ object using
432    multiple inheritance. </p></li>
433</ul></div>
434<p>You can optionally activate heuristics to use during the leak
435search to detect the interior pointers corresponding to
436the <code class="computeroutput">stdstring</code>,
437<code class="computeroutput">length64</code>,
438<code class="computeroutput">newarray</code>
439and <code class="computeroutput">multipleinheritance</code> cases. If the
440heuristic detects that an interior pointer corresponds to such a case,
441the block will be considered as reachable by the interior
442pointer. In other words, the interior pointer will be treated
443as if it were a start pointer.</p>
444<p>With that in mind, consider the nine possible cases described by the
445following figure.</p>
446<pre class="programlisting">
447     Pointer chain            AAA Leak Case   BBB Leak Case
448     -------------            -------------   -------------
449(1)  RRR ------------&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
459Pointer 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
465Leak Case legend:
466- DR: Directly reachable
467- IR: Indirectly reachable
468- DL: Directly lost
469- IL: Indirectly lost
470- (y)XY: it's XY if the interior-pointer is a real pointer
471- (n)XY: it's XY if the interior-pointer is not a real pointer
472- (_)XY: it's XY in either case
473</pre>
474<p>Every possible case can be reduced to one of the above nine.  Memcheck
475merges some of these cases in its output, resulting in the following four
476leak kinds.</p>
477<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
478<li class="listitem"><p>"Still reachable". This covers cases 1 and 2 (for the BBB blocks)
479    above.  A start-pointer or chain of start-pointers to the block is
480    found.  Since the block is still pointed at, the programmer could, at
481    least in principle, have freed it before program exit.  "Still reachable"
482    blocks are very common and arguably not a problem. So, by default,
483    Memcheck won't report such blocks individually.</p></li>
484<li class="listitem"><p>"Definitely lost".  This covers case 3 (for the BBB blocks) above.
485    This means that no pointer to the block can be found.  The block is
486    classified as "lost", because the programmer could not possibly have
487    freed it at program exit, since no pointer to it exists.  This is likely
488    a symptom of having lost the pointer at some earlier point in the
489    program.  Such cases should be fixed by the programmer.</p></li>
490<li class="listitem"><p>"Indirectly lost".  This covers cases 4 and 9 (for the BBB blocks)
491    above.  This means that the block is lost, not because there are no
492    pointers to it, but rather because all the blocks that point to it are
493    themselves lost.  For example, if you have a binary tree and the root
494    node is lost, all its children nodes will be indirectly lost.  Because
495    the problem will disappear if the definitely lost block that caused the
496    indirect leak is fixed, Memcheck won't report such blocks individually
497    by default.</p></li>
498<li class="listitem"><p>"Possibly lost".  This covers cases 5--8 (for the BBB blocks)
499    above.  This means that a chain of one or more pointers to the block has
500    been found, but at least one of the pointers is an interior-pointer.
501    This could just be a random value in memory that happens to point into a
502    block, and so you shouldn't consider this ok unless you know you have
503    interior-pointers.</p></li>
504</ul></div>
505<p>(Note: This mapping of the nine possible cases onto four leak kinds is
506not necessarily the best way that leaks could be reported;  in particular,
507interior-pointers are treated inconsistently.  It is possible the
508categorisation may be improved in the future.)</p>
509<p>Furthermore, if suppressions exists for a block, it will be reported
510as "suppressed" no matter what which of the above four kinds it belongs
511to.</p>
512<p>The following is an example leak summary.</p>
513<pre class="programlisting">
514LEAK SUMMARY:
515   definitely lost: 48 bytes in 3 blocks.
516   indirectly lost: 32 bytes in 2 blocks.
517     possibly lost: 96 bytes in 6 blocks.
518   still reachable: 64 bytes in 4 blocks.
519        suppressed: 0 bytes in 0 blocks.
520</pre>
521<p>If heuristics have been used to consider some blocks as
522reachable, the leak summary details the heuristically reachable subset
523of 'still reachable:' per heuristic. In the below example, of the 95
524bytes still reachable, 87 bytes (56+7+8+16) have been considered
525heuristically reachable.
526</p>
527<pre class="programlisting">
528LEAK SUMMARY:
529   definitely lost: 4 bytes in 1 blocks
530   indirectly lost: 0 bytes in 0 blocks
531     possibly lost: 0 bytes in 0 blocks
532   still reachable: 95 bytes in 6 blocks
533                      of which reachable via heuristic:
534                        stdstring          : 56 bytes in 2 blocks
535                        length64           : 16 bytes in 1 blocks
536                        newarray           : 7 bytes in 1 blocks
537                        multipleinheritance: 8 bytes in 1 blocks
538        suppressed: 0 bytes in 0 blocks
539</pre>
540<p>If <code class="option">--leak-check=full</code> is specified,
541Memcheck will give details for each definitely lost or possibly lost block,
542including where it was allocated.  (Actually, it merges results for all
543blocks that have the same leak kind and sufficiently similar stack traces
544into a single "loss record".  The
545<code class="option">--leak-resolution</code> lets you control the
546meaning of "sufficiently similar".)  It cannot tell you when or how or why
547the pointer to a leaked block was lost; you have to work that out for
548yourself.  In general, you should attempt to ensure your programs do not
549have any definitely lost or possibly lost blocks at exit.</p>
550<p>For example:</p>
551<pre class="programlisting">
5528 bytes in 1 blocks are definitely lost in loss record 1 of 14
553   at 0x........: malloc (vg_replace_malloc.c:...)
554   by 0x........: mk (leak-tree.c:11)
555   by 0x........: main (leak-tree.c:39)
556
55788 (8 direct, 80 indirect) bytes in 1 blocks are definitely lost in loss record 13 of 14
558   at 0x........: malloc (vg_replace_malloc.c:...)
559   by 0x........: mk (leak-tree.c:11)
560   by 0x........: main (leak-tree.c:25)
561</pre>
562<p>The first message describes a simple case of a single 8 byte block
563that has been definitely lost.  The second case mentions another 8 byte
564block that has been definitely lost;  the difference is that a further 80
565bytes in other blocks are indirectly lost because of this lost block.
566The loss records are not presented in any notable order, so the loss record
567numbers aren't particularly meaningful. The loss record numbers can be used
568in the Valgrind gdbserver to list the addresses of the leaked blocks and/or give
569more details about how a block is still reachable.</p>
570<p>The option <code class="option">--show-leak-kinds=&lt;set&gt;</code>
571controls the set of leak kinds to show
572when <code class="option">--leak-check=full</code> is specified. </p>
573<p>The <code class="option">&lt;set&gt;</code> of leak kinds is specified
574in one of the following ways:
575
576</p>
577<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
578<li class="listitem"><p>a comma separated list of one or more of
579    <code class="option">definite indirect possible reachable</code>.</p></li>
580<li class="listitem"><p><code class="option">all</code> to specify the complete set (all leak kinds).</p></li>
581<li class="listitem"><p><code class="option">none</code> for the empty set.</p></li>
582</ul></div>
583<p>
584
585</p>
586<p> The default value for the leak kinds to show is
587  <code class="option">--show-leak-kinds=definite,possible</code>.
588</p>
589<p>To also show the reachable and indirectly lost blocks in
590addition to the definitely and possibly lost blocks, you can
591use <code class="option">--show-leak-kinds=all</code>.  To only show the
592reachable and indirectly lost blocks, use
593<code class="option">--show-leak-kinds=indirect,reachable</code>.  The reachable
594and indirectly lost blocks will then be presented as shown in
595the following two examples.</p>
596<pre class="programlisting">
59764 bytes in 4 blocks are still reachable in loss record 2 of 4
598   at 0x........: malloc (vg_replace_malloc.c:177)
599   by 0x........: mk (leak-cases.c:52)
600   by 0x........: main (leak-cases.c:74)
601
60232 bytes in 2 blocks are indirectly lost in loss record 1 of 4
603   at 0x........: malloc (vg_replace_malloc.c:177)
604   by 0x........: mk (leak-cases.c:52)
605   by 0x........: main (leak-cases.c:80)
606</pre>
607<p>Because there are different kinds of leaks with different
608severities, an interesting question is: which leaks should be
609counted as true "errors" and which should not?
610</p>
611<p> The answer to this question affects the numbers printed in
612the <code class="computeroutput">ERROR SUMMARY</code> line, and also the
613effect of the <code class="option">--error-exitcode</code> option.  First, a leak
614is only counted as a true "error"
615if <code class="option">--leak-check=full</code> is specified.  Then, the
616option <code class="option">--errors-for-leak-kinds=&lt;set&gt;</code> controls
617the set of leak kinds to consider as errors.  The default value
618is <code class="option">--errors-for-leak-kinds=definite,possible</code>
619</p>
620</div>
621</div>
622<div class="sect1">
623<div class="titlepage"><div><div><h2 class="title" style="clear: both">
624<a name="mc-manual.options"></a>4.3.�Memcheck Command-Line Options</h2></div></div></div>
625<div class="variablelist">
626<a name="mc.opts.list"></a><dl class="variablelist">
627<dt>
628<a name="opt.leak-check"></a><span class="term">
629      <code class="option">--leak-check=&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">
1105Memcheck:suppression_type</pre>
1106<p>The Memcheck suppression types are as follows:</p>
1107<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1108<li class="listitem"><p><code class="varname">Value1</code>,
1109    <code class="varname">Value2</code>,
1110    <code class="varname">Value4</code>,
1111    <code class="varname">Value8</code>,
1112    <code class="varname">Value16</code>,
1113    meaning an uninitialised-value error when
1114    using a value of 1, 2, 4, 8 or 16 bytes.</p></li>
1115<li class="listitem"><p><code class="varname">Cond</code> (or its old
1116    name, <code class="varname">Value0</code>), meaning use
1117    of an uninitialised CPU condition code.</p></li>
1118<li class="listitem"><p><code class="varname">Addr1</code>,
1119    <code class="varname">Addr2</code>,
1120    <code class="varname">Addr4</code>,
1121    <code class="varname">Addr8</code>,
1122    <code class="varname">Addr16</code>,
1123    meaning an invalid address during a
1124    memory access of 1, 2, 4, 8 or 16 bytes respectively.</p></li>
1125<li class="listitem"><p><code class="varname">Jump</code>, meaning an
1126    jump to an unaddressable location error.</p></li>
1127<li class="listitem"><p><code class="varname">Param</code>, meaning an
1128    invalid system call parameter error.</p></li>
1129<li class="listitem"><p><code class="varname">Free</code>, meaning an
1130    invalid or mismatching free.</p></li>
1131<li class="listitem"><p><code class="varname">Overlap</code>, meaning a
1132    <code class="computeroutput">src</code> /
1133    <code class="computeroutput">dst</code> overlap in
1134    <code class="function">memcpy</code> or a similar function.</p></li>
1135<li class="listitem"><p><code class="varname">Leak</code>, meaning
1136    a memory leak.</p></li>
1137</ul></div>
1138<p><code class="computeroutput">Param</code> errors have a mandatory extra
1139information line at this point, which is the name of the offending
1140system call parameter. </p>
1141<p><code class="computeroutput">Leak</code> errors have an optional
1142extra information line, with the following format:</p>
1143<pre class="programlisting">
1144match-leak-kinds:&lt;set&gt;</pre>
1145<p>where <code class="computeroutput">&lt;set&gt;</code> specifies which
1146leak kinds are matched by this suppression entry.
1147<code class="computeroutput">&lt;set&gt;</code> is specified in the
1148same way as with the option <code class="option">--show-leak-kinds</code>, that is,
1149one of the following:</p>
1150<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1151<li class="listitem">a comma separated list of one or more of
1152    <code class="option">definite indirect possible reachable</code>.
1153  </li>
1154<li class="listitem">
1155<code class="option">all</code> to specify the complete set (all leak kinds).
1156  </li>
1157<li class="listitem">
1158<code class="option">none</code> for the empty set.
1159  </li>
1160</ul></div>
1161<p>If this optional extra line is not present, the suppression
1162entry will match all leak kinds.</p>
1163<p>Be aware that leak suppressions that are created using
1164<code class="option">--gen-suppressions</code> will contain this optional extra
1165line, and therefore may match fewer leaks than you expect.  You may
1166want to remove the line before using the generated
1167suppressions.</p>
1168<p>The other Memcheck error kinds do not have extra lines.</p>
1169<p>
1170If you give the <code class="option">-v</code> option, Valgrind will print
1171the list of used suppressions at the end of execution.
1172For a leak suppression, this output gives the number of different
1173loss records that match the suppression, and the number of bytes
1174and blocks suppressed by the suppression.
1175If the run contains multiple leak checks, the number of bytes and blocks
1176are reset to zero before each new leak check. Note that the number of different
1177loss records is not reset to zero.</p>
1178<p>In the example below, in the last leak search, 7 blocks and 96 bytes have
1179been suppressed by a suppression with the name
1180<code class="option">some_leak_suppression</code>:</p>
1181<pre class="programlisting">
1182--21041-- used_suppression:     10 some_other_leak_suppression s.supp:14 suppressed: 12,400 bytes in 1 blocks
1183--21041-- used_suppression:     39 some_leak_suppression s.supp:2 suppressed: 96 bytes in 7 blocks
1184</pre>
1185<p>For <code class="varname">ValueN</code> and <code class="varname">AddrN</code>
1186errors, the first line of the calling context is either the name of
1187the function in which the error occurred, or, failing that, the full
1188path of the <code class="filename">.so</code> file or executable containing the
1189error location.  For <code class="varname">Free</code> errors, the first line is
1190the name of the function doing the freeing (eg,
1191<code class="function">free</code>, <code class="function">__builtin_vec_delete</code>,
1192etc).  For <code class="varname">Overlap</code> errors, the first line is the name of the
1193function with the overlapping arguments (eg.
1194<code class="function">memcpy</code>, <code class="function">strcpy</code>, etc).</p>
1195<p>The last part of any suppression specifies the rest of the
1196calling context that needs to be matched.</p>
1197</div>
1198<div class="sect1">
1199<div class="titlepage"><div><div><h2 class="title" style="clear: both">
1200<a name="mc-manual.machine"></a>4.5.�Details of Memcheck's checking machinery</h2></div></div></div>
1201<p>Read this section if you want to know, in detail, exactly
1202what and how Memcheck is checking.</p>
1203<div class="sect2">
1204<div class="titlepage"><div><div><h3 class="title">
1205<a name="mc-manual.value"></a>4.5.1.�Valid-value (V) bits</h3></div></div></div>
1206<p>It is simplest to think of Memcheck implementing a synthetic CPU
1207which is identical to a real CPU, except for one crucial detail.  Every
1208bit (literally) of data processed, stored and handled by the real CPU
1209has, in the synthetic CPU, an associated "valid-value" bit, which says
1210whether or not the accompanying bit has a legitimate value.  In the
1211discussions which follow, this bit is referred to as the V (valid-value)
1212bit.</p>
1213<p>Each byte in the system therefore has a 8 V bits which follow it
1214wherever it goes.  For example, when the CPU loads a word-size item (4
1215bytes) from memory, it also loads the corresponding 32 V bits from a
1216bitmap which stores the V bits for the process' entire address space.
1217If the CPU should later write the whole or some part of that value to
1218memory at a different address, the relevant V bits will be stored back
1219in the V-bit bitmap.</p>
1220<p>In short, each bit in the system has (conceptually) an associated V
1221bit, which follows it around everywhere, even inside the CPU.  Yes, all the
1222CPU's registers (integer, floating point, vector and condition registers)
1223have their own V bit vectors.  For this to work, Memcheck uses a great deal
1224of compression to represent the V bits compactly.</p>
1225<p>Copying values around does not cause Memcheck to check for, or
1226report on, errors.  However, when a value is used in a way which might
1227conceivably affect your program's externally-visible behaviour,
1228the associated V bits are immediately checked.  If any of these indicate
1229that the value is undefined (even partially), an error is reported.</p>
1230<p>Here's an (admittedly nonsensical) example:</p>
1231<pre class="programlisting">
1232int i, j;
1233int a[10], b[10];
1234for ( i = 0; i &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
1239uninitialised values from <code class="varname">a[]</code> into
1240<code class="varname">b[]</code>, and doesn't use them in a way which could
1241affect the behaviour of the program.  However, if
1242the loop is changed to:</p>
1243<pre class="programlisting">
1244for ( i = 0; i &lt; 10; i++ ) {
1245  j += a[i];
1246}
1247if ( j == 77 )
1248  printf("hello there\n");
1249</pre>
1250<p>then Memcheck will complain, at the
1251<code class="computeroutput">if</code>, that the condition depends on
1252uninitialised values.  Note that it <span class="command"><strong>doesn't</strong></span> complain
1253at the <code class="varname">j += a[i];</code>, since at that point the
1254undefinedness is not "observable".  It's only when a decision has to be
1255made as to whether or not to do the <code class="function">printf</code> -- an
1256observable action of your program -- that Memcheck complains.</p>
1257<p>Most low level operations, such as adds, cause Memcheck to use the
1258V bits for the operands to calculate the V bits for the result.  Even if
1259the result is partially or wholly undefined, it does not
1260complain.</p>
1261<p>Checks on definedness only occur in three places: when a value is
1262used to generate a memory address, when control flow decision needs to
1263be made, and when a system call is detected, Memcheck checks definedness
1264of parameters as required.</p>
1265<p>If a check should detect undefinedness, an error message is
1266issued.  The resulting value is subsequently regarded as well-defined.
1267To do otherwise would give long chains of error messages.  In other
1268words, once Memcheck reports an undefined value error, it tries to
1269avoid reporting further errors derived from that same undefined
1270value.</p>
1271<p>This sounds overcomplicated.  Why not just check all reads from
1272memory, and complain if an undefined value is loaded into a CPU
1273register?  Well, that doesn't work well, because perfectly legitimate C
1274programs routinely copy uninitialised values around in memory, and we
1275don't want endless complaints about that.  Here's the canonical example.
1276Consider a struct like this:</p>
1277<pre class="programlisting">
1278struct S { int x; char c; };
1279struct S s1, s2;
1280s1.x = 42;
1281s1.c = 'z';
1282s2 = s1;
1283</pre>
1284<p>The question to ask is: how large is <code class="varname">struct S</code>,
1285in bytes?  An <code class="varname">int</code> is 4 bytes and a
1286<code class="varname">char</code> one byte, so perhaps a <code class="varname">struct
1287S</code> occupies 5 bytes?  Wrong.  All non-toy compilers we know
1288of will round the size of <code class="varname">struct S</code> up to a whole
1289number of words, in this case 8 bytes.  Not doing this forces compilers
1290to generate truly appalling code for accessing arrays of
1291<code class="varname">struct S</code>'s on some architectures.</p>
1292<p>So <code class="varname">s1</code> occupies 8 bytes, yet only 5 of them will
1293be initialised.  For the assignment <code class="varname">s2 = s1</code>, GCC
1294generates code to copy all 8 bytes wholesale into <code class="varname">s2</code>
1295without regard for their meaning.  If Memcheck simply checked values as
1296they came out of memory, it would yelp every time a structure assignment
1297like this happened.  So the more complicated behaviour described above
1298is necessary.  This allows GCC to copy
1299<code class="varname">s1</code> into <code class="varname">s2</code> any way it likes, and a
1300warning will only be emitted if the uninitialised values are later
1301used.</p>
1302</div>
1303<div class="sect2">
1304<div class="titlepage"><div><div><h3 class="title">
1305<a name="mc-manual.vaddress"></a>4.5.2.�Valid-address (A) bits</h3></div></div></div>
1306<p>Notice that the previous subsection describes how the validity of
1307values is established and maintained without having to say whether the
1308program does or does not have the right to access any particular memory
1309location.  We now consider the latter question.</p>
1310<p>As described above, every bit in memory or in the CPU has an
1311associated valid-value (V) bit.  In addition, all bytes in memory, but
1312not in the CPU, have an associated valid-address (A) bit.  This
1313indicates whether or not the program can legitimately read or write that
1314location.  It does not give any indication of the validity of the data
1315at that location -- that's the job of the V bits -- only whether or not
1316the location may be accessed.</p>
1317<p>Every time your program reads or writes memory, Memcheck checks
1318the A bits associated with the address.  If any of them indicate an
1319invalid address, an error is emitted.  Note that the reads and writes
1320themselves do not change the A bits, only consult them.</p>
1321<p>So how do the A bits get set/cleared?  Like this:</p>
1322<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1323<li class="listitem"><p>When the program starts, all the global data areas are
1324    marked as accessible.</p></li>
1325<li class="listitem"><p>When the program does
1326    <code class="function">malloc</code>/<code class="computeroutput">new</code>,
1327    the A bits for exactly the area allocated, and not a byte more,
1328    are marked as accessible.  Upon freeing the area the A bits are
1329    changed to indicate inaccessibility.</p></li>
1330<li class="listitem"><p>When the stack pointer register (<code class="literal">SP</code>) moves
1331    up or down, A bits are set.  The rule is that the area from
1332    <code class="literal">SP</code> up to the base of the stack is marked as
1333    accessible, and below <code class="literal">SP</code> is inaccessible.  (If
1334    that sounds illogical, bear in mind that the stack grows down, not
1335    up, on almost all Unix systems, including GNU/Linux.)  Tracking
1336    <code class="literal">SP</code> like this has the useful side-effect that the
1337    section of stack used by a function for local variables etc is
1338    automatically marked accessible on function entry and inaccessible
1339    on exit.</p></li>
1340<li class="listitem"><p>When doing system calls, A bits are changed appropriately.
1341    For example, <code class="literal">mmap</code>
1342    magically makes files appear in the process'
1343    address space, so the A bits must be updated if <code class="literal">mmap</code>
1344    succeeds.</p></li>
1345<li class="listitem"><p>Optionally, your program can tell Memcheck about such changes
1346    explicitly, using the client request mechanism described
1347    above.</p></li>
1348</ul></div>
1349</div>
1350<div class="sect2">
1351<div class="titlepage"><div><div><h3 class="title">
1352<a name="mc-manual.together"></a>4.5.3.�Putting it all together</h3></div></div></div>
1353<p>Memcheck's checking machinery can be summarised as
1354follows:</p>
1355<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1356<li class="listitem"><p>Each byte in memory has 8 associated V (valid-value) bits,
1357    saying whether or not the byte has a defined value, and a single A
1358    (valid-address) bit, saying whether or not the program currently has
1359    the right to read/write that address.  As mentioned above, heavy
1360    use of compression means the overhead is typically around 25%.</p></li>
1361<li class="listitem"><p>When memory is read or written, the relevant A bits are
1362    consulted.  If they indicate an invalid address, Memcheck emits an
1363    Invalid read or Invalid write error.</p></li>
1364<li class="listitem"><p>When memory is read into the CPU's registers, the relevant V
1365    bits are fetched from memory and stored in the simulated CPU.  They
1366    are not consulted.</p></li>
1367<li class="listitem"><p>When a register is written out to memory, the V bits for that
1368    register are written back to memory too.</p></li>
1369<li class="listitem"><p>When values in CPU registers are used to generate a memory
1370    address, or to determine the outcome of a conditional branch, the V
1371    bits for those values are checked, and an error emitted if any of
1372    them are undefined.</p></li>
1373<li class="listitem"><p>When values in CPU registers are used for any other purpose,
1374    Memcheck computes the V bits for the result, but does not check
1375    them.</p></li>
1376<li class="listitem"><p>Once the V bits for a value in the CPU have been checked, they
1377    are then set to indicate validity.  This avoids long chains of
1378    errors.</p></li>
1379<li class="listitem">
1380<p>When values are loaded from memory, Memcheck checks the A bits
1381    for that location and issues an illegal-address warning if needed.
1382    In that case, the V bits loaded are forced to indicate Valid,
1383    despite the location being invalid.</p>
1384<p>This apparently strange choice reduces the amount of confusing
1385    information presented to the user.  It avoids the unpleasant
1386    phenomenon in which memory is read from a place which is both
1387    unaddressable and contains invalid values, and, as a result, you get
1388    not only an invalid-address (read/write) error, but also a
1389    potentially large set of uninitialised-value errors, one for every
1390    time the value is used.</p>
1391<p>There is a hazy boundary case to do with multi-byte loads from
1392    addresses which are partially valid and partially invalid.  See
1393    details of the option <code class="option">--partial-loads-ok</code> for details.
1394    </p>
1395</li>
1396</ul></div>
1397<p>Memcheck intercepts calls to <code class="function">malloc</code>,
1398<code class="function">calloc</code>, <code class="function">realloc</code>,
1399<code class="function">valloc</code>, <code class="function">memalign</code>,
1400<code class="function">free</code>, <code class="computeroutput">new</code>,
1401<code class="computeroutput">new[]</code>,
1402<code class="computeroutput">delete</code> and
1403<code class="computeroutput">delete[]</code>.  The behaviour you get
1404is:</p>
1405<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1406<li class="listitem"><p><code class="function">malloc</code>/<code class="function">new</code>/<code class="computeroutput">new[]</code>:
1407    the returned memory is marked as addressable but not having valid
1408    values.  This means you have to write to it before you can read
1409    it.</p></li>
1410<li class="listitem"><p><code class="function">calloc</code>: returned memory is marked both
1411    addressable and valid, since <code class="function">calloc</code> clears
1412    the area to zero.</p></li>
1413<li class="listitem"><p><code class="function">realloc</code>: if the new size is larger than
1414    the old, the new section is addressable but invalid, as with
1415    <code class="function">malloc</code>.  If the new size is smaller, the
1416    dropped-off section is marked as unaddressable.  You may only pass to
1417    <code class="function">realloc</code> a pointer previously issued to you by
1418    <code class="function">malloc</code>/<code class="function">calloc</code>/<code class="function">realloc</code>.</p></li>
1419<li class="listitem"><p><code class="function">free</code>/<code class="computeroutput">delete</code>/<code class="computeroutput">delete[]</code>:
1420    you may only pass to these functions a pointer previously issued
1421    to you by the corresponding allocation function.  Otherwise,
1422    Memcheck complains.  If the pointer is indeed valid, Memcheck
1423    marks the entire area it points at as unaddressable, and places
1424    the block in the freed-blocks-queue.  The aim is to defer as long
1425    as possible reallocation of this block.  Until that happens, all
1426    attempts to access it will elicit an invalid-address error, as you
1427    would hope.</p></li>
1428</ul></div>
1429</div>
1430</div>
1431<div class="sect1">
1432<div class="titlepage"><div><div><h2 class="title" style="clear: both">
1433<a name="mc-manual.monitor-commands"></a>4.6.�Memcheck Monitor Commands</h2></div></div></div>
1434<p>The Memcheck tool provides monitor commands handled by Valgrind's
1435built-in gdbserver (see <a class="xref" href="manual-core-adv.html#manual-core-adv.gdbserver-commandhandling" title="3.2.5.�Monitor command handling by the Valgrind gdbserver">Monitor command handling by the Valgrind gdbserver</a>).
1436</p>
1437<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1438<li class="listitem">
1439<p><code class="varname">xb &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
14700x804A2F0:      0x3f    0x6e    0x3f    0x65    0x3f    0x??     0x3f    0x65
1471                  ff      00
14720x804A2F8:      0x3f    0x00
1473Address 0x804A2F0 len 10 has 1 bytes unaddressable
1474(gdb)
1475</pre>
1476<p> The command xb cannot be used with registers. To get
1477      the validity bits of a register, you must start Valgrind with the
1478      option <code class="option">--vgdb-shadow-registers=yes</code>. The validity
1479      bits of a register can then be obtained by printing the 'shadow 1'
1480      corresponding register.  In the below x86 example, the register
1481      eax has all its bits undefined, while the register ebx is fully
1482      defined.
1483    </p>
1484<pre class="programlisting">
1485(gdb) p /x $eaxs1
1486$9 = 0xffffffff
1487(gdb) p /x $ebxs1
1488$10 = 0x0
1489(gdb)
1490</pre>
1491</li>
1492<li class="listitem">
1493<p><code class="varname">get_vbits &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
1510ff00ff00 ff__ff00 ff00
1511Address 0x804A2F0 len 10 has 1 bytes unaddressable
1512(gdb)
1513</pre>
1514</li>
1515<li class="listitem">
1516<p><code class="varname">make_memory
1517    [noaccess|undefined|defined|Definedifaddressable] &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
15380000ff00 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
1553Address 0x8049E28 len 1 defined
1554==14698==  Location 0x8049e28 is 0 bytes inside string10[0],
1555==14698==  declared at prog.c:10, in frame #0 of thread 1
1556(gdb)
1557</pre>
1558</li>
1559<li class="listitem">
1560<p><code class="varname">leak_check [full*|summary|xtleak]
1561                              [kinds &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>.
1836See <code class="filename">memcheck.h</code> for exact details of their
1837arguments.</p>
1838<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1839<li class="listitem"><p><code class="varname">VALGRIND_MAKE_MEM_NOACCESS</code>,
1840    <code class="varname">VALGRIND_MAKE_MEM_UNDEFINED</code> and
1841    <code class="varname">VALGRIND_MAKE_MEM_DEFINED</code>.
1842    These mark address ranges as completely inaccessible,
1843    accessible but containing undefined data, and accessible and
1844    containing defined data, respectively. They return -1, when
1845    run on Valgrind and 0 otherwise.</p></li>
1846<li class="listitem"><p><code class="varname">VALGRIND_MAKE_MEM_DEFINED_IF_ADDRESSABLE</code>.
1847    This is just like <code class="varname">VALGRIND_MAKE_MEM_DEFINED</code> but only
1848    affects those bytes that are already addressable.</p></li>
1849<li class="listitem"><p><code class="varname">VALGRIND_CHECK_MEM_IS_ADDRESSABLE</code> and
1850    <code class="varname">VALGRIND_CHECK_MEM_IS_DEFINED</code>: check immediately
1851    whether or not the given address range has the relevant property,
1852    and if not, print an error message.  Also, for the convenience of
1853    the client, returns zero if the relevant property holds; otherwise,
1854    the returned value is the address of the first byte for which the
1855    property is not true.  Always returns 0 when not run on
1856    Valgrind.</p></li>
1857<li class="listitem"><p><code class="varname">VALGRIND_CHECK_VALUE_IS_DEFINED</code>: a quick and easy
1858    way to find out whether Valgrind thinks a particular value
1859    (lvalue, to be precise) is addressable and defined.  Prints an error
1860    message if not.  It has no return value.</p></li>
1861<li class="listitem"><p><code class="varname">VALGRIND_DO_LEAK_CHECK</code>: does a full memory leak
1862    check (like <code class="option">--leak-check=full</code>) right now.
1863    This is useful for incrementally checking for leaks between arbitrary
1864    places in the program's execution.  It has no return value.</p></li>
1865<li class="listitem"><p><code class="varname">VALGRIND_DO_ADDED_LEAK_CHECK</code>: same as
1866   <code class="varname"> VALGRIND_DO_LEAK_CHECK</code> but only shows the
1867    entries for which there was an increase in leaked bytes or leaked
1868    number of blocks since the previous leak search.  It has no return
1869    value.</p></li>
1870<li class="listitem"><p><code class="varname">VALGRIND_DO_CHANGED_LEAK_CHECK</code>: same as
1871    <code class="varname">VALGRIND_DO_LEAK_CHECK</code> but only shows the
1872    entries for which there was an increase or decrease in leaked
1873    bytes or leaked number of blocks since the previous leak search. It
1874    has no return value.</p></li>
1875<li class="listitem"><p><code class="varname">VALGRIND_DO_QUICK_LEAK_CHECK</code>: like
1876    <code class="varname">VALGRIND_DO_LEAK_CHECK</code>, except it produces only a leak
1877    summary (like <code class="option">--leak-check=summary</code>).
1878    It has no return value.</p></li>
1879<li class="listitem"><p><code class="varname">VALGRIND_COUNT_LEAKS</code>: fills in the four
1880    arguments with the number of bytes of memory found by the previous
1881    leak check to be leaked (i.e. the sum of direct leaks and indirect leaks),
1882    dubious, reachable and suppressed.  This is useful in test harness code,
1883    after calling <code class="varname">VALGRIND_DO_LEAK_CHECK</code> or
1884    <code class="varname">VALGRIND_DO_QUICK_LEAK_CHECK</code>.</p></li>
1885<li class="listitem"><p><code class="varname">VALGRIND_COUNT_LEAK_BLOCKS</code>: identical to
1886    <code class="varname">VALGRIND_COUNT_LEAKS</code> except that it returns the
1887    number of blocks rather than the number of bytes in each
1888    category.</p></li>
1889<li class="listitem"><p><code class="varname">VALGRIND_GET_VBITS</code> and
1890    <code class="varname">VALGRIND_SET_VBITS</code>: allow you to get and set the
1891    V (validity) bits for an address range.  You should probably only
1892    set V bits that you have got with
1893    <code class="varname">VALGRIND_GET_VBITS</code>.  Only for those who really
1894    know what they are doing.</p></li>
1895<li class="listitem">
1896<p><code class="varname">VALGRIND_CREATE_BLOCK</code> and
1897    <code class="varname">VALGRIND_DISCARD</code>.  <code class="varname">VALGRIND_CREATE_BLOCK</code>
1898    takes an address, a number of bytes and a character string.  The
1899    specified address range is then associated with that string.  When
1900    Memcheck reports an invalid access to an address in the range, it
1901    will describe it in terms of this block rather than in terms of
1902    any other block it knows about.  Note that the use of this macro
1903    does not actually change the state of memory in any way -- it
1904    merely gives a name for the range.
1905    </p>
1906<p>At some point you may want Memcheck to stop reporting errors
1907    in terms of the block named
1908    by <code class="varname">VALGRIND_CREATE_BLOCK</code>.  To make this
1909    possible, <code class="varname">VALGRIND_CREATE_BLOCK</code> returns a
1910    "block handle", which is a C <code class="varname">int</code> value.  You
1911    can pass this block handle to <code class="varname">VALGRIND_DISCARD</code>.
1912    After doing so, Valgrind will no longer relate addressing errors
1913    in the specified range to the block.  Passing invalid handles to
1914    <code class="varname">VALGRIND_DISCARD</code> is harmless.
1915   </p>
1916</li>
1917</ul></div>
1918</div>
1919<div class="sect1">
1920<div class="titlepage"><div><div><h2 class="title" style="clear: both">
1921<a name="mc-manual.mempools"></a>4.8.�Memory Pools: describing and working with custom allocators</h2></div></div></div>
1922<p>Some programs use custom memory allocators, often for performance
1923reasons.  Left to itself, Memcheck is unable to understand the
1924behaviour of custom allocation schemes as well as it understands the
1925standard allocators, and so may miss errors and leaks in your program.  What
1926this section describes is a way to give Memcheck enough of a description of
1927your custom allocator that it can make at least some sense of what is
1928happening.</p>
1929<p>There are many different sorts of custom allocator, so Memcheck
1930attempts to reason about them using a loose, abstract model.  We
1931use the following terminology when describing custom allocation
1932systems:</p>
1933<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1934<li class="listitem"><p>Custom allocation involves a set of independent "memory pools".
1935    </p></li>
1936<li class="listitem"><p>Memcheck's notion of a a memory pool consists of a single "anchor
1937    address" and a set of non-overlapping "chunks" associated with the
1938    anchor address.</p></li>
1939<li class="listitem"><p>Typically a pool's anchor address is the address of a
1940    book-keeping "header" structure.</p></li>
1941<li class="listitem"><p>Typically the pool's chunks are drawn from a contiguous
1942    "superblock" acquired through the system
1943    <code class="function">malloc</code> or
1944    <code class="function">mmap</code>.</p></li>
1945</ul></div>
1946<p>Keep in mind that the last two points above say "typically": the
1947Valgrind mempool client request API is intentionally vague about the
1948exact structure of a mempool. There is no specific mention made of
1949headers or superblocks. Nevertheless, the following picture may help
1950elucidate the intention of the terms in the API:</p>
1951<pre class="programlisting">
1952   "pool"
1953   (anchor address)
1954   |
1955   v
1956   +--------+---+
1957   | header | o |
1958   +--------+-|-+
1959              |
1960              v                  superblock
1961              +------+---+--------------+---+------------------+
1962              |      |rzB|  allocation  |rzB|                  |
1963              +------+---+--------------+---+------------------+
1964                         ^              ^
1965                         |              |
1966                       "addr"     "addr"+"size"
1967</pre>
1968<p>
1969Note that the header and the superblock may be contiguous or
1970discontiguous, and there may be multiple superblocks associated with a
1971single header; such variations are opaque to Memcheck. The API
1972only requires that your allocation scheme can present sensible values
1973of "pool", "addr" and "size".</p>
1974<p>
1975Typically, before making client requests related to mempools, a client
1976program will have allocated such a header and superblock for their
1977mempool, and marked the superblock NOACCESS using the
1978<code class="varname">VALGRIND_MAKE_MEM_NOACCESS</code> client request.</p>
1979<p>
1980When dealing with mempools, the goal is to maintain a particular
1981invariant condition: that Memcheck believes the unallocated portions
1982of the pool's superblock (including redzones) are NOACCESS. To
1983maintain this invariant, the client program must ensure that the
1984superblock starts out in that state; Memcheck cannot make it so, since
1985Memcheck never explicitly learns about the superblock of a pool, only
1986the allocated chunks within the pool.</p>
1987<p>
1988Once the header and superblock for a pool are established and properly
1989marked, there are a number of client requests programs can use to
1990inform Memcheck about changes to the state of a mempool:</p>
1991<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
1992<li class="listitem">
1993<p>
1994    <code class="varname">VALGRIND_CREATE_MEMPOOL(pool, rzB, is_zeroed)</code>:
1995    This request registers the address <code class="varname">pool</code> as the anchor
1996    address for a memory pool. It also provides a size
1997    <code class="varname">rzB</code>, specifying how large the redzones placed around
1998    chunks allocated from the pool should be. Finally, it provides an
1999    <code class="varname">is_zeroed</code> argument that specifies whether the pool's
2000    chunks are zeroed (more precisely: defined) when allocated.
2001    </p>
2002<p>
2003    Upon completion of this request, no chunks are associated with the
2004    pool.  The request simply tells Memcheck that the pool exists, so that
2005    subsequent calls can refer to it as a pool.
2006    </p>
2007</li>
2008<li class="listitem">
2009<p>
2010      <code class="varname">VALGRIND_CREATE_MEMPOOL_EXT(pool, rzB, is_zeroed, flags)</code>:
2011      Create a memory pool with some flags (that can
2012      be OR-ed together) specifying extended behaviour.  When flags is
2013      zero, the behaviour is identical to
2014    <code class="varname">VALGRIND_CREATE_MEMPOOL</code>.</p>
2015<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
2016<li class="listitem"><p> The flag <code class="varname">VALGRIND_MEMPOOL_METAPOOL</code>
2017          specifies that the pieces of memory associated with the pool
2018          using <code class="varname">VALGRIND_MEMPOOL_ALLOC</code> will be used
2019          by the application as superblocks to dole out MALLOC_LIKE
2020          blocks using <code class="varname">VALGRIND_MALLOCLIKE_BLOCK</code>.
2021          In other words, a meta pool is a "2 levels" pool : first
2022          level is the blocks described
2023          by <code class="varname">VALGRIND_MEMPOOL_ALLOC</code>.  The second
2024          level blocks are described
2025          using <code class="varname">VALGRIND_MALLOCLIKE_BLOCK</code>.  Note
2026          that the association between the pool and the second level
2027          blocks is implicit : second level blocks will be located
2028          inside first level blocks. It is necessary to use
2029          the <code class="varname">VALGRIND_MEMPOOL_METAPOOL</code> flag for
2030          such 2 levels pools, as otherwise valgrind will detect
2031          overlapping memory blocks, and will abort execution
2032          (e.g. during leak search).
2033	</p></li>
2034<li class="listitem"><p>
2035	  <code class="varname">VALGRIND_MEMPOOL_AUTO_FREE</code>.  Such a meta
2036          pool can also be marked as an 'auto free' pool using the
2037          flag <code class="varname">VALGRIND_MEMPOOL_AUTO_FREE</code>, which
2038          must be OR-ed together with
2039          the <code class="varname">VALGRIND_MEMPOOL_METAPOOL</code>. For an
2040          'auto free' pool, <code class="varname">VALGRIND_MEMPOOL_FREE</code>
2041          will automatically free the second level blocks that are
2042          contained inside the first level block freed
2043          with <code class="varname">VALGRIND_MEMPOOL_FREE</code>.  In other
2044          words, calling <code class="varname">VALGRIND_MEMPOOL_FREE</code> will
2045          cause implicit calls
2046          to <code class="varname">VALGRIND_FREELIKE_BLOCK</code> for all the
2047          second level blocks included in the first level block.
2048          Note: it is an error to use
2049          the <code class="varname">VALGRIND_MEMPOOL_AUTO_FREE</code> flag
2050          without the
2051         <code class="varname">VALGRIND_MEMPOOL_METAPOOL</code> flag.
2052	</p></li>
2053</ul></div>
2054</li>
2055<li class="listitem"><p><code class="varname">VALGRIND_DESTROY_MEMPOOL(pool)</code>:
2056    This request tells Memcheck that a pool is being torn down. Memcheck
2057    then removes all records of chunks associated with the pool, as well
2058    as its record of the pool's existence. While destroying its records of
2059    a mempool, Memcheck resets the redzones of any live chunks in the pool
2060    to NOACCESS.
2061    </p></li>
2062<li class="listitem"><p><code class="varname">VALGRIND_MEMPOOL_ALLOC(pool, addr, size)</code>:
2063    This request informs Memcheck that a <code class="varname">size</code>-byte chunk
2064    has been allocated at <code class="varname">addr</code>, and associates the chunk with the
2065    specified
2066    <code class="varname">pool</code>. If the pool was created with nonzero
2067    <code class="varname">rzB</code> redzones, Memcheck will mark the
2068    <code class="varname">rzB</code> bytes before and after the chunk as NOACCESS. If
2069    the pool was created with the <code class="varname">is_zeroed</code> argument set,
2070    Memcheck will mark the chunk as DEFINED, otherwise Memcheck will mark
2071    the chunk as UNDEFINED.
2072    </p></li>
2073<li class="listitem"><p><code class="varname">VALGRIND_MEMPOOL_FREE(pool, addr)</code>:
2074    This request informs Memcheck that the chunk at <code class="varname">addr</code>
2075    should no longer be considered allocated. Memcheck will mark the chunk
2076    associated with <code class="varname">addr</code> as NOACCESS, and delete its
2077    record of the chunk's existence.
2078    </p></li>
2079<li class="listitem">
2080<p><code class="varname">VALGRIND_MEMPOOL_TRIM(pool, addr, size)</code>:
2081    This request trims the chunks associated with <code class="varname">pool</code>.
2082    The request only operates on chunks associated with
2083    <code class="varname">pool</code>. Trimming is formally defined as:</p>
2084<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; ">
2085<li class="listitem"><p> All chunks entirely inside the range
2086        <code class="varname">addr..(addr+size-1)</code> are preserved.</p></li>
2087<li class="listitem"><p>All chunks entirely outside the range
2088        <code class="varname">addr..(addr+size-1)</code> are discarded, as though
2089        <code class="varname">VALGRIND_MEMPOOL_FREE</code> was called on them. </p></li>
2090<li class="listitem"><p>All other chunks must intersect with the range
2091        <code class="varname">addr..(addr+size-1)</code>; areas outside the
2092        intersection are marked as NOACCESS, as though they had been
2093        independently freed with
2094        <code class="varname">VALGRIND_MEMPOOL_FREE</code>.</p></li>
2095</ul></div>
2096<p>This is a somewhat rare request, but can be useful in
2097    implementing the type of mass-free operations common in custom
2098    LIFO allocators.</p>
2099</li>
2100<li class="listitem">
2101<p><code class="varname">VALGRIND_MOVE_MEMPOOL(poolA, poolB)</code>: This
2102    request informs Memcheck that the pool previously anchored at
2103    address <code class="varname">poolA</code> has moved to anchor address
2104    <code class="varname">poolB</code>.  This is a rare request, typically only needed
2105    if you <code class="function">realloc</code> the header of a mempool.</p>
2106<p>No memory-status bits are altered by this request.</p>
2107</li>
2108<li class="listitem">
2109<p>
2110    <code class="varname">VALGRIND_MEMPOOL_CHANGE(pool, addrA, addrB,
2111    size)</code>: This request informs Memcheck that the chunk
2112    previously allocated at address <code class="varname">addrA</code> within
2113    <code class="varname">pool</code> has been moved and/or resized, and should be
2114    changed to cover the region <code class="varname">addrB..(addrB+size-1)</code>. This
2115    is a rare request, typically only needed if you
2116    <code class="function">realloc</code> a superblock or wish to extend a chunk
2117    without changing its memory-status bits.
2118    </p>
2119<p>No memory-status bits are altered by this request.
2120    </p>
2121</li>
2122<li class="listitem"><p><code class="varname">VALGRIND_MEMPOOL_EXISTS(pool)</code>:
2123    This request informs the caller whether or not Memcheck is currently
2124    tracking a mempool at anchor address <code class="varname">pool</code>. It
2125    evaluates to 1 when there is a mempool associated with that address, 0
2126    otherwise. This is a rare request, only useful in circumstances when
2127    client code might have lost track of the set of active mempools.
2128    </p></li>
2129</ul></div>
2130</div>
2131<div class="sect1">
2132<div class="titlepage"><div><div><h2 class="title" style="clear: both">
2133<a name="mc-manual.mpiwrap"></a>4.9.�Debugging MPI Parallel Programs with Valgrind</h2></div></div></div>
2134<p>Memcheck supports debugging of distributed-memory applications
2135which use the MPI message passing standard.  This support consists of a
2136library of wrapper functions for the
2137<code class="computeroutput">PMPI_*</code> interface.  When incorporated
2138into the application's address space, either by direct linking or by
2139<code class="computeroutput">LD_PRELOAD</code>, the wrappers intercept
2140calls to <code class="computeroutput">PMPI_Send</code>,
2141<code class="computeroutput">PMPI_Recv</code>, etc.  They then
2142use client requests to inform Memcheck of memory state changes caused
2143by the function being wrapped.  This reduces the number of false
2144positives that Memcheck otherwise typically reports for MPI
2145applications.</p>
2146<p>The wrappers also take the opportunity to carefully check
2147size and definedness of buffers passed as arguments to MPI functions, hence
2148detecting errors such as passing undefined data to
2149<code class="computeroutput">PMPI_Send</code>, or receiving data into a
2150buffer which is too small.</p>
2151<p>Unlike most of the rest of Valgrind, the wrapper library is subject to a
2152BSD-style license, so you can link it into any code base you like.
2153See the top of <code class="computeroutput">mpi/libmpiwrap.c</code>
2154for license details.</p>
2155<div class="sect2">
2156<div class="titlepage"><div><div><h3 class="title">
2157<a name="mc-manual.mpiwrap.build"></a>4.9.1.�Building and installing the wrappers</h3></div></div></div>
2158<p> The wrapper library will be built automatically if possible.
2159Valgrind's configure script will look for a suitable
2160<code class="computeroutput">mpicc</code> to build it with.  This must be
2161the same <code class="computeroutput">mpicc</code> you use to build the
2162MPI application you want to debug.  By default, Valgrind tries
2163<code class="computeroutput">mpicc</code>, but you can specify a
2164different one by using the configure-time option
2165<code class="option">--with-mpicc</code>.  Currently the
2166wrappers are only buildable with
2167<code class="computeroutput">mpicc</code>s which are based on GNU
2168GCC or Intel's C++ Compiler.</p>
2169<p>Check that the configure script prints a line like this:</p>
2170<pre class="programlisting">
2171checking for usable MPI2-compliant mpicc and mpi.h... yes, mpicc
2172</pre>
2173<p>If it says <code class="computeroutput">... no</code>, your
2174<code class="computeroutput">mpicc</code> has failed to compile and link
2175a test MPI2 program.</p>
2176<p>If the configure test succeeds, continue in the usual way with
2177<code class="computeroutput">make</code> and <code class="computeroutput">make
2178install</code>.  The final install tree should then contain
2179<code class="computeroutput">libmpiwrap-&lt;platform&gt;.so</code>.
2180</p>
2181<p>Compile up a test MPI program (eg, MPI hello-world) and try
2182this:</p>
2183<pre class="programlisting">
2184LD_PRELOAD=$prefix/lib/valgrind/libmpiwrap-&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">
2189valgrind MPI wrappers 31901: Active for pid 31901
2190valgrind MPI wrappers 31901: Try MPIWRAP_DEBUG=help for possible options
2191</pre>
2192<p>repeated for every process in the group.  If you do not see
2193these, there is an build/installation problem of some kind.</p>
2194<p> The MPI functions to be wrapped are assumed to be in an ELF
2195shared object with soname matching
2196<code class="computeroutput">libmpi.so*</code>.  This is known to be
2197correct at least for Open MPI and Quadrics MPI, and can easily be
2198changed if required.</p>
2199</div>
2200<div class="sect2">
2201<div class="titlepage"><div><div><h3 class="title">
2202<a name="mc-manual.mpiwrap.gettingstarted"></a>4.9.2.�Getting started</h3></div></div></div>
2203<p>Compile your MPI application as usual, taking care to link it
2204using the same <code class="computeroutput">mpicc</code> that your
2205Valgrind build was configured with.</p>
2206<p>
2207Use the following basic scheme to run your application on Valgrind with
2208the wrappers engaged:</p>
2209<pre class="programlisting">
2210MPIWRAP_DEBUG=[wrapper-args]                                  \
2211   LD_PRELOAD=$prefix/lib/valgrind/libmpiwrap-&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
2219simply link it to your application if desired.  This should not disturb
2220native behaviour of your application in any way.</p>
2221</div>
2222<div class="sect2">
2223<div class="titlepage"><div><div><h3 class="title">
2224<a name="mc-manual.mpiwrap.controlling"></a>4.9.3.�Controlling the wrapper library</h3></div></div></div>
2225<p>Environment variable
2226<code class="computeroutput">MPIWRAP_DEBUG</code> is consulted at
2227startup.  The default behaviour is to print a starting banner</p>
2228<pre class="programlisting">
2229valgrind MPI wrappers 16386: Active for pid 16386
2230valgrind MPI wrappers 16386: Try MPIWRAP_DEBUG=help for possible options
2231</pre>
2232<p> and then be relatively quiet.</p>
2233<p>You can give a list of comma-separated options in
2234<code class="computeroutput">MPIWRAP_DEBUG</code>.  These are</p>
2235<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
2236<li class="listitem"><p><code class="computeroutput">verbose</code>:
2237    show entries/exits of all wrappers.  Also show extra
2238    debugging info, such as the status of outstanding
2239    <code class="computeroutput">MPI_Request</code>s resulting
2240    from uncompleted <code class="computeroutput">MPI_Irecv</code>s.</p></li>
2241<li class="listitem"><p><code class="computeroutput">quiet</code>:
2242    opposite of <code class="computeroutput">verbose</code>, only print
2243    anything when the wrappers want
2244    to report a detected programming error, or in case of catastrophic
2245    failure of the wrappers.</p></li>
2246<li class="listitem"><p><code class="computeroutput">warn</code>:
2247    by default, functions which lack proper wrappers
2248    are not commented on, just silently
2249    ignored.  This causes a warning to be printed for each unwrapped
2250    function used, up to a maximum of three warnings per function.</p></li>
2251<li class="listitem"><p><code class="computeroutput">strict</code>:
2252    print an error message and abort the program if
2253    a function lacking a wrapper is used.</p></li>
2254</ul></div>
2255<p> If you want to use Valgrind's XML output facility
2256(<code class="option">--xml=yes</code>), you should pass
2257<code class="computeroutput">quiet</code> in
2258<code class="computeroutput">MPIWRAP_DEBUG</code> so as to get rid of any
2259extraneous printing from the wrappers.</p>
2260</div>
2261<div class="sect2">
2262<div class="titlepage"><div><div><h3 class="title">
2263<a name="mc-manual.mpiwrap.limitations.functions"></a>4.9.4.�Functions</h3></div></div></div>
2264<p>All MPI2 functions except
2265<code class="computeroutput">MPI_Wtick</code>,
2266<code class="computeroutput">MPI_Wtime</code> and
2267<code class="computeroutput">MPI_Pcontrol</code> have wrappers.  The
2268first two are not wrapped because they return a
2269<code class="computeroutput">double</code>, which Valgrind's
2270function-wrap mechanism cannot handle (but it could easily be
2271extended to do so).  <code class="computeroutput">MPI_Pcontrol</code> cannot be
2272wrapped as it has variable arity:
2273<code class="computeroutput">int MPI_Pcontrol(const int level, ...)</code></p>
2274<p>Most functions are wrapped with a default wrapper which does
2275nothing except complain or abort if it is called, depending on
2276settings in <code class="computeroutput">MPIWRAP_DEBUG</code> listed
2277above.  The following functions have "real", do-something-useful
2278wrappers:</p>
2279<pre class="programlisting">
2280PMPI_Send PMPI_Bsend PMPI_Ssend PMPI_Rsend
2281
2282PMPI_Recv PMPI_Get_count
2283
2284PMPI_Isend PMPI_Ibsend PMPI_Issend PMPI_Irsend
2285
2286PMPI_Irecv
2287PMPI_Wait PMPI_Waitall
2288PMPI_Test PMPI_Testall
2289
2290PMPI_Iprobe PMPI_Probe
2291
2292PMPI_Cancel
2293
2294PMPI_Sendrecv
2295
2296PMPI_Type_commit PMPI_Type_free
2297
2298PMPI_Pack PMPI_Unpack
2299
2300PMPI_Bcast PMPI_Gather PMPI_Scatter PMPI_Alltoall
2301PMPI_Reduce PMPI_Allreduce PMPI_Op_create
2302
2303PMPI_Comm_create PMPI_Comm_dup PMPI_Comm_free PMPI_Comm_rank PMPI_Comm_size
2304
2305PMPI_Error_string
2306PMPI_Init PMPI_Initialized PMPI_Finalize
2307</pre>
2308<p> A few functions such as
2309<code class="computeroutput">PMPI_Address</code> are listed as
2310<code class="computeroutput">HAS_NO_WRAPPER</code>.  They have no wrapper
2311at all as there is nothing worth checking, and giving a no-op wrapper
2312would reduce performance for no reason.</p>
2313<p> Note that the wrapper library itself can itself generate large
2314numbers of calls to the MPI implementation, especially when walking
2315complex types.  The most common functions called are
2316<code class="computeroutput">PMPI_Extent</code>,
2317<code class="computeroutput">PMPI_Type_get_envelope</code>,
2318<code class="computeroutput">PMPI_Type_get_contents</code>, and
2319<code class="computeroutput">PMPI_Type_free</code>.  </p>
2320</div>
2321<div class="sect2">
2322<div class="titlepage"><div><div><h3 class="title">
2323<a name="mc-manual.mpiwrap.limitations.types"></a>4.9.5.�Types</h3></div></div></div>
2324<p> MPI-1.1 structured types are supported, and walked exactly.
2325The currently supported combiners are
2326<code class="computeroutput">MPI_COMBINER_NAMED</code>,
2327<code class="computeroutput">MPI_COMBINER_CONTIGUOUS</code>,
2328<code class="computeroutput">MPI_COMBINER_VECTOR</code>,
2329<code class="computeroutput">MPI_COMBINER_HVECTOR</code>
2330<code class="computeroutput">MPI_COMBINER_INDEXED</code>,
2331<code class="computeroutput">MPI_COMBINER_HINDEXED</code> and
2332<code class="computeroutput">MPI_COMBINER_STRUCT</code>.  This should
2333cover all MPI-1.1 types.  The mechanism (function
2334<code class="computeroutput">walk_type</code>) should extend easily to
2335cover MPI2 combiners.</p>
2336<p>MPI defines some named structured types
2337(<code class="computeroutput">MPI_FLOAT_INT</code>,
2338<code class="computeroutput">MPI_DOUBLE_INT</code>,
2339<code class="computeroutput">MPI_LONG_INT</code>,
2340<code class="computeroutput">MPI_2INT</code>,
2341<code class="computeroutput">MPI_SHORT_INT</code>,
2342<code class="computeroutput">MPI_LONG_DOUBLE_INT</code>) which are pairs
2343of some basic type and a C <code class="computeroutput">int</code>.
2344Unfortunately the MPI specification makes it impossible to look inside
2345these types and see where the fields are.  Therefore these wrappers
2346assume the types are laid out as <code class="computeroutput">struct { float val;
2347int loc; }</code> (for
2348<code class="computeroutput">MPI_FLOAT_INT</code>), etc, and act
2349accordingly.  This appears to be correct at least for Open MPI 1.0.2
2350and for Quadrics MPI.</p>
2351<p>If <code class="computeroutput">strict</code> is an option specified
2352in <code class="computeroutput">MPIWRAP_DEBUG</code>, the application
2353will abort if an unhandled type is encountered.  Otherwise, the
2354application will print a warning message and continue.</p>
2355<p>Some effort is made to mark/check memory ranges corresponding to
2356arrays of values in a single pass.  This is important for performance
2357since asking Valgrind to mark/check any range, no matter how small,
2358carries quite a large constant cost.  This optimisation is applied to
2359arrays of primitive types (<code class="computeroutput">double</code>,
2360<code class="computeroutput">float</code>,
2361<code class="computeroutput">int</code>,
2362<code class="computeroutput">long</code>, <code class="computeroutput">long
2363long</code>, <code class="computeroutput">short</code>,
2364<code class="computeroutput">char</code>, and <code class="computeroutput">long
2365double</code> on platforms where <code class="computeroutput">sizeof(long
2366double) == 8</code>).  For arrays of all other types, the
2367wrappers handle each element individually and so there can be a very
2368large performance cost.</p>
2369</div>
2370<div class="sect2">
2371<div class="titlepage"><div><div><h3 class="title">
2372<a name="mc-manual.mpiwrap.writingwrappers"></a>4.9.6.�Writing new wrappers</h3></div></div></div>
2373<p>
2374For the most part the wrappers are straightforward.  The only
2375significant complexity arises with nonblocking receives.</p>
2376<p>The issue is that <code class="computeroutput">MPI_Irecv</code>
2377states the recv buffer and returns immediately, giving a handle
2378(<code class="computeroutput">MPI_Request</code>) for the transaction.
2379Later the user will have to poll for completion with
2380<code class="computeroutput">MPI_Wait</code> etc, and when the
2381transaction completes successfully, the wrappers have to paint the
2382recv buffer.  But the recv buffer details are not presented to
2383<code class="computeroutput">MPI_Wait</code> -- only the handle is.  The
2384library therefore maintains a shadow table which associates
2385uncompleted <code class="computeroutput">MPI_Request</code>s with the
2386corresponding buffer address/count/type.  When an operation completes,
2387the table is searched for the associated address/count/type info, and
2388memory is marked accordingly.</p>
2389<p>Access to the table is guarded by a (POSIX pthreads) lock, so as
2390to make the library thread-safe.</p>
2391<p>The table is allocated with
2392<code class="computeroutput">malloc</code> and never
2393<code class="computeroutput">free</code>d, so it will show up in leak
2394checks.</p>
2395<p>Writing new wrappers should be fairly easy.  The source file is
2396<code class="computeroutput">mpi/libmpiwrap.c</code>.  If possible,
2397find an existing wrapper for a function of similar behaviour to the
2398one you want to wrap, and use it as a starting point.  The wrappers
2399are organised in sections in the same order as the MPI 1.1 spec, to
2400aid navigation.  When adding a wrapper, remember to comment out the
2401definition of the default wrapper in the long list of defaults at the
2402bottom of the file (do not remove it, just comment it out).</p>
2403</div>
2404<div class="sect2">
2405<div class="titlepage"><div><div><h3 class="title">
2406<a name="mc-manual.mpiwrap.whattoexpect"></a>4.9.7.�What to expect when using the wrappers</h3></div></div></div>
2407<p>The wrappers should reduce Memcheck's false-error rate on MPI
2408applications.  Because the wrapping is done at the MPI interface,
2409there will still potentially be a large number of errors reported in
2410the MPI implementation below the interface.  The best you can do is
2411try to suppress them.</p>
2412<p>You may also find that the input-side (buffer
2413length/definedness) checks find errors in your MPI use, for example
2414passing too short a buffer to
2415<code class="computeroutput">MPI_Recv</code>.</p>
2416<p>Functions which are not wrapped may increase the false
2417error rate.  A possible approach is to run with
2418<code class="computeroutput">MPI_DEBUG</code> containing
2419<code class="computeroutput">warn</code>.  This will show you functions
2420which lack proper wrappers but which are nevertheless used.  You can
2421then write wrappers for them.
2422</p>
2423<p>A known source of potential false errors are the
2424<code class="computeroutput">PMPI_Reduce</code> family of functions, when
2425using a custom (user-defined) reduction function.  In a reduction
2426operation, each node notionally sends data to a "central point" which
2427uses the specified reduction function to merge the data items into a
2428single item.  Hence, in general, data is passed between nodes and fed
2429to the reduction function, but the wrapper library cannot mark the
2430transferred data as initialised before it is handed to the reduction
2431function, because all that happens "inside" the
2432<code class="computeroutput">PMPI_Reduce</code> call.  As a result you
2433may see false positives reported in your reduction function.</p>
2434</div>
2435</div>
2436</div>
2437<div>
2438<br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer">
2439<tr>
2440<td rowspan="2" width="40%" align="left">
2441<a accesskey="p" href="manual-core-adv.html">&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