blob: 07f3f1a5d5a758b39c44a220fe6ddc85ab7a617b [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>
njnb8329f02009-04-16 00:33:20 +0000145<screen>valgrind: m_mallocfree.c:248 (get_bszB_as_is): Assertion 'bszB_lo == bszB_hi' failed.</screen>
146 <para>or like this:</para>
147<screen>valgrind: m_mallocfree.c:442 (mk_inuse_bszB): Assertion 'bszB != 0' failed.</screen>
njn557bb832009-05-18 23:03:52 +0000148 <para>or otherwise aborts or crashes in m_mallocfree.c.</para>
njnb8329f02009-04-16 00:33:20 +0000149
debad57fc2005-12-03 22:33:29 +0000150 </question>
151 <answer id="a-bugdeath">
152 <para>If Memcheck (the memory checker) shows any invalid reads,
sewardj08e31e22007-05-23 21:58:33 +0000153 invalid writes or invalid frees in your program, the above may
debad57fc2005-12-03 22:33:29 +0000154 happen. Reason is that your program may trash Valgrind's low-level
155 memory manager, which then dies with the above assertion, or
sewardj08e31e22007-05-23 21:58:33 +0000156 something similar. The cure is to fix your program so that it
debad57fc2005-12-03 22:33:29 +0000157 doesn't do any illegal memory accesses. The above failure will
158 hopefully go away after that.</para>
159 </answer>
njn3e986b22004-11-30 10:43:45 +0000160</qandaentry>
161
162<qandaentry id="faq.msgdeath">
debad57fc2005-12-03 22:33:29 +0000163 <question id="q-msgdeath">
164 <para>My program dies, printing a message like this along the
njn3e986b22004-11-30 10:43:45 +0000165 way:</para>
sewardj08e31e22007-05-23 21:58:33 +0000166<screen>vex x86->IR: unhandled instruction bytes: 0x66 0xF 0x2E 0x5</screen>
debad57fc2005-12-03 22:33:29 +0000167 </question>
168 <answer id="a-msgdeath">
njnb8329f02009-04-16 00:33:20 +0000169 <para>One possibility is that your program has a bug and erroneously
170 jumps to a non-code address, in which case you'll get a SIGILL signal.
171 Memcheck may issue a warning just before this happens, but it might not
172 if the jump happens to land in addressable memory.</para>
173
174 <para>Another possibility is that Valgrind does not handle the
175 instruction. If you are using an older Valgrind, a newer version might
176 handle the instruction. However, all instruction sets have some
177 obscure, rarely used instructions. Also, on amd64 there are an almost
178 limitless number of combinations of redundant instruction prefixes, many
179 of them undocumented but accepted by CPUs. So Valgrind will still have
180 decoding failures from time to time. If this happens, please file a bug
sewardj08e31e22007-05-23 21:58:33 +0000181 report.</para>
njn7316df22009-08-04 01:16:01 +0000182 </answer>
183</qandaentry>
184
185<qandaentry id="faq.bss">
186 <question id="q-bss">
187 <para>My program fails to start, and this message is printed:</para>
188<screen></screen>
189 </question>
190 <answer id="a-bss">
191 <para>One possibility is that your program has a bug and erroneously
192 jumps to a non-code address, in which case you'll get a SIGILL signal.
193 Memcheck may issue a warning just before this happens, but it might not
194 if the jump happens to land in addressable memory.</para>
195
196 <para>Another possibility is that Valgrind does not handle the
197 instruction. If you are using an older Valgrind, a newer version might
198 handle the instruction. However, all instruction sets have some
199 obscure, rarely used instructions. Also, on amd64 there are an almost
200 limitless number of combinations of redundant instruction prefixes, many
201 of them undocumented but accepted by CPUs. So Valgrind will still have
202 decoding failures from time to time. If this happens, please file a bug
203 report.</para>
njn3e986b22004-11-30 10:43:45 +0000204
debad57fc2005-12-03 22:33:29 +0000205 </answer>
njn3e986b22004-11-30 10:43:45 +0000206</qandaentry>
207
njndde37b42005-10-06 18:58:33 +0000208<qandaentry id="faq.java">
debad57fc2005-12-03 22:33:29 +0000209 <question id="q-java">
210 <para>I tried running a Java program (or another program that uses a
211 just-in-time compiler) under Valgrind but something went wrong.
212 Does Valgrind handle such programs?</para>
213 </question>
214 <answer id="a-java">
215 <para>Valgrind can handle dynamically generated code, so long as
216 none of the generated code is later overwritten by other generated
217 code. If this happens, though, things will go wrong as Valgrind
218 will continue running its translations of the old code (this is true
sewardj08e31e22007-05-23 21:58:33 +0000219 on x86 and amd64, on PowerPC there are explicit cache flush
220 instructions which Valgrind detects and honours).
221 You should try running with
222 <option>--smc-check=all</option> in this case. Valgrind will run
debad57fc2005-12-03 22:33:29 +0000223 much more slowly, but should detect the use of the out-of-date
224 code.</para>
225
sewardj33878892007-11-17 09:43:25 +0000226 <para>Alternatively, if you have the source code to the JIT compiler
debad57fc2005-12-03 22:33:29 +0000227 you can insert calls to the
228 <computeroutput>VALGRIND_DISCARD_TRANSLATIONS</computeroutput>
229 client request to mark out-of-date code, saving you from using
230 <option>--smc-check=all</option>.</para>
231
232 <para>Apart from this, in theory Valgrind can run any Java program
233 just fine, even those that use JNI and are partially implemented in
234 other languages like C and C++. In practice, Java implementations
235 tend to do nasty things that most programs do not, and Valgrind
236 sometimes falls over these corner cases.</para>
237
238 <para>If your Java programs do not run under Valgrind, even with
239 <option>--smc-check=all</option>, please file a bug report and
240 hopefully we'll be able to fix the problem.</para>
241 </answer>
njndde37b42005-10-06 18:58:33 +0000242</qandaentry>
243
de9bec93c2005-11-25 05:36:48 +0000244</qandadiv>
njn3e986b22004-11-30 10:43:45 +0000245
246
de9bec93c2005-11-25 05:36:48 +0000247<!-- Valgrind behaves unexpectedly -->
248<qandadiv id="faq.unexpected" xreflabel="Valgrind behaves unexpectedly">
njn3e986b22004-11-30 10:43:45 +0000249<title>Valgrind behaves unexpectedly</title>
njn3e986b22004-11-30 10:43:45 +0000250
njn3e986b22004-11-30 10:43:45 +0000251<qandaentry id="faq.reports">
debad57fc2005-12-03 22:33:29 +0000252 <question id="q-reports">
253 <para>My program uses the C++ STL and string classes. Valgrind
254 reports 'still reachable' memory leaks involving these classes at
255 the exit of the program, but there should be none.</para>
256 </question>
257 <answer id="a-reports">
258 <para>First of all: relax, it's probably not a bug, but a feature.
259 Many implementations of the C++ standard libraries use their own
260 memory pool allocators. Memory for quite a number of destructed
261 objects is not immediately freed and given back to the OS, but kept
262 in the pool(s) for later re-use. The fact that the pools are not
263 freed at the exit() of the program cause Valgrind to report this
264 memory as still reachable. The behaviour not to free pools at the
265 exit() could be called a bug of the library though.</para>
njn3e986b22004-11-30 10:43:45 +0000266
njn7316df22009-08-04 01:16:01 +0000267 <para>Using GCC, you can force the STL to use malloc and to free
debad57fc2005-12-03 22:33:29 +0000268 memory as soon as possible by globally disabling memory caching.
269 Beware! Doing so will probably slow down your program, sometimes
270 drastically.</para>
271 <itemizedlist>
272 <listitem>
njn7316df22009-08-04 01:16:01 +0000273 <para>With GCC 2.91, 2.95, 3.0 and 3.1, compile all source using
sewardj08e31e22007-05-23 21:58:33 +0000274 the STL with <literal>-D__USE_MALLOC</literal>. Beware! This was
njn7316df22009-08-04 01:16:01 +0000275 removed from GCC starting with version 3.3.</para>
debad57fc2005-12-03 22:33:29 +0000276 </listitem>
277 <listitem>
njn7316df22009-08-04 01:16:01 +0000278 <para>With GCC 3.2.2 and later, you should export the
debad57fc2005-12-03 22:33:29 +0000279 environment variable <literal>GLIBCPP_FORCE_NEW</literal> before
280 running your program.</para>
281 </listitem>
282 <listitem>
njn7316df22009-08-04 01:16:01 +0000283 <para>With GCC 3.4 and later, that variable has changed name to
debad57fc2005-12-03 22:33:29 +0000284 <literal>GLIBCXX_FORCE_NEW</literal>.</para>
285 </listitem>
286 </itemizedlist>
njn3e986b22004-11-30 10:43:45 +0000287
debad57fc2005-12-03 22:33:29 +0000288 <para>There are other ways to disable memory pooling: using the
289 <literal>malloc_alloc</literal> template with your objects (not
njn7316df22009-08-04 01:16:01 +0000290 portable, but should work for GCC) or even writing your own memory
debad57fc2005-12-03 22:33:29 +0000291 allocators. But all this goes beyond the scope of this FAQ. Start
292 by reading
sewardj08e31e22007-05-23 21:58:33 +0000293 <ulink
294 url="http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html#4_4_leak">
295 http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html#4_4_leak</ulink> if
296 you absolutely want to do that. But beware:
297 allocators belong to the more messy parts of the STL and
298 people went to great lengths to make the STL portable across
299 platforms. Chances are good that your solution will work on your
300 platform, but not on others.</para>
njn3e986b22004-11-30 10:43:45 +0000301 </answer>
302</qandaentry>
303
304
305<qandaentry id="faq.unhelpful">
debad57fc2005-12-03 22:33:29 +0000306 <question id="q-unhelpful">
307 <para>The stack traces given by Memcheck (or another tool) aren't
308 helpful. How can I improve them?</para>
309 </question>
310 <answer id="a-unhelpful">
311 <para>If they're not long enough, use <option>--num-callers</option>
312 to make them longer.</para>
njn3e986b22004-11-30 10:43:45 +0000313
debad57fc2005-12-03 22:33:29 +0000314 <para>If they're not detailed enough, make sure you are compiling
315 with <option>-g</option> to add debug information. And don't strip
316 symbol tables (programs should be unstripped unless you run 'strip'
317 on them; some libraries ship stripped).</para>
njn0211ff32005-05-15 14:49:24 +0000318
debad57fc2005-12-03 22:33:29 +0000319 <para>Also, for leak reports involving shared objects, if the shared
320 object is unloaded before the program terminates, Valgrind will
321 discard the debug information and the error message will be full of
322 <literal>???</literal> entries. The workaround here is to avoid
323 calling dlclose() on these shared objects.</para>
324
325 <para>Also, <option>-fomit-frame-pointer</option> and
326 <option>-fstack-check</option> can make stack traces worse.</para>
njn3e986b22004-11-30 10:43:45 +0000327
328 <para>Some example sub-traces:</para>
329
njn15d7c342005-09-30 01:43:32 +0000330 <itemizedlist>
331 <listitem>
332 <para>With debug information and unstripped (best):</para>
njn3e986b22004-11-30 10:43:45 +0000333<programlisting>
334Invalid write of size 1
335 at 0x80483BF: really (malloc1.c:20)
336 by 0x8048370: main (malloc1.c:9)
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>With no debug information, unstripped:</para>
njn3e986b22004-11-30 10:43:45 +0000342<programlisting>
343Invalid write of size 1
344 at 0x80483BF: really (in /auto/homes/njn25/grind/head5/a.out)
345 by 0x8048370: main (in /auto/homes/njn25/grind/head5/a.out)
346</programlisting>
njn15d7c342005-09-30 01:43:32 +0000347 </listitem>
njn3e986b22004-11-30 10:43:45 +0000348
njn15d7c342005-09-30 01:43:32 +0000349 <listitem>
350 <para>With no debug information, stripped:</para>
njn3e986b22004-11-30 10:43:45 +0000351<programlisting>
352Invalid write of size 1
353 at 0x80483BF: (within /auto/homes/njn25/grind/head5/a.out)
354 by 0x8048370: (within /auto/homes/njn25/grind/head5/a.out)
355 by 0x42015703: __libc_start_main (in /lib/tls/libc-2.3.2.so)
356 by 0x80482CC: (within /auto/homes/njn25/grind/head5/a.out)
357</programlisting>
njn15d7c342005-09-30 01:43:32 +0000358 </listitem>
njn3e986b22004-11-30 10:43:45 +0000359
njn15d7c342005-09-30 01:43:32 +0000360 <listitem>
361 <para>With debug information and -fomit-frame-pointer:</para>
njn3e986b22004-11-30 10:43:45 +0000362<programlisting>
363Invalid write of size 1
364 at 0x80483C4: really (malloc1.c:20)
365 by 0x42015703: __libc_start_main (in /lib/tls/libc-2.3.2.so)
366 by 0x80482CC: ??? (start.S:81)
367</programlisting>
njn15d7c342005-09-30 01:43:32 +0000368 </listitem>
njn3e986b22004-11-30 10:43:45 +0000369
njn15d7c342005-09-30 01:43:32 +0000370 <listitem>
371 <para>A leak error message involving an unloaded shared object:</para>
njn0211ff32005-05-15 14:49:24 +0000372<programlisting>
37384 bytes in 1 blocks are possibly lost in loss record 488 of 713
374 at 0x1B9036DA: operator new(unsigned) (vg_replace_malloc.c:132)
375 by 0x1DB63EEB: ???
376 by 0x1DB4B800: ???
377 by 0x1D65E007: ???
378 by 0x8049EE6: main (main.cpp:24)
379</programlisting>
njn15d7c342005-09-30 01:43:32 +0000380 </listitem>
381 </itemizedlist>
njn0211ff32005-05-15 14:49:24 +0000382
njn3e986b22004-11-30 10:43:45 +0000383 </answer>
384</qandaentry>
385
njn16eeb4e2005-06-16 03:56:58 +0000386<qandaentry id="faq.aliases">
debad57fc2005-12-03 22:33:29 +0000387 <question id="q-aliases">
388 <para>The stack traces given by Memcheck (or another tool) seem to
389 have the wrong function name in them. What's happening?</para>
390 </question>
391 <answer id="a-aliases">
392 <para>Occasionally Valgrind stack traces get the wrong function
393 names. This is caused by glibc using aliases to effectively give
394 one function two names. Most of the time Valgrind chooses a
395 suitable name, but very occasionally it gets it wrong. Examples we
396 know of are printing 'bcmp' instead of 'memcmp', 'index' instead of
397 'strchr', and 'rindex' instead of 'strrchr'.</para>
398 </answer>
njn16eeb4e2005-06-16 03:56:58 +0000399</qandaentry>
400
njn6e9a3df2007-09-25 22:05:04 +0000401
402<qandaentry id="faq.crashes">
403 <question id="q-crashes">
404 <para>My program crashes normally, but doesn't under Valgrind, or vice
405 versa. What's happening?</para>
406 </question>
407 <answer id="a-crashes">
408 <para>When a program runs under Valgrind, its environment is slightly
409 different to when it runs natively. For example, the memory layout is
410 different, and the way that threads are scheduled is different.</para>
411
412 <para>Most of the time this doesn't make any difference, but it can,
413 particularly if your program is buggy. For example, if your program
414 crashes because it erroneously accesses memory that is unaddressable,
415 it's possible that this memory will not be unaddressable when run under
416 Valgrind. Alternatively, if your program has data races, these may not
417 manifest under Valgrind.</para>
418
419 <para>There isn't anything you can do to change this, it's just the
420 nature of the way Valgrind works that it cannot exactly replicate a
421 native execution environment. In the case where your program crashes
422 due to a memory error when run natively but not when run under Valgrind,
423 in most cases Memcheck should identify the bad memory operation.</para>.
424 </answer>
425</qandaentry>
426
de9bec93c2005-11-25 05:36:48 +0000427</qandadiv>
njn3e986b22004-11-30 10:43:45 +0000428
429
de9bec93c2005-11-25 05:36:48 +0000430
431<!-- Memcheck doesn't find my bug -->
432<qandadiv id="faq.notfound" xreflabel="Memcheck doesn't find my bug">
njn3e986b22004-11-30 10:43:45 +0000433<title>Memcheck doesn't find my bug</title>
njn3e986b22004-11-30 10:43:45 +0000434
435<qandaentry id="faq.hiddenbug">
debad57fc2005-12-03 22:33:29 +0000436 <question id="q-hiddenbug">
437 <para>I try running "valgrind --tool=memcheck my_program" and get
438 Valgrind's startup message, but I don't get any errors and I know my
439 program has errors.</para>
440 </question>
441 <answer id="a-hiddenbug">
442 <para>There are two possible causes of this.</para>
njna11b9b02005-03-27 17:05:08 +0000443
debad57fc2005-12-03 22:33:29 +0000444 <para>First, by default, Valgrind only traces the top-level process.
445 So if your program spawns children, they won't be traced by Valgrind
446 by default. Also, if your program is started by a shell script,
447 Perl script, or something similar, Valgrind will trace the shell, or
448 the Perl interpreter, or equivalent.</para>
njn3e986b22004-11-30 10:43:45 +0000449
debad57fc2005-12-03 22:33:29 +0000450 <para>To trace child processes, use the
451 <option>--trace-children=yes</option> option.</para>
njn3e986b22004-11-30 10:43:45 +0000452
debad57fc2005-12-03 22:33:29 +0000453 <para>If you are tracing large trees of processes, it can be less
454 disruptive to have the output sent over the network. Give Valgrind
455 the flag <option>--log-socket=127.0.0.1:12345</option> (if you want
sewardj08e31e22007-05-23 21:58:33 +0000456 logging output sent to port <literal>12345</literal> on
debad57fc2005-12-03 22:33:29 +0000457 <literal>localhost</literal>). You can use the valgrind-listener
458 program to listen on that port:</para>
njn3e986b22004-11-30 10:43:45 +0000459<programlisting>
460valgrind-listener 12345
461</programlisting>
462
debad57fc2005-12-03 22:33:29 +0000463 <para>Obviously you have to start the listener process first. See
464 the manual for more details.</para>
njna11b9b02005-03-27 17:05:08 +0000465
debad57fc2005-12-03 22:33:29 +0000466 <para>Second, if your program is statically linked, most Valgrind
467 tools won't work as well, because they won't be able to replace
468 certain functions, such as malloc(), with their own versions. A key
469 indicator of this is if Memcheck says:
njna11b9b02005-03-27 17:05:08 +0000470<programlisting>
njn5666ee62005-12-19 19:38:02 +0000471All heap blocks were freed -- no leaks are possible
njna11b9b02005-03-27 17:05:08 +0000472</programlisting>
debad57fc2005-12-03 22:33:29 +0000473 when you know your program calls malloc(). The workaround is to
474 avoid statically linking your program.</para>
475 </answer>
njn3e986b22004-11-30 10:43:45 +0000476</qandaentry>
477
478
479<qandaentry id="faq.overruns">
debad57fc2005-12-03 22:33:29 +0000480 <question id="q-overruns">
481 <para>Why doesn't Memcheck find the array overruns in this
482 program?</para>
njn3e986b22004-11-30 10:43:45 +0000483<programlisting>
484int static[5];
485
486int main(void)
487{
488 int stack[5];
489
490 static[5] = 0;
491 stack [5] = 0;
492
493 return 0;
494}
495</programlisting>
debad57fc2005-12-03 22:33:29 +0000496 </question>
497 <answer id="a-overruns">
498 <para>Unfortunately, Memcheck doesn't do bounds checking on static
499 or stack arrays. We'd like to, but it's just not possible to do in
500 a reasonable way that fits with how Memcheck works. Sorry.</para>
501 </answer>
njn3e986b22004-11-30 10:43:45 +0000502</qandaentry>
503
de9bec93c2005-11-25 05:36:48 +0000504</qandadiv>
njn3e986b22004-11-30 10:43:45 +0000505
506
de9bec93c2005-11-25 05:36:48 +0000507
508<!-- Miscellaneous -->
509<qandadiv id="faq.misc" xreflabel="Miscellaneous">
njn3e986b22004-11-30 10:43:45 +0000510<title>Miscellaneous</title>
njn3e986b22004-11-30 10:43:45 +0000511
512<qandaentry id="faq.writesupp">
debad57fc2005-12-03 22:33:29 +0000513 <question id="q-writesupp">
514 <para>I tried writing a suppression but it didn't work. Can you
515 write my suppression for me?</para>
516 </question>
517 <answer id="a-writesupp">
518 <para>Yes! Use the <option>--gen-suppressions=yes</option> feature
519 to spit out suppressions automatically for you. You can then edit
520 them if you like, eg. combining similar automatically generated
521 suppressions using wildcards like <literal>'*'</literal>.</para>
njn3e986b22004-11-30 10:43:45 +0000522
debad57fc2005-12-03 22:33:29 +0000523 <para>If you really want to write suppressions by hand, read the
524 manual carefully. Note particularly that C++ function names must be
sewardj08e31e22007-05-23 21:58:33 +0000525 mangled (that is, not demangled).</para>
debad57fc2005-12-03 22:33:29 +0000526 </answer>
njn3e986b22004-11-30 10:43:45 +0000527</qandaentry>
528
529
530<qandaentry id="faq.deflost">
debad57fc2005-12-03 22:33:29 +0000531 <question id="q-deflost">
njn1d0825f2006-03-27 11:37:07 +0000532 <para>With Memcheck's memory leak detector, what's the
njn8225cc02009-03-09 22:52:24 +0000533 difference between "definitely lost", "indirectly lost", "possibly
534 lost", "still reachable", and "suppressed"?</para>
debad57fc2005-12-03 22:33:29 +0000535 </question>
536 <answer id="a-deflost">
njn8225cc02009-03-09 22:52:24 +0000537 <para>The details are in the Memcheck section of the user manual.</para>
njn3e986b22004-11-30 10:43:45 +0000538
debad57fc2005-12-03 22:33:29 +0000539 <para>In short:</para>
540 <itemizedlist>
541 <listitem>
542 <para>"definitely lost" means your program is leaking memory --
njn8225cc02009-03-09 22:52:24 +0000543 fix those leaks!</para>
debad57fc2005-12-03 22:33:29 +0000544 </listitem>
545 <listitem>
njn8225cc02009-03-09 22:52:24 +0000546 <para>"indirectly lost" means your program is leaking memory in
547 a pointer-based structure. (E.g. if the root node of a binary tree
548 is "definitely lost", all the children will be "indirectly lost".)
549 If you fix the "definitely lost" leaks, the "indirectly lost" leaks
550 should go away.
551 </para>
552 </listitem>
553 <listitem>
554 <para>"possibly lost" means your program is leaking
debad57fc2005-12-03 22:33:29 +0000555 memory, unless you're doing funny things with pointers.</para>
556 </listitem>
557 <listitem>
558 <para>"still reachable" means your program is probably ok -- it
559 didn't free some memory it could have. This is quite common and
560 often reasonable. Don't use
561 <option>--show-reachable=yes</option> if you don't want to see
562 these reports.</para>
563 </listitem>
564 <listitem>
565 <para>"suppressed" means that a leak error has been suppressed.
566 There are some suppressions in the default suppression files.
567 You can ignore suppressed errors.</para>
568 </listitem>
569 </itemizedlist>
570 </answer>
njn3e986b22004-11-30 10:43:45 +0000571</qandaentry>
572
njn3fdb3622006-10-20 22:16:57 +0000573<qandaentry id="faq.undeferrors">
574 <question id="q-undeferrors">
575 <para>Memcheck's uninitialised value errors are hard to track down,
576 because they are often reported some time after they are caused. Could
577 Memcheck record a trail of operations to better link the cause to the
578 effect? Or maybe just eagerly report any copies of uninitialised
579 memory values?</para>
580 </question>
581 <answer id="a-undeferrors">
njnbb97c5e2008-12-13 22:27:05 +0000582 <para>Prior to version 3.4.0, the answer was "we don't know how to do it
583 without huge performance penalties". As of 3.4.0, try using the
584 <option>--track-origins=yes</option> flag. It will run slower than
585 usual, but will give you extra information about the origin of
586 uninitialised values.</para>
njn3fdb3622006-10-20 22:16:57 +0000587
njnbb97c5e2008-12-13 22:27:05 +0000588 <para>Or if you want to do it the old fashioned way, you can use the
589 client request
njn3fdb3622006-10-20 22:16:57 +0000590 <computeroutput>VALGRIND_CHECK_VALUE_IS_DEFINED</computeroutput> to help
591 track these errors down -- work backwards from the point where the
592 uninitialised error occurs, checking suspect values until you find the
593 cause. This requires editing, compiling and re-running your program
594 multiple times, which is a pain, but still easier than debugging the
595 problem without Memcheck's help.</para>
596
597 <para>As for eager reporting of copies of uninitialised memory values,
598 this has been suggested multiple times. Unfortunately, almost all
sewardj33878892007-11-17 09:43:25 +0000599 programs legitimately copy uninitialised memory values around (because
njn3fdb3622006-10-20 22:16:57 +0000600 compilers pad structs to preserve alignment) and eager checking leads to
601 hundreds of false positives. Therefore Memcheck does not support eager
602 checking at this time.</para>
603 </answer>
604</qandaentry>
605
606
njnbfc79f82009-01-06 05:54:45 +0000607<qandaentry id="faq.attach">
608 <question id="q-attach">
609 <para>Is it possible to attach Valgrind to a program that is already
610 running?</para>
611 </question>
njn7441b992009-02-22 22:25:31 +0000612 <answer id="a-attach">
njnbfc79f82009-01-06 05:54:45 +0000613 <para>No. The environment that Valgrind provides for running programs
614 is significantly different to that for normal programs, e.g. due to
615 different layout of memory. Therefore Valgrind has to have full control
616 from the very start.</para>
617
618 <para>It is possible to achieve something like this by running your
619 program without any instrumentation (which involves a slow-down of about
620 5x, less than that of most tools), and then adding instrumentation once
621 you get to a point of interest. Support for this must be provided by
622 the tool, however, and Callgrind is the only tool that currently has
623 such support. See the instructions on the
624 <computeroutput>callgrind_control</computeroutput> program for details.
625 </para>
626 </answer>
627</qandaentry>
628
629
de9bec93c2005-11-25 05:36:48 +0000630</qandadiv>
njn3e986b22004-11-30 10:43:45 +0000631
de9bec93c2005-11-25 05:36:48 +0000632
633
634<!-- Further Assistance -->
635<qandadiv id="faq.help" xreflabel="How To Get Further Assistance">
636<title>How To Get Further Assistance</title>
637
638<qandaentry id="e-help">
debad57fc2005-12-03 22:33:29 +0000639 <!-- <question><para/></question> -->
640 <answer id="a-help">
de9bec93c2005-11-25 05:36:48 +0000641 <para>Please read all of this section before posting.</para>
642
643 <para>If you think an answer is incomplete or inaccurate, please
644 e-mail <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink>.</para>
debad57fc2005-12-03 22:33:29 +0000645
de97ab7e72005-11-27 18:19:40 +0000646 <para>Read the appropriate section(s) of the
647 <ulink url="&vg-bookset;">Valgrind Documentation</ulink>.</para>
de9bec93c2005-11-25 05:36:48 +0000648
de97ab7e72005-11-27 18:19:40 +0000649 <para>Read the
650 <ulink url="&vg-dist-docs;">Distribution Documents</ulink>.</para>
de9bec93c2005-11-25 05:36:48 +0000651
652 <para><ulink url="http://search.gmane.org">Search</ulink> the
653 <ulink url="http://news.gmane.org/gmane.comp.debugging.valgrind">valgrind-users</ulink> mailing list archives, using the group name
654 <computeroutput>gmane.comp.debugging.valgrind</computeroutput>.</para>
655
debad57fc2005-12-03 22:33:29 +0000656 <para>Only when you have tried all of these things and are still
657 stuck, should you post to the
658 <ulink url="&vg-users-list;">valgrind-users mailing list</ulink>. In
659 which case, please read the following carefully. Making a complete
660 posting will greatly increase the chances that an expert or fellow
661 user reading it will have enough information and motivation to
662 reply.</para>
de9bec93c2005-11-25 05:36:48 +0000663
debad57fc2005-12-03 22:33:29 +0000664 <para>Make sure you give full details of the problem, including the
njn1ac2f0d2005-12-04 19:26:00 +0000665 full output of <computeroutput>valgrind -v &lt;your-prog&gt;</computeroutput>, if
debad57fc2005-12-03 22:33:29 +0000666 applicable. Also which Linux distribution you're using (Red Hat,
667 Debian, etc) and its version number.</para>
de9bec93c2005-11-25 05:36:48 +0000668
debad57fc2005-12-03 22:33:29 +0000669 <para>You are in little danger of making your posting too long unless
670 you include large chunks of Valgrind's (unsuppressed) output, so err
671 on the side of giving too much information.</para>
de9bec93c2005-11-25 05:36:48 +0000672
debad57fc2005-12-03 22:33:29 +0000673 <para>Clearly written subject lines and message bodies are
674 appreciated, too.</para>
de9bec93c2005-11-25 05:36:48 +0000675
676 <para>Finally, remember that, despite the fact that most of the
debad57fc2005-12-03 22:33:29 +0000677 community are very helpful and responsive to emailed questions, you
678 are probably requesting help from unpaid volunteers, so you have no
679 guarantee of receiving an answer.</para>
de9bec93c2005-11-25 05:36:48 +0000680</answer>
681
682</qandaentry>
683</qandadiv>
684
685
686<!-- FAQ ends here -->
njn3e986b22004-11-30 10:43:45 +0000687</qandaset>
de9bec93c2005-11-25 05:36:48 +0000688
njn3e986b22004-11-30 10:43:45 +0000689
690
691<!-- template
de9bec93c2005-11-25 05:36:48 +0000692<qandadiv id="faq.installing" xreflabel="Installing">
693<title>Installing</title>
njn3e986b22004-11-30 10:43:45 +0000694
de9bec93c2005-11-25 05:36:48 +0000695<qandaentry id="faq.problem">
696 <question id="q-problem">
njn3e986b22004-11-30 10:43:45 +0000697 <para></para>
698 </question>
de9bec93c2005-11-25 05:36:48 +0000699 <answer id="a-problem">
njn3e986b22004-11-30 10:43:45 +0000700 <para></para>
701 </answer>
702</qandaentry>
703
de9bec93c2005-11-25 05:36:48 +0000704</qandadiv>
njn3e986b22004-11-30 10:43:45 +0000705-->
706
de9bec93c2005-11-25 05:36:48 +0000707</article>
njn3e986b22004-11-30 10:43:45 +0000708
709</book>