blob: 0dbf6e98a4f074cebedec54937a081a8a79fd92e [file] [log] [blame]
njn3e986b22004-11-30 10:43:45 +00001<?xml version="1.0"?> <!-- -*- sgml -*- -->
2<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
4[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
5
de252c6142005-11-27 04:10:00 +00006
njn3e986b22004-11-30 10:43:45 +00007<book id="FAQ" xreflabel="Valgrind FAQ">
de53ad6842005-11-19 03:28:10 +00008
dee9b715c2005-08-03 20:28:33 +00009<bookinfo>
de53ad6842005-11-19 03:28:10 +000010 <title>Valgrind FAQ</title>
de53ad6842005-11-19 03:28:10 +000011 <releaseinfo>&rel-type; &rel-version; &rel-date;</releaseinfo>
de9bec93c2005-11-25 05:36:48 +000012 <copyright>
13 <year>&vg-lifespan;</year>
14 <holder><ulink url="&vg-developers;">Valgrind Developers</ulink></holder>
15 </copyright>
debad57fc2005-12-03 22:33:29 +000016 <legalnotice>
17 <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para>
18 </legalnotice>
dee9b715c2005-08-03 20:28:33 +000019</bookinfo>
njn3e986b22004-11-30 10:43:45 +000020
de53ad6842005-11-19 03:28:10 +000021
de252c6142005-11-27 04:10:00 +000022<article id="faq">
de9bec93c2005-11-25 05:36:48 +000023<title>Valgrind Frequently Asked Questions</title>
24
25
26<!-- FAQ starts here -->
27<qandaset>
28
29
30<!-- Background -->
31<qandadiv id="faq.background" xreflabel="Background">
njn3e986b22004-11-30 10:43:45 +000032<title>Background</title>
33
njn3e986b22004-11-30 10:43:45 +000034<qandaentry id="faq.pronounce">
de9bec93c2005-11-25 05:36:48 +000035 <question id="q-pronounce">
njn3e986b22004-11-30 10:43:45 +000036 <para>How do you pronounce "Valgrind"?</para>
37 </question>
de9bec93c2005-11-25 05:36:48 +000038 <answer id="a-pronounce">
debad57fc2005-12-03 22:33:29 +000039 <para>The "Val" as in the world "value". The "grind" is pronounced
40 with a short 'i' -- ie. "grinned" (rhymes with "tinned") rather than
41 "grined" (rhymes with "find").</para> <para>Don't feel bad: almost
42 everyone gets it wrong at first.</para>
njn3e986b22004-11-30 10:43:45 +000043 </answer>
44</qandaentry>
45
46<qandaentry id="faq.whence">
de9bec93c2005-11-25 05:36:48 +000047 <question id="q-whence">
njn3e986b22004-11-30 10:43:45 +000048 <para>Where does the name "Valgrind" come from?</para>
49 </question>
de9bec93c2005-11-25 05:36:48 +000050 <answer id="a-whence">
debad57fc2005-12-03 22:33:29 +000051
52 <para>From Nordic mythology. Originally (before release) the project
53 was named Heimdall, after the watchman of the Nordic gods. He could
54 "see a hundred miles by day or night, hear the grass growing, see the
55 wool growing on a sheep's back" (etc). This would have been a great
56 name, but it was already taken by a security package "Heimdal".</para>
57
58 <para>Keeping with the Nordic theme, Valgrind was chosen. Valgrind is
59 the name of the main entrance to Valhalla (the Hall of the Chosen
60 Slain in Asgard). Over this entrance there resides a wolf and over it
61 there is the head of a boar and on it perches a huge eagle, whose eyes
62 can see to the far regions of the nine worlds. Only those judged
63 worthy by the guardians are allowed to pass through Valgrind. All
64 others are refused entrance.</para>
65
66 <para>It's not short for "value grinder", although that's not a bad
67 guess.</para>
njn3e986b22004-11-30 10:43:45 +000068 </answer>
69 </qandaentry>
70
de9bec93c2005-11-25 05:36:48 +000071</qandadiv>
njn3e986b22004-11-30 10:43:45 +000072
73
de9bec93c2005-11-25 05:36:48 +000074
75<!-- Compiling, Installing and Configuring -->
76<qandadiv id="faq.installing" xreflabel="Compiling, installing and configuring">
njn3e986b22004-11-30 10:43:45 +000077<title>Compiling, installing and configuring</title>
njn3e986b22004-11-30 10:43:45 +000078
79<qandaentry id="faq.make_dies">
de9bec93c2005-11-25 05:36:48 +000080 <question id="q-make_dies">
njn3e986b22004-11-30 10:43:45 +000081 <para>When I trying building Valgrind, 'make' dies partway with
de9bec93c2005-11-25 05:36:48 +000082 an assertion failure, something like this:</para>
njn3e986b22004-11-30 10:43:45 +000083<screen>
84% make: expand.c:489: allocated_variable_append:
85 Assertion 'current_variable_set_list->next != 0' failed.
86</screen>
njn3e986b22004-11-30 10:43:45 +000087 </question>
de9bec93c2005-11-25 05:36:48 +000088 <answer id="a-make_dies">
debad57fc2005-12-03 22:33:29 +000089 <para>It's probably a bug in 'make'. Some, but not all, instances of
90 version 3.79.1 have this bug, see
91 www.mail-archive.com/bug-make@gnu.org/msg01658.html. Try upgrading to
92 a more recent version of 'make'. Alternatively, we have heard that
93 unsetting the CFLAGS environment variable avoids the problem.</para>
njn3e986b22004-11-30 10:43:45 +000094 </answer>
95</qandaentry>
96
njna874ef42006-04-06 14:04:48 +000097<qandaentry id="faq.glibc_devel">
98 <question>
99 <para>When I try to build Valgrind, 'make' fails with
100<programlisting>
101/usr/bin/ld: cannot find -lc
102collect2: ld returned 1 exit status
103</programlisting>
104 </para>
105 </question>
106 <answer>
107 <para>You need to install the glibc-static-devel package.</para>
108 </answer>
109</qandaentry>
njn3e986b22004-11-30 10:43:45 +0000110
njna874ef42006-04-06 14:04:48 +0000111</qandadiv>
njn3e986b22004-11-30 10:43:45 +0000112
113
de9bec93c2005-11-25 05:36:48 +0000114<!-- Valgrind aborts unexpectedly -->
115<qandadiv id="faq.abort" xreflabel="Valgrind aborts unexpectedly">
njn3e986b22004-11-30 10:43:45 +0000116<title>Valgrind aborts unexpectedly</title>
njn3e986b22004-11-30 10:43:45 +0000117
118<qandaentry id="faq.exit_errors">
debad57fc2005-12-03 22:33:29 +0000119 <question id="q-exit_errors">
120 <para>Programs run OK on Valgrind, but at exit produce a bunch of
121 errors involving <literal>__libc_freeres()</literal> and then die
122 with a segmentation fault.</para>
123 </question>
124 <answer id="a-exit_errors">
125 <para>When the program exits, Valgrind runs the procedure
126 <function>__libc_freeres()</function> in glibc. This is a hook for
127 memory debuggers, so they can ask glibc to free up any memory it has
128 used. Doing that is needed to ensure that Valgrind doesn't
129 incorrectly report space leaks in glibc.</para>
130
131 <para>Problem is that running <literal>__libc_freeres()</literal> in
132 older glibc versions causes this crash.</para>
133
sewardj08e31e22007-05-23 21:58:33 +0000134 <para>Workaround for 1.1.X and later versions of Valgrind: use the
debad57fc2005-12-03 22:33:29 +0000135 <option>--run-libc-freeres=no</option> flag. You may then get space
sewardj08e31e22007-05-23 21:58:33 +0000136 leak reports for glibc allocations (please don't report these to
debad57fc2005-12-03 22:33:29 +0000137 the glibc people, since they are not real leaks), but at least the
138 program runs.</para>
139 </answer>
njn3e986b22004-11-30 10:43:45 +0000140</qandaentry>
141
142<qandaentry id="faq.bugdeath">
debad57fc2005-12-03 22:33:29 +0000143 <question id="q-bugdeath">
144 <para>My (buggy) program dies like this:</para>
sewardj08e31e22007-05-23 21:58:33 +0000145<screen>valgrind: m_mallocfree.c:442 (bszW_to_pszW): Assertion 'pszW >= 0' failed.</screen>
debad57fc2005-12-03 22:33:29 +0000146 </question>
147 <answer id="a-bugdeath">
148 <para>If Memcheck (the memory checker) shows any invalid reads,
sewardj08e31e22007-05-23 21:58:33 +0000149 invalid writes or invalid frees in your program, the above may
debad57fc2005-12-03 22:33:29 +0000150 happen. Reason is that your program may trash Valgrind's low-level
151 memory manager, which then dies with the above assertion, or
sewardj08e31e22007-05-23 21:58:33 +0000152 something similar. The cure is to fix your program so that it
debad57fc2005-12-03 22:33:29 +0000153 doesn't do any illegal memory accesses. The above failure will
154 hopefully go away after that.</para>
155 </answer>
njn3e986b22004-11-30 10:43:45 +0000156</qandaentry>
157
158<qandaentry id="faq.msgdeath">
debad57fc2005-12-03 22:33:29 +0000159 <question id="q-msgdeath">
160 <para>My program dies, printing a message like this along the
njn3e986b22004-11-30 10:43:45 +0000161 way:</para>
sewardj08e31e22007-05-23 21:58:33 +0000162<screen>vex x86->IR: unhandled instruction bytes: 0x66 0xF 0x2E 0x5</screen>
debad57fc2005-12-03 22:33:29 +0000163 </question>
164 <answer id="a-msgdeath">
sewardj08e31e22007-05-23 21:58:33 +0000165 <para>Older versions did not support some x86 and amd64 instructions,
166 particularly SSE/SSE2/SSE3 instructions. Try a newer Valgrind; we now
167 support almost all instructions. If it still breaks, file a bug
168 report.</para>
njn3e986b22004-11-30 10:43:45 +0000169
debad57fc2005-12-03 22:33:29 +0000170 <para>Another possibility is that your program has a bug and
171 erroneously jumps to a non-code address, in which case you'll get a
njn1d0825f2006-03-27 11:37:07 +0000172 SIGILL signal. Memcheck may issue a warning just before
sewardj08e31e22007-05-23 21:58:33 +0000173 this happens, but it might not if the jump happens to land in
debad57fc2005-12-03 22:33:29 +0000174 addressable memory.</para>
175 </answer>
njn3e986b22004-11-30 10:43:45 +0000176</qandaentry>
177
njndde37b42005-10-06 18:58:33 +0000178<qandaentry id="faq.java">
debad57fc2005-12-03 22:33:29 +0000179 <question id="q-java">
180 <para>I tried running a Java program (or another program that uses a
181 just-in-time compiler) under Valgrind but something went wrong.
182 Does Valgrind handle such programs?</para>
183 </question>
184 <answer id="a-java">
185 <para>Valgrind can handle dynamically generated code, so long as
186 none of the generated code is later overwritten by other generated
187 code. If this happens, though, things will go wrong as Valgrind
188 will continue running its translations of the old code (this is true
sewardj08e31e22007-05-23 21:58:33 +0000189 on x86 and amd64, on PowerPC there are explicit cache flush
190 instructions which Valgrind detects and honours).
191 You should try running with
192 <option>--smc-check=all</option> in this case. Valgrind will run
debad57fc2005-12-03 22:33:29 +0000193 much more slowly, but should detect the use of the out-of-date
194 code.</para>
195
sewardj33878892007-11-17 09:43:25 +0000196 <para>Alternatively, if you have the source code to the JIT compiler
debad57fc2005-12-03 22:33:29 +0000197 you can insert calls to the
198 <computeroutput>VALGRIND_DISCARD_TRANSLATIONS</computeroutput>
199 client request to mark out-of-date code, saving you from using
200 <option>--smc-check=all</option>.</para>
201
202 <para>Apart from this, in theory Valgrind can run any Java program
203 just fine, even those that use JNI and are partially implemented in
204 other languages like C and C++. In practice, Java implementations
205 tend to do nasty things that most programs do not, and Valgrind
206 sometimes falls over these corner cases.</para>
207
208 <para>If your Java programs do not run under Valgrind, even with
209 <option>--smc-check=all</option>, please file a bug report and
210 hopefully we'll be able to fix the problem.</para>
211 </answer>
njndde37b42005-10-06 18:58:33 +0000212</qandaentry>
213
de9bec93c2005-11-25 05:36:48 +0000214</qandadiv>
njn3e986b22004-11-30 10:43:45 +0000215
216
de9bec93c2005-11-25 05:36:48 +0000217<!-- Valgrind behaves unexpectedly -->
218<qandadiv id="faq.unexpected" xreflabel="Valgrind behaves unexpectedly">
njn3e986b22004-11-30 10:43:45 +0000219<title>Valgrind behaves unexpectedly</title>
njn3e986b22004-11-30 10:43:45 +0000220
njn3e986b22004-11-30 10:43:45 +0000221<qandaentry id="faq.reports">
debad57fc2005-12-03 22:33:29 +0000222 <question id="q-reports">
223 <para>My program uses the C++ STL and string classes. Valgrind
224 reports 'still reachable' memory leaks involving these classes at
225 the exit of the program, but there should be none.</para>
226 </question>
227 <answer id="a-reports">
228 <para>First of all: relax, it's probably not a bug, but a feature.
229 Many implementations of the C++ standard libraries use their own
230 memory pool allocators. Memory for quite a number of destructed
231 objects is not immediately freed and given back to the OS, but kept
232 in the pool(s) for later re-use. The fact that the pools are not
233 freed at the exit() of the program cause Valgrind to report this
234 memory as still reachable. The behaviour not to free pools at the
235 exit() could be called a bug of the library though.</para>
njn3e986b22004-11-30 10:43:45 +0000236
debad57fc2005-12-03 22:33:29 +0000237 <para>Using gcc, you can force the STL to use malloc and to free
238 memory as soon as possible by globally disabling memory caching.
239 Beware! Doing so will probably slow down your program, sometimes
240 drastically.</para>
241 <itemizedlist>
242 <listitem>
243 <para>With gcc 2.91, 2.95, 3.0 and 3.1, compile all source using
sewardj08e31e22007-05-23 21:58:33 +0000244 the STL with <literal>-D__USE_MALLOC</literal>. Beware! This was
debad57fc2005-12-03 22:33:29 +0000245 removed from gcc starting with version 3.3.</para>
246 </listitem>
247 <listitem>
248 <para>With gcc 3.2.2 and later, you should export the
249 environment variable <literal>GLIBCPP_FORCE_NEW</literal> before
250 running your program.</para>
251 </listitem>
252 <listitem>
253 <para>With gcc 3.4 and later, that variable has changed name to
254 <literal>GLIBCXX_FORCE_NEW</literal>.</para>
255 </listitem>
256 </itemizedlist>
njn3e986b22004-11-30 10:43:45 +0000257
debad57fc2005-12-03 22:33:29 +0000258 <para>There are other ways to disable memory pooling: using the
259 <literal>malloc_alloc</literal> template with your objects (not
260 portable, but should work for gcc) or even writing your own memory
261 allocators. But all this goes beyond the scope of this FAQ. Start
262 by reading
sewardj08e31e22007-05-23 21:58:33 +0000263 <ulink
264 url="http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html#4_4_leak">
265 http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html#4_4_leak</ulink> if
266 you absolutely want to do that. But beware:
267 allocators belong to the more messy parts of the STL and
268 people went to great lengths to make the STL portable across
269 platforms. Chances are good that your solution will work on your
270 platform, but not on others.</para>
njn3e986b22004-11-30 10:43:45 +0000271 </answer>
272</qandaentry>
273
274
275<qandaentry id="faq.unhelpful">
debad57fc2005-12-03 22:33:29 +0000276 <question id="q-unhelpful">
277 <para>The stack traces given by Memcheck (or another tool) aren't
278 helpful. How can I improve them?</para>
279 </question>
280 <answer id="a-unhelpful">
281 <para>If they're not long enough, use <option>--num-callers</option>
282 to make them longer.</para>
njn3e986b22004-11-30 10:43:45 +0000283
debad57fc2005-12-03 22:33:29 +0000284 <para>If they're not detailed enough, make sure you are compiling
285 with <option>-g</option> to add debug information. And don't strip
286 symbol tables (programs should be unstripped unless you run 'strip'
287 on them; some libraries ship stripped).</para>
njn0211ff32005-05-15 14:49:24 +0000288
debad57fc2005-12-03 22:33:29 +0000289 <para>Also, for leak reports involving shared objects, if the shared
290 object is unloaded before the program terminates, Valgrind will
291 discard the debug information and the error message will be full of
292 <literal>???</literal> entries. The workaround here is to avoid
293 calling dlclose() on these shared objects.</para>
294
295 <para>Also, <option>-fomit-frame-pointer</option> and
296 <option>-fstack-check</option> can make stack traces worse.</para>
njn3e986b22004-11-30 10:43:45 +0000297
298 <para>Some example sub-traces:</para>
299
njn15d7c342005-09-30 01:43:32 +0000300 <itemizedlist>
301 <listitem>
302 <para>With debug information and unstripped (best):</para>
njn3e986b22004-11-30 10:43:45 +0000303<programlisting>
304Invalid write of size 1
305 at 0x80483BF: really (malloc1.c:20)
306 by 0x8048370: main (malloc1.c:9)
307</programlisting>
njn15d7c342005-09-30 01:43:32 +0000308 </listitem>
njn3e986b22004-11-30 10:43:45 +0000309
njn15d7c342005-09-30 01:43:32 +0000310 <listitem>
311 <para>With no debug information, unstripped:</para>
njn3e986b22004-11-30 10:43:45 +0000312<programlisting>
313Invalid write of size 1
314 at 0x80483BF: really (in /auto/homes/njn25/grind/head5/a.out)
315 by 0x8048370: main (in /auto/homes/njn25/grind/head5/a.out)
316</programlisting>
njn15d7c342005-09-30 01:43:32 +0000317 </listitem>
njn3e986b22004-11-30 10:43:45 +0000318
njn15d7c342005-09-30 01:43:32 +0000319 <listitem>
320 <para>With no debug information, stripped:</para>
njn3e986b22004-11-30 10:43:45 +0000321<programlisting>
322Invalid write of size 1
323 at 0x80483BF: (within /auto/homes/njn25/grind/head5/a.out)
324 by 0x8048370: (within /auto/homes/njn25/grind/head5/a.out)
325 by 0x42015703: __libc_start_main (in /lib/tls/libc-2.3.2.so)
326 by 0x80482CC: (within /auto/homes/njn25/grind/head5/a.out)
327</programlisting>
njn15d7c342005-09-30 01:43:32 +0000328 </listitem>
njn3e986b22004-11-30 10:43:45 +0000329
njn15d7c342005-09-30 01:43:32 +0000330 <listitem>
331 <para>With debug information and -fomit-frame-pointer:</para>
njn3e986b22004-11-30 10:43:45 +0000332<programlisting>
333Invalid write of size 1
334 at 0x80483C4: really (malloc1.c:20)
335 by 0x42015703: __libc_start_main (in /lib/tls/libc-2.3.2.so)
336 by 0x80482CC: ??? (start.S:81)
337</programlisting>
njn15d7c342005-09-30 01:43:32 +0000338 </listitem>
njn3e986b22004-11-30 10:43:45 +0000339
njn15d7c342005-09-30 01:43:32 +0000340 <listitem>
341 <para>A leak error message involving an unloaded shared object:</para>
njn0211ff32005-05-15 14:49:24 +0000342<programlisting>
34384 bytes in 1 blocks are possibly lost in loss record 488 of 713
344 at 0x1B9036DA: operator new(unsigned) (vg_replace_malloc.c:132)
345 by 0x1DB63EEB: ???
346 by 0x1DB4B800: ???
347 by 0x1D65E007: ???
348 by 0x8049EE6: main (main.cpp:24)
349</programlisting>
njn15d7c342005-09-30 01:43:32 +0000350 </listitem>
351 </itemizedlist>
njn0211ff32005-05-15 14:49:24 +0000352
njn3e986b22004-11-30 10:43:45 +0000353 </answer>
354</qandaentry>
355
njn16eeb4e2005-06-16 03:56:58 +0000356<qandaentry id="faq.aliases">
debad57fc2005-12-03 22:33:29 +0000357 <question id="q-aliases">
358 <para>The stack traces given by Memcheck (or another tool) seem to
359 have the wrong function name in them. What's happening?</para>
360 </question>
361 <answer id="a-aliases">
362 <para>Occasionally Valgrind stack traces get the wrong function
363 names. This is caused by glibc using aliases to effectively give
364 one function two names. Most of the time Valgrind chooses a
365 suitable name, but very occasionally it gets it wrong. Examples we
366 know of are printing 'bcmp' instead of 'memcmp', 'index' instead of
367 'strchr', and 'rindex' instead of 'strrchr'.</para>
368 </answer>
njn16eeb4e2005-06-16 03:56:58 +0000369</qandaentry>
370
njn6e9a3df2007-09-25 22:05:04 +0000371
372<qandaentry id="faq.crashes">
373 <question id="q-crashes">
374 <para>My program crashes normally, but doesn't under Valgrind, or vice
375 versa. What's happening?</para>
376 </question>
377 <answer id="a-crashes">
378 <para>When a program runs under Valgrind, its environment is slightly
379 different to when it runs natively. For example, the memory layout is
380 different, and the way that threads are scheduled is different.</para>
381
382 <para>Most of the time this doesn't make any difference, but it can,
383 particularly if your program is buggy. For example, if your program
384 crashes because it erroneously accesses memory that is unaddressable,
385 it's possible that this memory will not be unaddressable when run under
386 Valgrind. Alternatively, if your program has data races, these may not
387 manifest under Valgrind.</para>
388
389 <para>There isn't anything you can do to change this, it's just the
390 nature of the way Valgrind works that it cannot exactly replicate a
391 native execution environment. In the case where your program crashes
392 due to a memory error when run natively but not when run under Valgrind,
393 in most cases Memcheck should identify the bad memory operation.</para>.
394 </answer>
395</qandaentry>
396
de9bec93c2005-11-25 05:36:48 +0000397</qandadiv>
njn3e986b22004-11-30 10:43:45 +0000398
399
de9bec93c2005-11-25 05:36:48 +0000400
401<!-- Memcheck doesn't find my bug -->
402<qandadiv id="faq.notfound" xreflabel="Memcheck doesn't find my bug">
njn3e986b22004-11-30 10:43:45 +0000403<title>Memcheck doesn't find my bug</title>
njn3e986b22004-11-30 10:43:45 +0000404
405<qandaentry id="faq.hiddenbug">
debad57fc2005-12-03 22:33:29 +0000406 <question id="q-hiddenbug">
407 <para>I try running "valgrind --tool=memcheck my_program" and get
408 Valgrind's startup message, but I don't get any errors and I know my
409 program has errors.</para>
410 </question>
411 <answer id="a-hiddenbug">
412 <para>There are two possible causes of this.</para>
njna11b9b02005-03-27 17:05:08 +0000413
debad57fc2005-12-03 22:33:29 +0000414 <para>First, by default, Valgrind only traces the top-level process.
415 So if your program spawns children, they won't be traced by Valgrind
416 by default. Also, if your program is started by a shell script,
417 Perl script, or something similar, Valgrind will trace the shell, or
418 the Perl interpreter, or equivalent.</para>
njn3e986b22004-11-30 10:43:45 +0000419
debad57fc2005-12-03 22:33:29 +0000420 <para>To trace child processes, use the
421 <option>--trace-children=yes</option> option.</para>
njn3e986b22004-11-30 10:43:45 +0000422
debad57fc2005-12-03 22:33:29 +0000423 <para>If you are tracing large trees of processes, it can be less
424 disruptive to have the output sent over the network. Give Valgrind
425 the flag <option>--log-socket=127.0.0.1:12345</option> (if you want
sewardj08e31e22007-05-23 21:58:33 +0000426 logging output sent to port <literal>12345</literal> on
debad57fc2005-12-03 22:33:29 +0000427 <literal>localhost</literal>). You can use the valgrind-listener
428 program to listen on that port:</para>
njn3e986b22004-11-30 10:43:45 +0000429<programlisting>
430valgrind-listener 12345
431</programlisting>
432
debad57fc2005-12-03 22:33:29 +0000433 <para>Obviously you have to start the listener process first. See
434 the manual for more details.</para>
njna11b9b02005-03-27 17:05:08 +0000435
debad57fc2005-12-03 22:33:29 +0000436 <para>Second, if your program is statically linked, most Valgrind
437 tools won't work as well, because they won't be able to replace
438 certain functions, such as malloc(), with their own versions. A key
439 indicator of this is if Memcheck says:
njna11b9b02005-03-27 17:05:08 +0000440<programlisting>
njn5666ee62005-12-19 19:38:02 +0000441All heap blocks were freed -- no leaks are possible
njna11b9b02005-03-27 17:05:08 +0000442</programlisting>
debad57fc2005-12-03 22:33:29 +0000443 when you know your program calls malloc(). The workaround is to
444 avoid statically linking your program.</para>
445 </answer>
njn3e986b22004-11-30 10:43:45 +0000446</qandaentry>
447
448
449<qandaentry id="faq.overruns">
debad57fc2005-12-03 22:33:29 +0000450 <question id="q-overruns">
451 <para>Why doesn't Memcheck find the array overruns in this
452 program?</para>
njn3e986b22004-11-30 10:43:45 +0000453<programlisting>
454int static[5];
455
456int main(void)
457{
458 int stack[5];
459
460 static[5] = 0;
461 stack [5] = 0;
462
463 return 0;
464}
465</programlisting>
debad57fc2005-12-03 22:33:29 +0000466 </question>
467 <answer id="a-overruns">
468 <para>Unfortunately, Memcheck doesn't do bounds checking on static
469 or stack arrays. We'd like to, but it's just not possible to do in
470 a reasonable way that fits with how Memcheck works. Sorry.</para>
471 </answer>
njn3e986b22004-11-30 10:43:45 +0000472</qandaentry>
473
de9bec93c2005-11-25 05:36:48 +0000474</qandadiv>
njn3e986b22004-11-30 10:43:45 +0000475
476
de9bec93c2005-11-25 05:36:48 +0000477
478<!-- Miscellaneous -->
479<qandadiv id="faq.misc" xreflabel="Miscellaneous">
njn3e986b22004-11-30 10:43:45 +0000480<title>Miscellaneous</title>
njn3e986b22004-11-30 10:43:45 +0000481
482<qandaentry id="faq.writesupp">
debad57fc2005-12-03 22:33:29 +0000483 <question id="q-writesupp">
484 <para>I tried writing a suppression but it didn't work. Can you
485 write my suppression for me?</para>
486 </question>
487 <answer id="a-writesupp">
488 <para>Yes! Use the <option>--gen-suppressions=yes</option> feature
489 to spit out suppressions automatically for you. You can then edit
490 them if you like, eg. combining similar automatically generated
491 suppressions using wildcards like <literal>'*'</literal>.</para>
njn3e986b22004-11-30 10:43:45 +0000492
debad57fc2005-12-03 22:33:29 +0000493 <para>If you really want to write suppressions by hand, read the
494 manual carefully. Note particularly that C++ function names must be
sewardj08e31e22007-05-23 21:58:33 +0000495 mangled (that is, not demangled).</para>
debad57fc2005-12-03 22:33:29 +0000496 </answer>
njn3e986b22004-11-30 10:43:45 +0000497</qandaentry>
498
499
500<qandaentry id="faq.deflost">
debad57fc2005-12-03 22:33:29 +0000501 <question id="q-deflost">
njn1d0825f2006-03-27 11:37:07 +0000502 <para>With Memcheck's memory leak detector, what's the
debad57fc2005-12-03 22:33:29 +0000503 difference between "definitely lost", "possibly lost", "still
504 reachable", and "suppressed"?</para>
505 </question>
506 <answer id="a-deflost">
507 <para>The details are in the Memcheck section of the user
508 manual.</para>
njn3e986b22004-11-30 10:43:45 +0000509
debad57fc2005-12-03 22:33:29 +0000510 <para>In short:</para>
511 <itemizedlist>
512 <listitem>
513 <para>"definitely lost" means your program is leaking memory --
514 fix it!</para>
515 </listitem>
516 <listitem>
517 <para>"possibly lost" means your program is probably leaking
518 memory, unless you're doing funny things with pointers.</para>
519 </listitem>
520 <listitem>
521 <para>"still reachable" means your program is probably ok -- it
522 didn't free some memory it could have. This is quite common and
523 often reasonable. Don't use
524 <option>--show-reachable=yes</option> if you don't want to see
525 these reports.</para>
526 </listitem>
527 <listitem>
528 <para>"suppressed" means that a leak error has been suppressed.
529 There are some suppressions in the default suppression files.
530 You can ignore suppressed errors.</para>
531 </listitem>
532 </itemizedlist>
533 </answer>
njn3e986b22004-11-30 10:43:45 +0000534</qandaentry>
535
njn3fdb3622006-10-20 22:16:57 +0000536<qandaentry id="faq.undeferrors">
537 <question id="q-undeferrors">
538 <para>Memcheck's uninitialised value errors are hard to track down,
539 because they are often reported some time after they are caused. Could
540 Memcheck record a trail of operations to better link the cause to the
541 effect? Or maybe just eagerly report any copies of uninitialised
542 memory values?</para>
543 </question>
544 <answer id="a-undeferrors">
545 <para>We'd love to improve these errors, but we don't know how to do it
546 without huge performance penalties.</para>
547
548 <para>You can use the client request
549 <computeroutput>VALGRIND_CHECK_VALUE_IS_DEFINED</computeroutput> to help
550 track these errors down -- work backwards from the point where the
551 uninitialised error occurs, checking suspect values until you find the
552 cause. This requires editing, compiling and re-running your program
553 multiple times, which is a pain, but still easier than debugging the
554 problem without Memcheck's help.</para>
555
556 <para>As for eager reporting of copies of uninitialised memory values,
557 this has been suggested multiple times. Unfortunately, almost all
sewardj33878892007-11-17 09:43:25 +0000558 programs legitimately copy uninitialised memory values around (because
njn3fdb3622006-10-20 22:16:57 +0000559 compilers pad structs to preserve alignment) and eager checking leads to
560 hundreds of false positives. Therefore Memcheck does not support eager
561 checking at this time.</para>
562 </answer>
563</qandaentry>
564
565
de9bec93c2005-11-25 05:36:48 +0000566</qandadiv>
njn3e986b22004-11-30 10:43:45 +0000567
de9bec93c2005-11-25 05:36:48 +0000568
569
570<!-- Further Assistance -->
571<qandadiv id="faq.help" xreflabel="How To Get Further Assistance">
572<title>How To Get Further Assistance</title>
573
574<qandaentry id="e-help">
debad57fc2005-12-03 22:33:29 +0000575 <!-- <question><para/></question> -->
576 <answer id="a-help">
de9bec93c2005-11-25 05:36:48 +0000577 <para>Please read all of this section before posting.</para>
578
579 <para>If you think an answer is incomplete or inaccurate, please
580 e-mail <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink>.</para>
debad57fc2005-12-03 22:33:29 +0000581
de97ab7e72005-11-27 18:19:40 +0000582 <para>Read the appropriate section(s) of the
583 <ulink url="&vg-bookset;">Valgrind Documentation</ulink>.</para>
de9bec93c2005-11-25 05:36:48 +0000584
de97ab7e72005-11-27 18:19:40 +0000585 <para>Read the
586 <ulink url="&vg-dist-docs;">Distribution Documents</ulink>.</para>
de9bec93c2005-11-25 05:36:48 +0000587
588 <para><ulink url="http://search.gmane.org">Search</ulink> the
589 <ulink url="http://news.gmane.org/gmane.comp.debugging.valgrind">valgrind-users</ulink> mailing list archives, using the group name
590 <computeroutput>gmane.comp.debugging.valgrind</computeroutput>.</para>
591
debad57fc2005-12-03 22:33:29 +0000592 <para>Only when you have tried all of these things and are still
593 stuck, should you post to the
594 <ulink url="&vg-users-list;">valgrind-users mailing list</ulink>. In
595 which case, please read the following carefully. Making a complete
596 posting will greatly increase the chances that an expert or fellow
597 user reading it will have enough information and motivation to
598 reply.</para>
de9bec93c2005-11-25 05:36:48 +0000599
debad57fc2005-12-03 22:33:29 +0000600 <para>Make sure you give full details of the problem, including the
njn1ac2f0d2005-12-04 19:26:00 +0000601 full output of <computeroutput>valgrind -v &lt;your-prog&gt;</computeroutput>, if
debad57fc2005-12-03 22:33:29 +0000602 applicable. Also which Linux distribution you're using (Red Hat,
603 Debian, etc) and its version number.</para>
de9bec93c2005-11-25 05:36:48 +0000604
debad57fc2005-12-03 22:33:29 +0000605 <para>You are in little danger of making your posting too long unless
606 you include large chunks of Valgrind's (unsuppressed) output, so err
607 on the side of giving too much information.</para>
de9bec93c2005-11-25 05:36:48 +0000608
debad57fc2005-12-03 22:33:29 +0000609 <para>Clearly written subject lines and message bodies are
610 appreciated, too.</para>
de9bec93c2005-11-25 05:36:48 +0000611
612 <para>Finally, remember that, despite the fact that most of the
debad57fc2005-12-03 22:33:29 +0000613 community are very helpful and responsive to emailed questions, you
614 are probably requesting help from unpaid volunteers, so you have no
615 guarantee of receiving an answer.</para>
de9bec93c2005-11-25 05:36:48 +0000616</answer>
617
618</qandaentry>
619</qandadiv>
620
621
622<!-- FAQ ends here -->
njn3e986b22004-11-30 10:43:45 +0000623</qandaset>
de9bec93c2005-11-25 05:36:48 +0000624
njn3e986b22004-11-30 10:43:45 +0000625
626
627<!-- template
de9bec93c2005-11-25 05:36:48 +0000628<qandadiv id="faq.installing" xreflabel="Installing">
629<title>Installing</title>
njn3e986b22004-11-30 10:43:45 +0000630
de9bec93c2005-11-25 05:36:48 +0000631<qandaentry id="faq.problem">
632 <question id="q-problem">
njn3e986b22004-11-30 10:43:45 +0000633 <para></para>
634 </question>
de9bec93c2005-11-25 05:36:48 +0000635 <answer id="a-problem">
njn3e986b22004-11-30 10:43:45 +0000636 <para></para>
637 </answer>
638</qandaentry>
639
de9bec93c2005-11-25 05:36:48 +0000640</qandadiv>
njn3e986b22004-11-30 10:43:45 +0000641-->
642
de9bec93c2005-11-25 05:36:48 +0000643</article>
njn3e986b22004-11-30 10:43:45 +0000644
645</book>