|
From: <sv...@va...> - 2005-08-03 22:42:37
|
Author: de
Date: 2005-08-03 23:42:35 +0100 (Wed, 03 Aug 2005)
New Revision: 159
Log:
updated doc
Modified:
trunk/docs/quick-start.html
Modified: trunk/docs/quick-start.html
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=
=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D
--- trunk/docs/quick-start.html 2005-08-03 22:39:44 UTC (rev 158)
+++ trunk/docs/quick-start.html 2005-08-03 22:42:35 UTC (rev 159)
@@ -1,166 +1,206 @@
-<h1>Valgrind Quick Start</h1>
-
-<p>The Valgrind distribution has multiple tools. The memory
-checking tool (called Memcheck) can detect many common memory
-errors such as:</p>
-
-<ul>
-
- <li>touching memory you shouldn't (eg. overrunning heap block
- boundaries)</li>
-
- <li>using values before they have been initialized</li>
-
- <li>incorrect freeing of memory, such as double-freeing heap
- blocks</li>
-
- <li>memory leaks</li>
-
-</ul>
-
-<p>What follows is the minimum information you need to start
-detecting memory errors in your program with Memcheck. Note that
-this guide applies to Valgrind version 2.4.0; some of the
-information is not quite right for earlier versions.</p>
-
-
-<h3>1. Preparing your program.</h3>
-
-<p>Compile your program with <code>-g</code> to include debugging
-information so that Memcheck's error messages include exact line
+<div><table class=3D"nav" width=3D"100%" cellspacing=3D"3" cellpadding=3D=
"3" border=3D"0" summary=3D"Navigation header"><tr>
+<td width=3D"22px" align=3D"center" valign=3D"middle"><a accesskey=3D"p"=
href=3D"index.html"><img src=3D"images/prev.png" width=3D"18" height=3D"=
21" border=3D"0" alt=3D"Prev"></a></td>
+<td width=3D"25px" align=3D"center" valign=3D"middle"><a accesskey=3D"u"=
href=3D"index.html"><img src=3D"images/up.png" width=3D"21" height=3D"18=
" border=3D"0" alt=3D"Up"></a></td>
+<td width=3D"31px" align=3D"center" valign=3D"middle"><a accesskey=3D"h"=
href=3D"index.html"><img src=3D"images/home.png" width=3D"27" height=3D"=
20" border=3D"0" alt=3D"Up"></a></td>
+<th align=3D"center" valign=3D"middle">Valgrind Documentation</th>
+<td width=3D"22px" align=3D"center" valign=3D"middle"><a accesskey=3D"n"=
href=3D"manual.html"><img src=3D"images/next.png" width=3D"18" height=3D=
"21" border=3D"0" alt=3D"Next"></a></td>
+</tr></table></div>
+<div class=3D"book" lang=3D"en">
+<div class=3D"titlepage">
+<div><div><h1 class=3D"title">
+<a name=3D"quick-start"></a>Valgrind Quick Start Guide</h1></div></div>
+<div></div>
+<hr>
+</div>
+<p>The Valgrind distribution has multiple tools. The most popular is th=
e
+memory checking tool (called Memcheck) which can detect many common memo=
ry
+errors such as:
+</p>
+<div class=3D"itemizedlist"><ul type=3D"disc">
+<li><p>touching memory you shouldn't (eg. overrunning heap block=20
+ boundaries);</p></li>
+<li><p>using values before they have been initialized;</p></li>
+<li><p>incorrect freeing of memory, such as double-freeing heap
+ blocks;</p></li>
+<li><p>memory leaks;</p></li>
+</ul></div>
+<p>What follows is the minimum information you need to start detecting
+memory errors in your program with Memcheck. Note that this guide appli=
es
+to Valgrind version 2.4.0 and later; some of the information is not qui=
te
+right for earlier versions.</p>
+<div class=3D"sect1" lang=3D"en">
+<div class=3D"titlepage">
+<div><div><h2 class=3D"title" style=3D"clear: both">
+<a name=3D"quick-start.prepare"></a>1.=A0Preparing your program</h2></di=
v></div>
+<div></div>
+</div>
+<p>Compile your program with <tt class=3D"computeroutput">-g</tt> to inc=
lude
+debugging information so that Memcheck's error messages include exact li=
ne
numbers.</p>
+</div>
+<div class=3D"sect1" lang=3D"en">
+<div class=3D"titlepage">
+<div><div><h2 class=3D"title" style=3D"clear: both">
+<a name=3D"quick-start.mcrun"></a>2.=A0Running your program under Memche=
ck</h2></div></div>
+<div></div>
+</div>
+<p>If you normally run your program like this:
=20
+</p>
+<pre class=3D"programlisting">
+ myprog arg1 arg2
+</pre>
+<p>
=20
-<h3>2. Running your program under Memcheck.</h3>
+Use this command line:
=20
-<p>If you normally run your program like this:=20
-<code>myprog arg1 arg2</code></p>
+</p>
+<pre class=3D"programlisting">
+ valgrind --leak-check=3Dyes myprog arg1 arg2
+</pre>
+<p>
=20
-<p>Use this command line:=20
-<code>valgrind --leak-check=3Dyes myprog arg1 arg2</code></p>
+Memcheck is the default tool. The
+<tt class=3D"computeroutput">--leak-check</tt> option turns on the detai=
led
+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 er=
rors
+and leaks that it detects.</p>
+</div>
+<div class=3D"sect1" lang=3D"en">
+<div class=3D"titlepage">
+<div><div><h2 class=3D"title" style=3D"clear: both">
+<a name=3D"quick-start.interpret"></a>3.=A0Interpreting Memcheck's outpu=
t</h2></div></div>
+<div></div>
+</div>
+<p>Here's an example C program with a memory error and a memory leak.
=20
-<p>Memcheck is the default tool. The <code>--leak-check</code>
-option turns on the memory leak detector.</p>
+</p>
+<pre class=3D"programlisting">
+ #include <stdlib.h>
=20
-<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>
+ void f(void)
+ {
+ int* x =3D malloc(10 * sizeof(int));
+ x[10] =3D 0; // problem 1: heap block overrun
+ } // problem 2: memory leak -- x not freed
=20
-
-<h3>3. Interpreting Memcheck's output.</h3>
-
-<p>Here's an example C program with a memory errors and a memory
-leak.</p>
-
-<pre>
-#include <stdlib.h>
-
-void f(void) {
- int* x =3D malloc(10 * sizeof(int));
- x[10] =3D 0; // problem 1: heap block overrun
-} // problem 2: memory leak -- x not freed
-
-int main(void) {
- f();
- return 0;
-}
+ int main(void)
+ {
+ f();
+ return 0;
+ }
</pre>
+<p>
=20
-<p>Most error messages look like the following, which describes
-problem 1, the heap block overrun:</p>
+Most error messages look like the following, which describes problem 1, =
the
+heap block overrun:
=20
-<pre>
- =3D=3D19182=3D=3D Invalid write of size 4
- =3D=3D19182=3D=3D at 0x804838F: f (example.c:8)
- =3D=3D19182=3D=3D by 0x80483AB: main (example.c:14)
- =3D=3D19182=3D=3D Address 0x1BA45050 is 0 bytes after a block of size =
40 alloc'd
- =3D=3D19182=3D=3D at 0x1B8FF5CD: malloc (vg_replace_malloc.c:130)
- =3D=3D19182=3D=3D by 0x8048385: f (example.c:7)
- =3D=3D19182=3D=3D by 0x80483AB: main (example.c:14)
+</p>
+<pre class=3D"programlisting">
+ =3D=3D19182=3D=3D Invalid write of size 4
+ =3D=3D19182=3D=3D at 0x804838F: f (example.c:6)
+ =3D=3D19182=3D=3D by 0x80483AB: main (example.c:11)
+ =3D=3D19182=3D=3D Address 0x1BA45050 is 0 bytes after a block of size=
40 alloc'd
+ =3D=3D19182=3D=3D at 0x1B8FF5CD: malloc (vg_replace_malloc.c:130)
+ =3D=3D19182=3D=3D by 0x8048385: f (example.c:5)
+ =3D=3D19182=3D=3D by 0x80483AB: main (example.c:11)
</pre>
+<p>
=20
+Things to notice:
=20
-<p>Things to notice:</p>
+</p>
+<div class=3D"itemizedlist"><ul type=3D"disc">
+<li><p>There is a lot of information in each error message; read it
+ carefully.</p></li>
+<li><p>The 19182 is the process ID; it's usually unimportant.</p></li>
+<li><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><p>Below the first line is a stack trace telling you where the probl=
em
+ occurred. Stack traces can get quite large, and be confusing, especi=
ally
+ if you are using the C++ STL. Reading them from the bottom up can he=
lp.
+ If the stack trace is not big enough, use the
+ <tt class=3D"computeroutput">--num-callers</tt> option to make it
+ bigger.</p></li>
+<li><p>The addresses (eg. 0x804838F) are usually unimportant, but occasi=
onally
+ crucial for tracking down weirder bugs.</p></li>
+<li><p>Some error messages have a second component which describes the m=
emory
+ address involved. This one shows that the written memory is just pas=
t
+ the end of a block allocated with malloc() on line 7 of example.c.</p=
></li>
+</ul></div>
+<p>
=20
-<ul>
+It's worth fixing errors in the order they are reported, as later
+errors can be caused by earlier errors.</p>
+<p>Memory leak messages look like this:
=20
-<li>There is a lot of information in each error message; read it
- carefully.</li>
-
-<li>The 19182 is the process ID; it's usually unimportant.</li>
-
-<li>The first line ("Invalid write...") tells you what the error
- is. Here, the program wrote to some memory it should not have
- due to a heap block overrun.</li>
-
-<li>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 a bigger <code>--num-callers</code>
- option.</li>
-
-<li>The addresses (eg. 0x804838F) are usually unimportant, but
- occasionally crucial for tracking down weirder bugs.</li>
-
-<li>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 7 of example.c.</li>
-
-</ul>
-
-<p>It's worth fixing errors in the order they are reported, as
-later errors can be caused by earlier errors.</p>
-
-<p>Memory leak messages look like this:</p>
-<pre>
- =3D=3D19182=3D=3D 40 bytes in 1 blocks are definitely lost in loss reco=
rd 1 of 1
- =3D=3D19182=3D=3D at 0x1B8FF5CD: malloc (vg_replace_malloc.c:130)
- =3D=3D19182=3D=3D by 0x8048385: f (a.c:7)
- =3D=3D19182=3D=3D by 0x80483AB: main (a.c:14)
+</p>
+<pre class=3D"programlisting">
+ =3D=3D19182=3D=3D 40 bytes in 1 blocks are definitely lost in loss rec=
ord 1 of 1
+ =3D=3D19182=3D=3D at 0x1B8FF5CD: malloc (vg_replace_malloc.c:130)
+ =3D=3D19182=3D=3D by 0x8048385: f (a.c:7)
+ =3D=3D19182=3D=3D by 0x80483AB: main (a.c:14)
</pre>
+<p>
=20
-<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>
+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:
=20
+</p>
+<div class=3D"itemizedlist"><ul type=3D"disc">
+<li><p>"definitely lost": your program is leaking memory -- fix
+ it!</p></li>
+<li><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>
=20
-<p>There are several kinds of leaks; the two most important
-categories are:</p>
-<ul>
- <li>"definitely lost": your program is leaking memory -- fix it!</li>
-
- <li>"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).</li>
-</ul>
-
-<p>If you don't understand an error message, please consult
-section 3 of the User Manual which has examples of all the error
-messages Memcheck produces.</p>
-
-
-<h3>4. Caveats.</h3>
-
-<p>Memcheck is not perfect; it occasionally produces false
-positives, and there are mechanisms for suppressing these (see
-"suppressions" in the User Manual). 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?</p>
-
-<p>Memcheck also cannot detect every memory error your program
-has. For example, it can't detect if you overrun the bounds of
-an array that is allocated statically or on the stack.</p>
-
-
-
-<h3>5. More information.</h3>
-
-<p>Please consult the FAQ and the User Manual, which have much
-more information. Note that the other tools in the Valgrind
-distribution can be invoked with the <code>--tool</code>
-option.</p>
-
+If you don't understand an error message, please consult
+<a href=3D"mc-manual.html#mc-manual.errormsgs">Explanation of error mess=
ages from Memcheck</a> in the <a href=3D"manual.html">Valgrind User Manua=
l</a> which has
+examples of all the error messages Memcheck produces.</p>
+</div>
+<div class=3D"sect1" lang=3D"en">
+<div class=3D"titlepage">
+<div><div><h2 class=3D"title" style=3D"clear: both">
+<a name=3D"quick-start.caveats"></a>4.=A0Caveats</h2></div></div>
+<div></div>
+</div>
+<p>Memcheck is not perfect; it occasionally produces false positives,
+and there are mechanisms for suppressing these (see
+<a href=3D"manual-core.html#manual-core.suppress">Suppressing errors</a>=
in the <a href=3D"manual.html">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?</p>
+<p>Memcheck also cannot detect every memory error your program has. For
+example, it can't detect if you overrun the bounds of an array that is
+allocated statically or on the stack.</p>
+</div>
+<div class=3D"sect1" lang=3D"en">
+<div class=3D"titlepage">
+<div><div><h2 class=3D"title" style=3D"clear: both">
+<a name=3D"quick-start.info"></a>5.=A0More information</h2></div></div>
+<div></div>
+</div>
+<p>Please consult the <a href=3D"FAQ.html">Valgrind FAQ</a> and the
+<a href=3D"manual.html">Valgrind User Manual</a>, which have much more i=
nformation. Note that the
+other tools in the Valgrind distribution can be invoked with the
+<tt class=3D"computeroutput">--tool</tt> option.</p>
+</div>
+</div>
+<div>
+<br><table class=3D"nav" width=3D"100%" cellspacing=3D"3" cellpadding=3D=
"2" border=3D"0" summary=3D"Navigation footer">
+<tr>
+<td rowspan=3D"2" width=3D"40%" align=3D"left">
+<a accesskey=3D"p" href=3D"index.html"><<=A0Valgrind Documentation=
</a>=A0</td>
+<td width=3D"20%" align=3D"center"><a accesskey=3D"u" href=3D"index.html=
">Up</a></td>
+<td rowspan=3D"2" width=3D"40%" align=3D"right">=A0<a accesskey=3D"n" hr=
ef=3D"manual.html">Valgrind User Manual=A0>></a>
+</td>
+</tr>
+<tr><td width=3D"20%" align=3D"center"><a accesskey=3D"h" href=3D"index.=
html">Home</a></td></tr>
+</table>
+</div>
|