The Valgrind Quick Start Guide (2024)

1.Introduction

The Valgrind tool suite provides a number of debugging andprofiling tools that help you make your programs faster and more correct.The most popular of these tools is called Memcheck. It can detect manymemory-related errors that are common in C and C++ programs and that canlead to crashes and unpredictable behaviour.

The rest of this guide gives the minimum information you need to startdetecting memory errors in your program with Memcheck. For fulldocumentation of Memcheck and the other tools, please read the User Manual.

2.Preparing your program

Compile your program with -g to include debugginginformation so that Memcheck's error messages include exact linenumbers. Using -O0 is also a goodidea, if you can tolerate the slowdown. With-O1 line numbers in error messages canbe inaccurate, although generally speaking running Memcheck on code compiledat -O1 works fairly well, and the speed improvementcompared to running -O0 is quite significant.Use of-O2 and above is not recommended asMemcheck occasionally reports uninitialised-value errors which don'treally exist.

3.Running your program under Memcheck

If you normally run your program like this:

 myprog arg1 arg2

Use this command line:

 valgrind --leak-check=yes myprog arg1 arg2

Memcheck is the default tool. The --leak-checkoption turns on the detailed memory leak detector.

Your program will run much slower (eg. 20 to 30 times) thannormal, and use a lot more memory. Memcheck will issue messages aboutmemory errors and leaks that it detects.

4.Interpreting Memcheck's output

Here's an example C program, in a file called a.c, with a memory errorand a memory leak.

 #include <stdlib.h> void f(void) { int* x = malloc(10 * sizeof(int)); x[10] = 0; // problem 1: heap block overrun } // problem 2: memory leak -- x not freed int main(void) { f(); return 0; }

Most error messages look like the following, which describesproblem 1, the heap block overrun:

 ==19182== Invalid write of size 4 ==19182== at 0x804838F: f (example.c:6) ==19182== by 0x80483AB: main (example.c:11) ==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 (example.c:5) ==19182== by 0x80483AB: main (example.c:11)

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 kind of error it 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 telling you where the problem occurred. 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 the --num-callers option to make it bigger.

  • The code addresses (eg. 0x804838F) are usually unimportant, but occasionally crucial for tracking down weirder bugs.

  • Some error messages have a second component which describes the memory address involved. This one shows that the written memory is just past the end of a block allocated with malloc() on line 5 of example.c.

It's worth fixing errors in the order they are reported, aslater errors can be caused by earlier errors. Failing to do this is acommon cause of difficulty with Memcheck.

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:5) ==19182== by 0x80483AB: main (a.c:11)

The stack trace tells you where the leaked memory was allocated.Memcheck cannot tell you why the memory leaked, unfortunately.(Ignore the "vg_replace_malloc.c", that's an implementationdetail.)

There are several kinds of leaks; the two most importantcategories are:

  • "definitely lost": your program is leaking memory -- fix it!

  • "probably lost": your program is leaking memory, unless you're doing funny things with pointers (such as moving them to point to the middle of a heap block).

Memcheck also reports uses of uninitialised values, most commonly withthe message "Conditional jump or move depends on uninitialisedvalue(s)". It can be difficult to determine the root cause of these errors.Try using the --track-origins=yes to get extra information.This makes Memcheck run slower, but the extra information you get oftensaves a lot of time figuring out where the uninitialised values are comingfrom.

If you don't understand an error message, please consultExplanation of error messages from Memcheck in the Valgrind User Manualwhich has examples of all the error messages Memcheck produces.

5.Caveats

Memcheck is not perfect; it occasionally produces false positives,and there are mechanisms for suppressing these (see Suppressing errors in the Valgrind User Manual).However, it is typically right 99% of the time, so you should be wary ofignoring its error messages. After all, you wouldn't ignore warningmessages produced by a compiler, right? The suppression mechanism isalso useful if Memcheck is reporting errors in library code that youcannot change. The default suppression set hides a lot of these, but youmay come across more.

Memcheck cannot detect every memory error your program has.For example, it can't detect out-of-range reads or writes to arraysthat are allocated statically or on the stack. But it should detect manyerrors that could crash your program (eg. cause a segmentationfault).

Try to make your program so clean that Memcheck reports noerrors. Once you achieve this state, it is much easier to see whenchanges to the program cause Memcheck to report new errors.Experience from several years of Memcheck use shows that it ispossible to make even huge programs run Memcheck-clean. For example,large parts of KDE, OpenOffice.org and Firefox are Memcheck-clean, or veryclose to it.

6.More information

Please consult the Valgrind FAQ and the Valgrind User Manual, which have much more information. Note thatthe other tools in the Valgrind distribution can be invoked with the--tool option.

The Valgrind Quick Start Guide (2024)

References

Top Articles
Latest Posts
Article information

Author: Nathanael Baumbach

Last Updated:

Views: 6404

Rating: 4.4 / 5 (75 voted)

Reviews: 82% of readers found this page helpful

Author information

Name: Nathanael Baumbach

Birthday: 1998-12-02

Address: Apt. 829 751 Glover View, West Orlando, IN 22436

Phone: +901025288581

Job: Internal IT Coordinator

Hobby: Gunsmithing, Motor sports, Flying, Skiing, Hooping, Lego building, Ice skating

Introduction: My name is Nathanael Baumbach, I am a fantastic, nice, victorious, brave, healthy, cute, glorious person who loves writing and wants to share my knowledge and understanding with you.