mirror of
https://github.com/ioacademy-jikim/debugging
synced 2025-06-08 00:16:11 +00:00
204 lines
11 KiB
HTML
204 lines
11 KiB
HTML
<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.78.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>
|