Valgrind quick start -------------------- This document contains the minimum information you should know to start detecting memory errors in your program with Valgrind. The Valgrind distribution has multiple tools. The memory checking tool (called Memcheck) can detect many common memory errors such as: - touching memory you shouldn't (eg. overrunning heap block boundaries) - using values before they have been initialized - incorrect freeing of memory, such as double-freeing heap blocks - memory leaks Here's how to use it. 1. Preparing your program. Compile your program with debugging information so that Memcheck's error messages include exact line numbers. 2. Running your program under Memcheck. If you normally run your program like this: myprog arg1 arg2 arg3 Use this command line: valgrind --tool=memcheck --num-callers=40 --leak-check=yes myprog arg2 arg2 arg3 The --tool option invokes Memcheck. The --num-callers option asks for big stack traces, which make error messages more informative. The --leak-check option turns on the memory leak detector. Your program will run much slower (eg. 20 to 30 times) than normal. Memcheck will describe any errors it detects. When your program terminates, Memcheck will describe any memory leaks it detects. 3. Interpreting Memcheck's output. Here's an example C program with two memory errors. #include #include int f(void) { int* x = malloc(10 * sizeof(int)); x[10] = 0; // problem 1: heap block overrun return; // problem 2: memory leak -- x not freed } int main(void) { f(); return 0; } Most error messages look like the following, which describes problem 1, the heap block overrun: ==19182== Invalid write of size 4 ==19182== at 0x804838F: f (a.c:8) ==19182== by 0x80483AB: main (a.c:14) ==19182== Address 0x1BA45050 is 0 bytes after a block of size 40 alloc'd ==19182== at 0x1B8FF5CD: malloc (vg_replace_malloc.c:130) ==19182== by 0x8048385: f (a.c:7) ==19182== by 0x80483AB: main (a.c:14) Things to notice: - There is a lot of information in each error message; read it carefully. - The 19182 is the process ID; it's usually unimportant. - The first line ("Invalid write...") tells you what the error is. Here, the program wrote to some memory it should not have due to a heap block overrun. - Below the first line is a stack trace. Stack traces can get quite large, and be confusing, especially if you are using the C++ STL. Reading them from the bottom up can help. If the stack trace is not big enough, use a bigger --num-callers option. - The addresses (eg. 0x804838F) are usually unimportant, but occasionally crucial for tracking down weirder bugs. - Some error messages, such as this one, have a second component which describes the memory address involved, and possibly give another stack trace showing where it was allocated or freed. Memory leak messages look like this: ==19182== 40 bytes in 1 blocks are definitely lost in loss record 1 of 1 ==19182== at 0x1B8FF5CD: malloc (vg_replace_malloc.c:130) ==19182== by 0x8048385: f (a.c:7) ==19182== by 0x80483AB: main (a.c:14) The stack trace tells you where the leaked memory was allocated. The "vg_replace_malloc.c" is Memcheck's version of malloc(); pretend it's the normal system malloc(). There are several kinds of leaks; the two most important categories are: - "definitely lost": your program is leaking memory -- fix it! - "probably lost": your program is probably leaking memory, unless you're doing funny things with pointers (such as moving them to point to the middle of a heap block). If you don't understand an error message, please consult section 3 of the Valgrind user manual which has examples of all the error messages Memcheck produces. 4. Caveats. Memcheck is not perfect; it occasionally produces false positives, and there are mechanisms for suppressing these (see "suppressions" in the user manual). However, it is typically right 99% of the time, so you should not ignore any of its error messages unless you are really confident. After all, you wouldn't ignore warning messages produced by a compiler, right? Memcheck also cannot detect every memory error your program has. For example, it can't detect if you overrun the bounds of an array that is allocated on the stack. So don't assume your program is bug-free if Memcheck doesn't complain. 5. More information. Please consult the FAQ and the user manual, which have much more information.