• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1
2
3Valgrind FAQ
4Release 3.13.0 15 June 2017
5~~~~~~~~~~~~~~~~~~~~~~~~~~~
6
7Table of Contents
81. Background
92. Compiling, installing and configuring
103. Valgrind aborts unexpectedly
114. Valgrind behaves unexpectedly
125. Miscellaneous
136. How To Get Further Assistance
14
15------------------------------------------------------------------------
161. Background
17------------------------------------------------------------------------
18
191.1. How do you pronounce "Valgrind"?
20The "Val" as in the word "value". The "grind" is pronounced with a short
21'i' -- ie. "grinned" (rhymes with "tinned") rather than "grined" (rhymes
22with "find").
23
24Don't feel bad: almost everyone gets it wrong at first.
25------------------------------------------------------------------------
26
271.2. Where does the name "Valgrind" come from?
28From Nordic mythology. Originally (before release) the project was named
29Heimdall, after the watchman of the Nordic gods. He could "see a hundred
30miles by day or night, hear the grass growing, see the wool growing on a
31sheep's back", etc. This would have been a great name, but it was
32already taken by a security package "Heimdal".
33
34Keeping with the Nordic theme, Valgrind was chosen. Valgrind is the name
35of the main entrance to Valhalla (the Hall of the Chosen Slain in
36Asgard). Over this entrance there resides a wolf and over it there is
37the head of a boar and on it perches a huge eagle, whose eyes can see to
38the far regions of the nine worlds. Only those judged worthy by the
39guardians are allowed to pass through Valgrind. All others are refused
40entrance.
41
42It's not short for "value grinder", although that's not a bad guess.
43
44------------------------------------------------------------------------
452. Compiling, installing and configuring
46------------------------------------------------------------------------
47
482.1. When building Valgrind, 'make' dies partway with an assertion
49failure, something like this:
50
51    % make: expand.c:489: allocated_variable_append:
52            Assertion 'current_variable_set_list->next != 0' failed.
53
54It's probably a bug in 'make'. Some, but not all, instances of version
553.79.1 have this bug, see this:
56<http://www.mail-archive.com/bug-make@gnu.org/msg01658.html>. Try
57upgrading to a more recent version of 'make'. Alternatively, we have
58heard that unsetting the CFLAGS environment variable avoids the problem.
59
60------------------------------------------------------------------------
61
622.2. When building Valgrind, 'make' fails with this:
63    /usr/bin/ld: cannot find -lc
64    collect2: ld returned 1 exit status
65
66You need to install the glibc-static-devel package.
67
68------------------------------------------------------------------------
693. Valgrind aborts unexpectedly
70------------------------------------------------------------------------
71
723.1. Programs run OK on Valgrind, but at exit produce a bunch of errors
73involving __libc_freeres and then die with a segmentation fault.
74
75When the program exits, Valgrind runs the procedure __libc_freeres in
76glibc. This is a hook for memory debuggers, so they can ask glibc to
77free up any memory it has used. Doing that is needed to ensure that
78Valgrind doesn't incorrectly report space leaks in glibc.
79
80The problem is that running __libc_freeres in older glibc versions
81causes this crash.
82
83Workaround for 1.1.X and later versions of Valgrind: use the
84--run-libc-freeres=no option. You may then get space leak reports for
85glibc allocations (please don't report these to the glibc people, since
86they are not real leaks), but at least the program runs.
87
88------------------------------------------------------------------------
89
903.2. My (buggy) program dies like this:
91    valgrind: m_mallocfree.c:248 (get_bszB_as_is): Assertion 'bszB_lo == bszB_hi' failed.
92
93or like this:
94    valgrind: m_mallocfree.c:442 (mk_inuse_bszB): Assertion 'bszB != 0' failed.
95
96or otherwise aborts or crashes in m_mallocfree.c.
97If Memcheck (the memory checker) shows any invalid reads, invalid writes
98or invalid frees in your program, the above may happen. Reason is that
99your program may trash Valgrind's low-level memory manager, which then
100dies with the above assertion, or something similar. The cure is to fix
101your program so that it doesn't do any illegal memory accesses. The
102above failure will hopefully go away after that.
103
104------------------------------------------------------------------------
105
1063.3. My program dies, printing a message like this along the way:
107    vex x86->IR: unhandled instruction bytes: 0x66 0xF 0x2E 0x5
108
109One possibility is that your program has a bug and erroneously jumps to
110a non-code address, in which case you'll get a SIGILL signal. Memcheck
111may issue a warning just before this happens, but it might not if the
112jump happens to land in addressable memory.
113
114Another possibility is that Valgrind does not handle the instruction. If
115you are using an older Valgrind, a newer version might handle the
116instruction. However, all instruction sets have some obscure, rarely
117used instructions. Also, on amd64 there are an almost limitless number
118of combinations of redundant instruction prefixes, many of them
119undocumented but accepted by CPUs. So Valgrind will still have decoding
120failures from time to time. If this happens, please file a bug report.
121
122------------------------------------------------------------------------
123
1243.4. I tried running a Java program (or another program that uses a
125just-in-time compiler) under Valgrind but something went wrong. Does
126Valgrind handle such programs?
127
128Valgrind can handle dynamically generated code, so long as none of the
129generated code is later overwritten by other generated code. If this
130happens, though, things will go wrong as Valgrind will continue running
131its translations of the old code (this is true on x86 and amd64, on
132PowerPC there are explicit cache flush instructions which Valgrind
133detects and honours). You should try running with --smc-check=all in
134this case. Valgrind will run much more slowly, but should detect the use
135of the out-of-date code.
136
137Alternatively, if you have the source code to the JIT compiler you can
138insert calls to the VALGRIND_DISCARD_TRANSLATIONS client request to mark
139out-of-date code, saving you from using --smc-check=all.
140
141Apart from this, in theory Valgrind can run any Java program just fine,
142even those that use JNI and are partially implemented in other languages
143like C and C++. In practice, Java implementations tend to do nasty
144things that most programs do not, and Valgrind sometimes falls over
145these corner cases.
146
147If your Java programs do not run under Valgrind, even with
148--smc-check=all, please file a bug report and hopefully we'll be able to
149fix the problem.
150
151
152------------------------------------------------------------------------
1534. Valgrind behaves unexpectedly
154------------------------------------------------------------------------
155
1564.1. My program uses the C++ STL and string classes. Valgrind reports
157'still reachable' memory leaks involving these classes at the exit of
158the program, but there should be none.
159
160First of all: relax, it's probably not a bug, but a feature. Many
161implementations of the C++ standard libraries use their own memory pool
162allocators. Memory for quite a number of destructed objects is not
163immediately freed and given back to the OS, but kept in the pool(s) for
164later re-use. The fact that the pools are not freed at the exit of the
165program cause Valgrind to report this memory as still reachable. The
166behaviour not to free pools at the exit could be called a bug of the
167library though.
168
169Using GCC, you can force the STL to use malloc and to free memory as
170soon as possible by globally disabling memory caching. Beware! Doing so
171will probably slow down your program, sometimes drastically.
172
173* With GCC 2.91, 2.95, 3.0 and 3.1, compile all source using the STL
174with -D__USE_MALLOC. Beware! This was removed from GCC starting with
175version 3.3.
176
177* With GCC 3.2.2 and later, you should export the environment variable
178GLIBCPP_FORCE_NEW before running your program.
179
180* With GCC 3.4 and later, that variable has changed name to
181GLIBCXX_FORCE_NEW.
182
183There are other ways to disable memory pooling: using the malloc_alloc
184template with your objects (not portable, but should work for GCC) or
185even writing your own memory allocators. But all this goes beyond the
186scope of this FAQ. Start by reading
187http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html#4_4_leak:
188<http://gcc.gnu.org/onlinedocs/libstdc++/faq/index.html#4_4_leak> if you
189absolutely want to do that. But beware: allocators belong to the more
190messy parts of the STL and people went to great lengths to make the STL
191portable across platforms. Chances are good that your solution will work
192on your platform, but not on others.
193
194------------------------------------------------------------------------
195
1964.2. The stack traces given by Memcheck (or another tool) aren't
197helpful. How can I improve them?
198
199If they're not long enough, use --num-callers to make them longer.
200If they're not detailed enough, make sure you are compiling with -g to
201add debug information. And don't strip symbol tables (programs should be
202unstripped unless you run 'strip' on them; some libraries ship
203stripped).
204
205Also, for leak reports involving shared objects, if the shared object is
206unloaded before the program terminates, Valgrind will discard the debug
207information and the error message will be full of ??? entries. The
208workaround here is to avoid calling dlclose on these shared objects.
209
210Also, -fomit-frame-pointer and -fstack-check can make stack traces
211worse.
212
213Some example sub-traces:
214* With debug information and unstripped (best):
215    Invalid write of size 1
216       at 0x80483BF: really (malloc1.c:20)
217       by 0x8048370: main (malloc1.c:9)
218
219* With no debug information, unstripped:
220    Invalid write of size 1
221       at 0x80483BF: really (in /auto/homes/njn25/grind/head5/a.out)
222       by 0x8048370: main (in /auto/homes/njn25/grind/head5/a.out)
223
224* With no debug information, stripped:
225    Invalid write of size 1
226       at 0x80483BF: (within /auto/homes/njn25/grind/head5/a.out)
227       by 0x8048370: (within /auto/homes/njn25/grind/head5/a.out)
228       by 0x42015703: __libc_start_main (in /lib/tls/libc-2.3.2.so)
229       by 0x80482CC: (within /auto/homes/njn25/grind/head5/a.out)
230
231* With debug information and -fomit-frame-pointer:
232    Invalid write of size 1
233       at 0x80483C4: really (malloc1.c:20)
234       by 0x42015703: __libc_start_main (in /lib/tls/libc-2.3.2.so)
235       by 0x80482CC: ??? (start.S:81)
236
237* A leak error message involving an unloaded shared object:
238    84 bytes in 1 blocks are possibly lost in loss record 488 of 713
239       at 0x1B9036DA: operator new(unsigned) (vg_replace_malloc.c:132)
240       by 0x1DB63EEB: ???
241       by 0x1DB4B800: ???
242       by 0x1D65E007: ???
243       by 0x8049EE6: main (main.cpp:24)
244
245------------------------------------------------------------------------
246
2474.3. The stack traces given by Memcheck (or another tool) seem to have
248the wrong function name in them. What's happening?
249
250Occasionally Valgrind stack traces get the wrong function names. This is
251caused by glibc using aliases to effectively give one function two
252names. Most of the time Valgrind chooses a suitable name, but very
253occasionally it gets it wrong. Examples we know of are printing bcmp
254instead of memcmp, index instead of strchr, and rindex instead of
255strrchr.
256
257------------------------------------------------------------------------
258
2594.4. My program crashes normally, but doesn't under Valgrind, or vice
260versa. What's happening?
261
262When a program runs under Valgrind, its environment is slightly
263different to when it runs natively. For example, the memory layout is
264different, and the way that threads are scheduled is different.
265
266Most of the time this doesn't make any difference, but it can,
267particularly if your program is buggy. For example, if your program
268crashes because it erroneously accesses memory that is unaddressable,
269it's possible that this memory will not be unaddressable when run under
270Valgrind. Alternatively, if your program has data races, these may not
271manifest under Valgrind.
272
273There isn't anything you can do to change this, it's just the nature of
274the way Valgrind works that it cannot exactly replicate a native
275execution environment. In the case where your program crashes due to a
276memory error when run natively but not when run under Valgrind, in most
277cases Memcheck should identify the bad memory operation.
278
279------------------------------------------------------------------------
280
2814.5. Memcheck doesn't report any errors and I know my program has
282errors.
283
284There are two possible causes of this.
285First, by default, Valgrind only traces the top-level process. So if
286your program spawns children, they won't be traced by Valgrind by
287default. Also, if your program is started by a shell script, Perl
288script, or something similar, Valgrind will trace the shell, or the Perl
289interpreter, or equivalent.
290
291To trace child processes, use the --trace-children=yes option.
292If you are tracing large trees of processes, it can be less disruptive
293to have the output sent over the network. Give Valgrind the option
294--log-socket=127.0.0.1:12345 (if you want logging output sent to port
29512345 on localhost). You can use the valgrind-listener program to listen
296on that port:
297
298    valgrind-listener 12345
299
300Obviously you have to start the listener process first. See the manual
301for more details.
302
303Second, if your program is statically linked, most Valgrind tools will
304only work well if they are able to replace certain functions, such as
305malloc, with their own versions. By default, statically linked malloc
306functions are not replaced. A key indicator of this is if Memcheck says:
307All heap blocks were freed -- no leaks are possible when you know your
308program calls malloc. The workaround is to use the option
309--soname-synonyms=somalloc=NONE or to avoid statically linking your
310program.
311
312There will also be no replacement if you use an alternative malloc
313library such as tcmalloc, jemalloc, ... In such a case, the option
314--soname-synonyms=somalloc=zzzz (where zzzz is the soname of the
315alternative malloc library) will allow Valgrind to replace the
316functions.
317
318------------------------------------------------------------------------
319
3204.6. Why doesn't Memcheck find the array overruns in this program?
321    int static[5];
322
323    int main(void)
324    {
325      int stack[5];
326
327      static[5] = 0;
328      stack [5] = 0;
329
330      return 0;
331    }
332
333Unfortunately, Memcheck doesn't do bounds checking on global or stack
334arrays. We'd like to, but it's just not possible to do in a reasonable
335way that fits with how Memcheck works. Sorry.
336
337However, the experimental tool SGcheck can detect errors like this. Run
338Valgrind with the --tool=exp-sgcheck option to try it, but be aware that
339it is not as robust as Memcheck.
340
341
342------------------------------------------------------------------------
3435. Miscellaneous
344------------------------------------------------------------------------
345
3465.1. I tried writing a suppression but it didn't work. Can you write my
347suppression for me?
348
349Yes! Use the --gen-suppressions=yes feature to spit out suppressions
350automatically for you. You can then edit them if you like, eg. combining
351similar automatically generated suppressions using wildcards like '*'.
352
353If you really want to write suppressions by hand, read the manual
354carefully. Note particularly that C++ function names must be mangled
355(that is, not demangled).
356
357------------------------------------------------------------------------
358
3595.2. With Memcheck's memory leak detector, what's the difference between
360"definitely lost", "indirectly lost", "possibly lost", "still
361reachable", and "suppressed"?
362
363The details are in the Memcheck section of the user manual.
364In short:
365* "definitely lost" means your program is leaking memory -- fix those
366leaks!
367
368* "indirectly lost" means your program is leaking memory in a
369pointer-based structure. (E.g. if the root node of a binary tree is
370"definitely lost", all the children will be "indirectly lost".) If you
371fix the "definitely lost" leaks, the "indirectly lost" leaks should go
372away.
373
374* "possibly lost" means your program is leaking memory, unless you're
375doing unusual things with pointers that could cause them to point into
376the middle of an allocated block; see the user manual for some possible
377causes. Use --show-possibly-lost=no if you don't want to see these
378reports.
379
380* "still reachable" means your program is probably ok -- it didn't free
381some memory it could have. This is quite common and often reasonable.
382Don't use --show-reachable=yes if you don't want to see these reports.
383
384* "suppressed" means that a leak error has been suppressed. There are
385some suppressions in the default suppression files. You can ignore
386suppressed errors.
387
388------------------------------------------------------------------------
389
3905.3. Memcheck's uninitialised value errors are hard to track down,
391because they are often reported some time after they are caused. Could
392Memcheck record a trail of operations to better link the cause to the
393effect? Or maybe just eagerly report any copies of uninitialised memory
394values?
395
396Prior to version 3.4.0, the answer was "we don't know how to do it
397without huge performance penalties". As of 3.4.0, try using the
398--track-origins=yes option. It will run slower than usual, but will give
399you extra information about the origin of uninitialised values.
400
401Or if you want to do it the old fashioned way, you can use the client
402request VALGRIND_CHECK_VALUE_IS_DEFINED to help track these errors down
403-- work backwards from the point where the uninitialised error occurs,
404checking suspect values until you find the cause. This requires editing,
405compiling and re-running your program multiple times, which is a pain,
406but still easier than debugging the problem without Memcheck's help.
407
408As for eager reporting of copies of uninitialised memory values, this
409has been suggested multiple times. Unfortunately, almost all programs
410legitimately copy uninitialised memory values around (because compilers
411pad structs to preserve alignment) and eager checking leads to hundreds
412of false positives. Therefore Memcheck does not support eager checking
413at this time.
414
415------------------------------------------------------------------------
416
4175.4. Is it possible to attach Valgrind to a program that is already
418running?
419
420No. The environment that Valgrind provides for running programs is
421significantly different to that for normal programs, e.g. due to
422different layout of memory. Therefore Valgrind has to have full control
423from the very start.
424
425It is possible to achieve something like this by running your program
426without any instrumentation (which involves a slow-down of about 5x,
427less than that of most tools), and then adding instrumentation once you
428get to a point of interest. Support for this must be provided by the
429tool, however, and Callgrind is the only tool that currently has such
430support. See the instructions on the callgrind_control program for
431details.
432
433
434------------------------------------------------------------------------
4356. How To Get Further Assistance
436------------------------------------------------------------------------
437
438Read the appropriate section(s) of the Valgrind Documentation:
439<http://www.valgrind.org/docs/manual/index.html>.
440
441Search: <http://search.gmane.org> the valgrind-users:
442<http://news.gmane.org/gmane.comp.debugging.valgrind> mailing list
443archives, using the group name gmane.comp.debugging.valgrind.
444
445If you think an answer in this FAQ is incomplete or inaccurate, please
446e-mail valgrind@valgrind.org: <valgrind@valgrind.org>.
447
448If you have tried all of these things and are still stuck, you can try
449mailing the valgrind-users mailing list:
450<http://www.valgrind.org/support/mailing_lists.html>. Note that an email
451has a better change of being answered usefully if it is clearly written.
452Also remember that, despite the fact that most of the community are very
453helpful and responsive to emailed questions, you are probably requesting
454help from unpaid volunteers, so you have no guarantee of receiving an
455answer.
456
457