1 <html> 2 <head> 3 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 4 <title>The Valgrind Quick Start Guide</title> 5 <link rel="stylesheet" type="text/css" href="vg_basic.css"> 6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7 <link rel="home" href="index.html" title="Valgrind Documentation"> 8 <link rel="up" href="QuickStart.html" title="The Valgrind Quick Start Guide"> 9 <link rel="prev" href="QuickStart.html" title="The Valgrind Quick Start Guide"> 10 <link rel="next" href="manual.html" title="Valgrind User Manual"> 11 </head> 12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"> 13 <div><table class="nav" width="100%" cellspacing="3" cellpadding="3" border="0" summary="Navigation header"><tr> 14 <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> 15 <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> 16 <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> 17 <th align="center" valign="middle">The Valgrind Quick Start Guide</th> 18 <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> 19 </tr></table></div> 20 <div class="article"> 21 <div class="titlepage"> 22 <div><div><h1 class="title"> 23 <a name="quick-start"></a>The Valgrind Quick Start Guide</h1></div></div> 24 <hr> 25 </div> 26 <div class="sect1"> 27 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 28 <a name="quick-start.intro"></a>1.Introduction</h2></div></div></div> 29 <p>The Valgrind tool suite provides a number of debugging and 30 profiling tools that help you make your programs faster and more correct. 31 The most popular of these tools is called Memcheck. It can detect many 32 memory-related errors that are common in C and C++ programs and that can 33 lead to crashes and unpredictable behaviour.</p> 34 <p>The rest of this guide gives the minimum information you need to start 35 detecting memory errors in your program with Memcheck. For full 36 documentation of Memcheck and the other tools, please read the User Manual. 37 </p> 38 </div> 39 <div class="sect1"> 40 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 41 <a name="quick-start.prepare"></a>2.Preparing your program</h2></div></div></div> 42 <p>Compile your program with <code class="option">-g</code> to include debugging 43 information so that Memcheck's error messages include exact line 44 numbers. Using <code class="option">-O0</code> is also a good 45 idea, if you can tolerate the slowdown. With 46 <code class="option">-O1</code> line numbers in error messages can 47 be inaccurate, although generally speaking running Memcheck on code compiled 48 at <code class="option">-O1</code> works fairly well, and the speed improvement 49 compared to running <code class="option">-O0</code> is quite significant. 50 Use of 51 <code class="option">-O2</code> and above is not recommended as 52 Memcheck occasionally reports uninitialised-value errors which don't 53 really exist.</p> 54 </div> 55 <div class="sect1"> 56 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 57 <a name="quick-start.mcrun"></a>3.Running your program under Memcheck</h2></div></div></div> 58 <p>If you normally run your program like this:</p> 59 <pre class="programlisting"> myprog arg1 arg2 60 </pre> 61 <p>Use this command line:</p> 62 <pre class="programlisting"> valgrind --leak-check=yes myprog arg1 arg2 63 </pre> 64 <p>Memcheck is the default tool. The <code class="option">--leak-check</code> 65 option turns on the detailed memory leak detector.</p> 66 <p>Your program will run much slower (eg. 20 to 30 times) than 67 normal, and use a lot more memory. Memcheck will issue messages about 68 memory errors and leaks that it detects.</p> 69 </div> 70 <div class="sect1"> 71 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 72 <a name="quick-start.interpret"></a>4.Interpreting Memcheck's output</h2></div></div></div> 73 <p>Here's an example C program, in a file called a.c, with a memory error 74 and a memory leak.</p> 75 <pre class="programlisting"> 76 #include <stdlib.h> 77 78 void f(void) 79 { 80 int* x = malloc(10 * sizeof(int)); 81 x[10] = 0; // problem 1: heap block overrun 82 } // problem 2: memory leak -- x not freed 83 84 int main(void) 85 { 86 f(); 87 return 0; 88 } 89 </pre> 90 <p>Most error messages look like the following, which describes 91 problem 1, the heap block overrun:</p> 92 <pre class="programlisting"> 93 ==19182== Invalid write of size 4 94 ==19182== at 0x804838F: f (example.c:6) 95 ==19182== by 0x80483AB: main (example.c:11) 96 ==19182== Address 0x1BA45050 is 0 bytes after a block of size 40 alloc'd 97 ==19182== at 0x1B8FF5CD: malloc (vg_replace_malloc.c:130) 98 ==19182== by 0x8048385: f (example.c:5) 99 ==19182== by 0x80483AB: main (example.c:11) 100 </pre> 101 <p>Things to notice:</p> 102 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 103 <li class="listitem"><p>There is a lot of information in each error message; read it 104 carefully.</p></li> 105 <li class="listitem"><p>The 19182 is the process ID; it's usually unimportant.</p></li> 106 <li class="listitem"><p>The first line ("Invalid write...") tells you what kind of 107 error it is. Here, the program wrote to some memory it should not 108 have due to a heap block overrun.</p></li> 109 <li class="listitem"><p>Below the first line is a stack trace telling you where the 110 problem occurred. Stack traces can get quite large, and be 111 confusing, especially if you are using the C++ STL. Reading them 112 from the bottom up can help. If the stack trace is not big enough, 113 use the <code class="option">--num-callers</code> option to make it 114 bigger.</p></li> 115 <li class="listitem"><p>The code addresses (eg. 0x804838F) are usually unimportant, but 116 occasionally crucial for tracking down weirder bugs.</p></li> 117 <li class="listitem"><p>Some error messages have a second component which describes 118 the memory address involved. This one shows that the written memory 119 is just past the end of a block allocated with malloc() on line 5 of 120 example.c.</p></li> 121 </ul></div> 122 <p>It's worth fixing errors in the order they are reported, as 123 later errors can be caused by earlier errors. Failing to do this is a 124 common cause of difficulty with Memcheck.</p> 125 <p>Memory leak messages look like this:</p> 126 <pre class="programlisting"> 127 ==19182== 40 bytes in 1 blocks are definitely lost in loss record 1 of 1 128 ==19182== at 0x1B8FF5CD: malloc (vg_replace_malloc.c:130) 129 ==19182== by 0x8048385: f (a.c:5) 130 ==19182== by 0x80483AB: main (a.c:11) 131 </pre> 132 <p>The stack trace tells you where the leaked memory was allocated. 133 Memcheck cannot tell you why the memory leaked, unfortunately. 134 (Ignore the "vg_replace_malloc.c", that's an implementation 135 detail.)</p> 136 <p>There are several kinds of leaks; the two most important 137 categories are:</p> 138 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 139 <li class="listitem"><p>"definitely lost": your program is leaking memory -- fix 140 it!</p></li> 141 <li class="listitem"><p>"probably lost": your program is leaking memory, unless you're 142 doing funny things with pointers (such as moving them to point to 143 the middle of a heap block).</p></li> 144 </ul></div> 145 <p>Memcheck also reports uses of uninitialised values, most commonly with 146 the message "Conditional jump or move depends on uninitialised 147 value(s)". It can be difficult to determine the root cause of these errors. 148 Try using the <code class="option">--track-origins=yes</code> to get extra information. 149 This makes Memcheck run slower, but the extra information you get often 150 saves a lot of time figuring out where the uninitialised values are coming 151 from.</p> 152 <p>If you don't understand an error message, please consult 153 <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> 154 which has examples of all the error messages Memcheck produces.</p> 155 </div> 156 <div class="sect1"> 157 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 158 <a name="quick-start.caveats"></a>5.Caveats</h2></div></div></div> 159 <p>Memcheck is not perfect; it occasionally produces false positives, 160 and there are mechanisms for suppressing these (see 161 <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>). 162 However, it is typically right 99% of the time, so you should be wary of 163 ignoring its error messages. After all, you wouldn't ignore warning 164 messages produced by a compiler, right? The suppression mechanism is 165 also useful if Memcheck is reporting errors in library code that you 166 cannot change. The default suppression set hides a lot of these, but you 167 may come across more.</p> 168 <p>Memcheck cannot detect every memory error your program has. 169 For example, it can't detect out-of-range reads or writes to arrays 170 that are allocated statically or on the stack. But it should detect many 171 errors that could crash your program (eg. cause a segmentation 172 fault).</p> 173 <p>Try to make your program so clean that Memcheck reports no 174 errors. Once you achieve this state, it is much easier to see when 175 changes to the program cause Memcheck to report new errors. 176 Experience from several years of Memcheck use shows that it is 177 possible to make even huge programs run Memcheck-clean. For example, 178 large parts of KDE, OpenOffice.org and Firefox are Memcheck-clean, or very 179 close to it.</p> 180 </div> 181 <div class="sect1"> 182 <div class="titlepage"><div><div><h2 class="title" style="clear: both"> 183 <a name="quick-start.info"></a>6.More information</h2></div></div></div> 184 <p>Please consult the <a class="xref" href="FAQ.html" title="Valgrind FAQ">Valgrind FAQ</a> and the 185 <a class="xref" href="manual.html" title="Valgrind User Manual">Valgrind User Manual</a>, which have much more information. Note that 186 the other tools in the Valgrind distribution can be invoked with the 187 <code class="option">--tool</code> option.</p> 188 </div> 189 </div> 190 <div> 191 <br><table class="nav" width="100%" cellspacing="3" cellpadding="2" border="0" summary="Navigation footer"> 192 <tr> 193 <td rowspan="2" width="40%" align="left"> 194 <a accesskey="p" href="QuickStart.html"><<The Valgrind Quick Start Guide</a></td> 195 <td width="20%" align="center"><a accesskey="u" href="QuickStart.html">Up</a></td> 196 <td rowspan="2" width="40%" align="right"><a accesskey="n" href="manual.html">Valgrind User Manual>></a> 197 </td> 198 </tr> 199 <tr><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td></tr> 200 </table> 201 </div> 202 </body> 203 </html> 204
