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
29profiling tools that help you make your programs faster and more correct.
30The most popular of these tools is called Memcheck.  It can detect many
31memory-related errors that are common in C and C++ programs and that can
32lead to crashes and unpredictable behaviour.</para>
33
34<para>The rest of this guide gives the minimum information you need to start
35detecting memory errors in your program with Memcheck.  For full
36documentation 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
46information so that Memcheck's error messages include exact line
47numbers.  Using <option>-O0</option> is also a good
48idea, if you can tolerate the slowdown.  With
49<option>-O1</option> line numbers in error messages can
50be inaccurate, although generally speaking running Memcheck on code compiled
51at <option>-O1</option> works fairly well, and the speed improvement
52compared to running <option>-O0</option> is quite significant.
53Use of
54<option>-O2</option> and above is not recommended as
55Memcheck occasionally reports uninitialised-value errors which don't
56really 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>
73option turns on the detailed memory leak detector.</para>
74
75<para>Your program will run much slower (eg. 20 to 30 times) than
76normal, and use a lot more memory.  Memcheck will issue messages about
77memory 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
86and a memory leak.</para>
87
88<programlisting>
89  #include &lt;stdlib.h&gt;
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
105problem 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
153later errors can be caused by earlier errors.  Failing to do this is a
154common 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.
166Memcheck cannot tell you why the memory leaked, unfortunately.
167(Ignore the "vg_replace_malloc.c", that's an implementation
168detail.)</para>
169
170<para>There are several kinds of leaks; the two most important
171categories 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
186the message "Conditional jump or move depends on uninitialised
187value(s)".  It can be difficult to determine the root cause of these errors.
188Try using the <option>--track-origins=yes</option> to get extra information.
189This makes Memcheck run slower, but the extra information you get often
190saves a lot of time figuring out where the uninitialised values are coming
191from.</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"/>
195which 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,
204and there are mechanisms for suppressing these (see
205<xref linkend="manual-core.suppress"/> in the <xref linkend="manual"/>).
206However, it is typically right 99% of the time, so you should be wary of
207ignoring its error messages.  After all, you wouldn't ignore warning
208messages produced by a compiler, right?  The suppression mechanism is
209also useful if Memcheck is reporting errors in library code that you
210cannot change.  The default suppression set hides a lot of these, but you
211may come across more.</para>
212
213<para>Memcheck cannot detect every memory error your program has.
214For example, it can't detect out-of-range reads or writes to arrays
215that are allocated statically or on the stack.  But it should detect many
216errors that could crash your program (eg. cause a segmentation
217fault).</para>
218
219<para>Try to make your program so clean that Memcheck reports no
220errors.  Once you achieve this state, it is much easier to see when
221changes to the program cause Memcheck to report new errors.
222Experience from several years of Memcheck use shows that it is
223possible to make even huge programs run Memcheck-clean.  For example,
224large parts of KDE, OpenOffice.org and Firefox are Memcheck-clean, or very
225close 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
236the 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