| <html> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>The Valgrind Quick Start Guide</title> |
| <link rel="stylesheet" type="text/css" href="vg_basic.css"> |
| <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> |
| <link rel="home" href="index.html" title="Valgrind Documentation"> |
| <link rel="up" href="QuickStart.html" title="The Valgrind Quick Start Guide"> |
| <link rel="prev" href="QuickStart.html" title="The Valgrind Quick Start Guide"> |
| <link rel="next" href="manual.html" title="Valgrind User Manual"> |
| </head> |
| <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> |
| <div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr> |
| <td width="22px" align="center" valign="middle"><a accesskey="p" href="QuickStart.html"><img src="images/prev.png" width="18" height="21" border="0" alt="Prev"></a></td> |
| <td width="25px" align="center" valign="middle"><a accesskey="u" href="QuickStart.html"><img src="images/up.png" width="21" height="18" border="0" alt="Up"></a></td> |
| <td width="31px" align="center" valign="middle"><a accesskey="h" href="index.html"><img src="images/home.png" width="27" height="20" border="0" alt="Up"></a></td> |
| <th align="center" valign="middle">The Valgrind Quick Start Guide</th> |
| <td width="22px" align="center" valign="middle"><a accesskey="n" href="manual.html"><img src="images/next.png" width="18" height="21" border="0" alt="Next"></a></td> |
| </tr></table></div> |
| <div class="article"> |
| <div class="titlepage"> |
| <div><div><h1 class="title"> |
| <a name="quick-start"></a>The Valgrind Quick Start Guide</h1></div></div> |
| <hr> |
| </div> |
| <div class="sect1"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="quick-start.intro"></a>1. Introduction</h2></div></div></div> |
| <p>The Valgrind tool suite provides a number of debugging and |
| profiling tools that help you make your programs faster and more correct. |
| The most popular of these tools is called Memcheck. It can detect many |
| memory-related errors that are common in C and C++ programs and that can |
| lead to crashes and unpredictable behaviour.</p> |
| <p>The rest of this guide gives the minimum information you need to start |
| detecting memory errors in your program with Memcheck. For full |
| documentation of Memcheck and the other tools, please read the User Manual. |
| </p> |
| </div> |
| <div class="sect1"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="quick-start.prepare"></a>2. Preparing your program</h2></div></div></div> |
| <p>Compile your program with <code class="option">-g</code> to include debugging |
| information so that Memcheck's error messages include exact line |
| numbers. Using <code class="option">-O0</code> is also a good |
| idea, if you can tolerate the slowdown. With |
| <code class="option">-O1</code> line numbers in error messages can |
| be inaccurate, although generally speaking running Memcheck on code compiled |
| at <code class="option">-O1</code> works fairly well, and the speed improvement |
| compared to running <code class="option">-O0</code> is quite significant. |
| Use of |
| <code class="option">-O2</code> and above is not recommended as |
| Memcheck occasionally reports uninitialised-value errors which don't |
| really exist.</p> |
| </div> |
| <div class="sect1"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="quick-start.mcrun"></a>3. Running your program under Memcheck</h2></div></div></div> |
| <p>If you normally run your program like this:</p> |
| <pre class="programlisting"> myprog arg1 arg2 |
| </pre> |
| <p>Use this command line:</p> |
| <pre class="programlisting"> valgrind --leak-check=yes myprog arg1 arg2 |
| </pre> |
| <p>Memcheck is the default tool. The <code class="option">--leak-check</code> |
| option turns on the detailed memory leak detector.</p> |
| <p>Your program will run much slower (eg. 20 to 30 times) than |
| normal, and use a lot more memory. Memcheck will issue messages about |
| memory errors and leaks that it detects.</p> |
| </div> |
| <div class="sect1"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="quick-start.interpret"></a>4. Interpreting Memcheck's output</h2></div></div></div> |
| <p>Here's an example C program, in a file called a.c, with a memory error |
| and a memory leak.</p> |
| <pre class="programlisting"> |
| #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; |
| } |
| </pre> |
| <p>Most error messages look like the following, which describes |
| problem 1, the heap block overrun:</p> |
| <pre class="programlisting"> |
| ==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) |
| </pre> |
| <p>Things to notice:</p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> |
| <li class="listitem"><p>There is a lot of information in each error message; read it |
| carefully.</p></li> |
| <li class="listitem"><p>The 19182 is the process ID; it's usually unimportant.</p></li> |
| <li class="listitem"><p>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.</p></li> |
| <li class="listitem"><p>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 <code class="option">--num-callers</code> option to make it |
| bigger.</p></li> |
| <li class="listitem"><p>The code addresses (eg. 0x804838F) are usually unimportant, but |
| occasionally crucial for tracking down weirder bugs.</p></li> |
| <li class="listitem"><p>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.</p></li> |
| </ul></div> |
| <p>It's worth fixing errors in the order they are reported, as |
| later errors can be caused by earlier errors. Failing to do this is a |
| common cause of difficulty with Memcheck.</p> |
| <p>Memory leak messages look like this:</p> |
| <pre class="programlisting"> |
| ==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) |
| </pre> |
| <p>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 implementation |
| detail.)</p> |
| <p>There are several kinds of leaks; the two most important |
| categories are:</p> |
| <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> |
| <li class="listitem"><p>"definitely lost": your program is leaking memory -- fix |
| it!</p></li> |
| <li class="listitem"><p>"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).</p></li> |
| </ul></div> |
| <p>Memcheck also reports uses of uninitialised values, most commonly with |
| the message "Conditional jump or move depends on uninitialised |
| value(s)". It can be difficult to determine the root cause of these errors. |
| Try using the <code class="option">--track-origins=yes</code> to get extra information. |
| This makes Memcheck run slower, but the extra information you get often |
| saves a lot of time figuring out where the uninitialised values are coming |
| from.</p> |
| <p>If you don't understand an error message, please consult |
| <a class="xref" href="mc-manual.html#mc-manual.errormsgs" title="4.2. Explanation of error messages from Memcheck">Explanation of error messages from Memcheck</a> in the <a class="xref" href="manual.html" title="Valgrind User Manual">Valgrind User Manual</a> |
| which has examples of all the error messages Memcheck produces.</p> |
| </div> |
| <div class="sect1"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="quick-start.caveats"></a>5. Caveats</h2></div></div></div> |
| <p>Memcheck is not perfect; it occasionally produces false positives, |
| and there are mechanisms for suppressing these (see |
| <a class="xref" href="manual-core.html#manual-core.suppress" title="2.5. Suppressing errors">Suppressing errors</a> in the <a class="xref" href="manual.html" title="Valgrind User Manual">Valgrind User Manual</a>). |
| However, it is typically right 99% of the time, so you should be wary of |
| ignoring its error messages. After all, you wouldn't ignore warning |
| messages produced by a compiler, right? The suppression mechanism is |
| also useful if Memcheck is reporting errors in library code that you |
| cannot change. The default suppression set hides a lot of these, but you |
| may come across more.</p> |
| <p>Memcheck cannot detect every memory error your program has. |
| For example, it can't detect out-of-range reads or writes to arrays |
| that are allocated statically or on the stack. But it should detect many |
| errors that could crash your program (eg. cause a segmentation |
| fault).</p> |
| <p>Try to make your program so clean that Memcheck reports no |
| errors. Once you achieve this state, it is much easier to see when |
| changes to the program cause Memcheck to report new errors. |
| Experience from several years of Memcheck use shows that it is |
| possible to make even huge programs run Memcheck-clean. For example, |
| large parts of KDE, OpenOffice.org and Firefox are Memcheck-clean, or very |
| close to it.</p> |
| </div> |
| <div class="sect1"> |
| <div class="titlepage"><div><div><h2 class="title" style="clear: both"> |
| <a name="quick-start.info"></a>6. More information</h2></div></div></div> |
| <p>Please consult the <a class="xref" href="FAQ.html" title="Valgrind FAQ">Valgrind FAQ</a> and the |
| <a class="xref" href="manual.html" title="Valgrind User Manual">Valgrind User Manual</a>, which have much more information. Note that |
| the other tools in the Valgrind distribution can be invoked with the |
| <code class="option">--tool</code> option.</p> |
| </div> |
| </div> |
| <div> |
| <br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer"> |
| <tr> |
| <td rowspan="2" width="40%" align="left"> |
| <a accesskey="p" href="QuickStart.html"><< The Valgrind Quick Start Guide</a> </td> |
| <td width="20%" align="center"><a accesskey="u" href="QuickStart.html">Up</a></td> |
| <td rowspan="2" width="40%" align="right"> <a accesskey="n" href="manual.html">Valgrind User Manual >></a> |
| </td> |
| </tr> |
| <tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr> |
| </table> |
| </div> |
| </body> |
| </html> |