1 <?xml version="1.0"?> <!-- -*- sgml -*- --> 2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" 3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" 4 [ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]> 5 6 <book id="QuickStart" xreflabel="Valgrind Quick Start Guide"> 7 8 <bookinfo> 9 <title>The Valgrind Quick Start Guide</title> 10 <releaseinfo>&rel-type; &rel-version; &rel-date;</releaseinfo> 11 <copyright> 12 <year>&vg-lifespan;</year> 13 <holder><ulink url="&vg-devs-url;">Valgrind Developers</ulink></holder> 14 </copyright> 15 <legalnotice> 16 <para>Email: <ulink url="mailto:&vg-vemail;">&vg-vemail;</ulink></para> 17 </legalnotice> 18 </bookinfo> 19 20 21 <article id="quick-start"> 22 <title>The Valgrind Quick Start Guide</title> 23 24 25 <sect1 id="quick-start.intro" xreflabel="Introduction"> 26 <title>Introduction</title> 27 28 <para>The Valgrind tool suite provides a number of debugging and 29 profiling tools that help you make your programs faster and more correct. 30 The most popular of these tools is called Memcheck. It can detect many 31 memory-related errors that are common in C and C++ programs and that can 32 lead to crashes and unpredictable behaviour.</para> 33 34 <para>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 </para> 38 39 </sect1> 40 41 42 <sect1 id="quick-start.prepare" xreflabel="Preparing your program"> 43 <title>Preparing your program</title> 44 45 <para>Compile your program with <option>-g</option> to include debugging 46 information so that Memcheck's error messages include exact line 47 numbers. Using <option>-O0</option> is also a good 48 idea, if you can tolerate the slowdown. With 49 <option>-O1</option> line numbers in error messages can 50 be inaccurate, although generally speaking running Memcheck on code compiled 51 at <option>-O1</option> works fairly well, and the speed improvement 52 compared to running <option>-O0</option> is quite significant. 53 Use of 54 <option>-O2</option> and above is not recommended as 55 Memcheck occasionally reports uninitialised-value errors which don't 56 really exist.</para> 57 58 </sect1> 59 60 61 <sect1 id="quick-start.mcrun" xreflabel="Running your program under Memcheck"> 62 <title>Running your program under Memcheck</title> 63 64 <para>If you normally run your program like this:</para> 65 <programlisting> myprog arg1 arg2 66 </programlisting> 67 68 <para>Use this command line:</para> 69 <programlisting> valgrind --leak-check=yes myprog arg1 arg2 70 </programlisting> 71 72 <para>Memcheck is the default tool. The <option>--leak-check</option> 73 option turns on the detailed memory leak detector.</para> 74 75 <para>Your program will run much slower (eg. 20 to 30 times) than 76 normal, and use a lot more memory. Memcheck will issue messages about 77 memory errors and leaks that it detects.</para> 78 79 </sect1> 80 81 82 <sect1 id="quick-start.interpret" 83 xreflabel="Interpreting Memcheck's output"> 84 <title>Interpreting Memcheck's output</title> 85 <para>Here's an example C program, in a file called a.c, with a memory error 86 and a memory leak.</para> 87 88 <programlisting> 89 #include <stdlib.h> 90 91 void f(void) 92 { 93 int* x = malloc(10 * sizeof(int)); 94 x[10] = 0; // problem 1: heap block overrun 95 } // problem 2: memory leak -- x not freed 96 97 int main(void) 98 { 99 f(); 100 return 0; 101 } 102 </programlisting> 103 104 <para>Most error messages look like the following, which describes 105 problem 1, the heap block overrun:</para> 106 107 <programlisting> 108 ==19182== Invalid write of size 4 109 ==19182== at 0x804838F: f (example.c:6) 110 ==19182== by 0x80483AB: main (example.c:11) 111 ==19182== Address 0x1BA45050 is 0 bytes after a block of size 40 alloc'd 112 ==19182== at 0x1B8FF5CD: malloc (vg_replace_malloc.c:130) 113 ==19182== by 0x8048385: f (example.c:5) 114 ==19182== by 0x80483AB: main (example.c:11) 115 </programlisting> 116 117 <para>Things to notice:</para> 118 119 <itemizedlist> 120 <listitem> 121 <para>There is a lot of information in each error message; read it 122 carefully.</para> 123 </listitem> 124 <listitem> 125 <para>The 19182 is the process ID; it's usually unimportant.</para> 126 </listitem> 127 <listitem> 128 <para>The first line ("Invalid write...") tells you what kind of 129 error it is. Here, the program wrote to some memory it should not 130 have due to a heap block overrun.</para> 131 </listitem> 132 <listitem> 133 <para>Below the first line is a stack trace telling you where the 134 problem occurred. Stack traces can get quite large, and be 135 confusing, especially if you are using the C++ STL. Reading them 136 from the bottom up can help. If the stack trace is not big enough, 137 use the <option>--num-callers</option> option to make it 138 bigger.</para> 139 </listitem> 140 <listitem> 141 <para>The code addresses (eg. 0x804838F) are usually unimportant, but 142 occasionally crucial for tracking down weirder bugs.</para> 143 </listitem> 144 <listitem> 145 <para>Some error messages have a second component which describes 146 the memory address involved. This one shows that the written memory 147 is just past the end of a block allocated with malloc() on line 5 of 148 example.c.</para> 149 </listitem> 150 </itemizedlist> 151 152 <para>It's worth fixing errors in the order they are reported, as 153 later errors can be caused by earlier errors. Failing to do this is a 154 common cause of difficulty with Memcheck.</para> 155 156 <para>Memory leak messages look like this:</para> 157 158 <programlisting> 159 ==19182== 40 bytes in 1 blocks are definitely lost in loss record 1 of 1 160 ==19182== at 0x1B8FF5CD: malloc (vg_replace_malloc.c:130) 161 ==19182== by 0x8048385: f (a.c:5) 162 ==19182== by 0x80483AB: main (a.c:11) 163 </programlisting> 164 165 <para>The stack trace tells you where the leaked memory was allocated. 166 Memcheck cannot tell you why the memory leaked, unfortunately. 167 (Ignore the "vg_replace_malloc.c", that's an implementation 168 detail.)</para> 169 170 <para>There are several kinds of leaks; the two most important 171 categories are:</para> 172 173 <itemizedlist> 174 <listitem> 175 <para>"definitely lost": your program is leaking memory -- fix 176 it!</para> 177 </listitem> 178 <listitem> 179 <para>"probably lost": your program is leaking memory, unless you're 180 doing funny things with pointers (such as moving them to point to 181 the middle of a heap block).</para> 182 </listitem> 183 </itemizedlist> 184 185 <para>Memcheck also reports uses of uninitialised values, most commonly with 186 the message "Conditional jump or move depends on uninitialised 187 value(s)". It can be difficult to determine the root cause of these errors. 188 Try using the <option>--track-origins=yes</option> to get extra information. 189 This makes Memcheck run slower, but the extra information you get often 190 saves a lot of time figuring out where the uninitialised values are coming 191 from.</para> 192 193 <para>If you don't understand an error message, please consult 194 <xref linkend="mc-manual.errormsgs"/> in the <xref linkend="manual"/> 195 which has examples of all the error messages Memcheck produces.</para> 196 197 </sect1> 198 199 200 <sect1 id="quick-start.caveats" xreflabel="Caveats"> 201 <title>Caveats</title> 202 203 <para>Memcheck is not perfect; it occasionally produces false positives, 204 and there are mechanisms for suppressing these (see 205 <xref linkend="manual-core.suppress"/> in the <xref linkend="manual"/>). 206 However, it is typically right 99% of the time, so you should be wary of 207 ignoring its error messages. After all, you wouldn't ignore warning 208 messages produced by a compiler, right? The suppression mechanism is 209 also useful if Memcheck is reporting errors in library code that you 210 cannot change. The default suppression set hides a lot of these, but you 211 may come across more.</para> 212 213 <para>Memcheck cannot detect every memory error your program has. 214 For example, it can't detect out-of-range reads or writes to arrays 215 that are allocated statically or on the stack. But it should detect many 216 errors that could crash your program (eg. cause a segmentation 217 fault).</para> 218 219 <para>Try to make your program so clean that Memcheck reports no 220 errors. Once you achieve this state, it is much easier to see when 221 changes to the program cause Memcheck to report new errors. 222 Experience from several years of Memcheck use shows that it is 223 possible to make even huge programs run Memcheck-clean. For example, 224 large parts of KDE, OpenOffice.org and Firefox are Memcheck-clean, or very 225 close to it.</para> 226 227 228 </sect1> 229 230 231 <sect1 id="quick-start.info" xreflabel="More Information"> 232 <title>More information</title> 233 234 <para>Please consult the <xref linkend="FAQ"/> and the 235 <xref linkend="manual"/>, which have much more information. Note that 236 the other tools in the Valgrind distribution can be invoked with the 237 <option>--tool</option> option.</para> 238 239 </sect1> 240 241 242 </article> 243 </book> 244
