[ <!ENTITY % vg-entities SYSTEM "../../docs/xml/vg-entities.xml"> %vg-entities; ]>
-<chapter id="cg-manual" xreflabel="Cachegrind: a cache-miss profiler">
-<title>Cachegrind: a cache and branch profiler</title>
-
-<sect1 id="cg-manual.cache" xreflabel="Cache profiling">
-<title>Cache and branch profiling</title>
+<chapter id="cg-manual" xreflabel="Cachegrind: a cache and branch-prediction profiler">
+<title>Cachegrind: a cache and branch-prediction profiler</title>
<para>To use this tool, you must specify
<computeroutput>--tool=cachegrind</computeroutput> on the
Valgrind command line.</para>
-<para>Cachegrind is a tool for finding places where programs
-interact badly with typical modern superscalar processors
-and run slowly as a result.
-In particular, it will do a cache simulation of your program,
-and optionally a branch-predictor simulation, and can
-then annotate your source line-by-line with the number of cache
-misses and branch mispredictions. The following statistics are
-collected:</para>
+<sect1 id="cg-manual.overview" xreflabel="Overview">
+<title>Overview</title>
+
+<para>Cachegrind simulates how your program interacts with a machine's cache
+hierarchy and (optionally) branch predictor. It gathers the following
+statistics:</para>
<itemizedlist>
<listitem>
- <para>L1 instruction cache reads and misses;</para>
+ <para>L1 instruction cache reads and read misses;</para>
</listitem>
<listitem>
<para>L1 data cache reads and read misses, writes and write
</listitem>
</itemizedlist>
+<para>These statistics are presented for the entire program and for each
+function in the program. You can also annotate each line of source code in
+the program with the counts that were caused directly by it.</para>
+
<para>On a modern machine, an L1 miss will typically cost
around 10 cycles, an L2 miss can cost as much as 200
cycles, and a mispredicted branch costs in the region of 10
to 30 cycles. Detailed cache and branch profiling can be very useful
-for improving the performance of your program.</para>
+for understanding how your program interacts with the machine and thus how
+to make it faster.</para>
<para>Also, since one instruction cache read is performed per
instruction executed, you can find out how many instructions are
-executed per line, which can be useful for traditional profiling
-and test coverage.</para>
+executed per line, which can be useful for traditional profiling.</para>
<para>Branch profiling is not enabled by default. To use it, you must
additionally specify <computeroutput>--branch-sim=yes</computeroutput>
on the command line.</para>
-<sect2 id="cg-manual.overview" xreflabel="Overview">
-<title>Overview</title>
+<sect2 id="cg-manual.basics" xreflabel="Basics">
+<title>Basics</title>
<para>First off, as for normal Valgrind use, you probably want to
compile with debugging info (the
<para>The cache configuration simulated (cache size,
associativity and line size) is determined automagically using
-the CPUID instruction. If you have an old machine that (a)
+the x86 CPUID instruction. If you have an machine that (a)
doesn't support the CPUID instruction, or (b) supports it in an
early incarnation that doesn't give any cache information, then
Cachegrind will fall back to using a default configuration (that
[ <!ENTITY % cl-entities SYSTEM "cl-entities.xml"> %cl-entities; ]>
<chapter id="cl-manual" xreflabel="Callgrind Manual">
-<title>Callgrind: a call graph profiler</title>
+<title>Callgrind: a call-graph generating cache profiler</title>
+<para>To use this tool, you must specify
+<computeroutput>--tool=callgrind</computeroutput> on the
+Valgrind command line.</para>
+
<sect1 id="cl-manual.use" xreflabel="Overview">
<title>Overview</title>
" Extra options read from ~/.valgrindrc, $VALGRIND_OPTS, ./.valgrindrc\n"
"\n"
" %s is %s\n"
-" Valgrind is Copyright (C) 2000-2009, and GNU GPL'd, by Julian Seward et al\n"
-" LibVEX is Copyright (C) 2004-2009, and GNU GPL'd, by OpenWorks LLP\n"
+" Valgrind is Copyright (C) 2000-2009, and GNU GPL'd, by Julian Seward et al.\n"
+" LibVEX is Copyright (C) 2004-2009, and GNU GPL'd, by OpenWorks LLP.\n"
"\n"
" Bug reports, feedback, admiration, abuse, etc, to: %s.\n"
"\n";
<?xml version="1.0"?> <!-- -*- sgml -*- -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
- "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+ "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"
+[ <!ENTITY % vg-entities SYSTEM "vg-entities.xml"> %vg-entities; ]>
<chapter id="manual-intro" xreflabel="Introduction">
<title>Introduction</title>
<sect1 id="manual-intro.overview" xreflabel="An Overview of Valgrind">
<title>An Overview of Valgrind</title>
-<para>Valgrind is a suite of simulation-based debugging and profiling
-tools for programs running on Linux (x86, amd64, ppc32 and ppc64).
-The system consists of a core, which provides a synthetic CPU in
-software, and a set of tools, each of which performs some kind of
-debugging, profiling, or similar task. The architecture is modular,
-so that new tools can be created easily and without disturbing the
-existing structure.</para>
+<para>Valgrind is an instrumentation framework for building dynamic analysis
+tools. It comes with a set of tools each of which performs some kind of
+debugging, profiling, or similar task that helps you improve your programs.
+Valgrind's architecture is modular, so new tools can be created easily
+and without disturbing the existing structure.</para>
-<para>A number of useful tools are supplied as standard. In
-summary, these are:</para>
+<para>A number of useful tools are supplied as standard.</para>
<orderedlist>
<listitem>
- <para><command>Memcheck</command> detects memory-management problems
- in programs. All reads and writes of memory are checked, and
- calls to malloc/new/free/delete are intercepted. As a result,
- Memcheck can detect the following problems:</para>
-
- <itemizedlist>
- <listitem>
- <para>Use of uninitialised memory</para>
- </listitem>
- <listitem>
- <para>Reading/writing memory after it has been
- free'd</para>
- </listitem>
- <listitem>
- <para>Reading/writing off the end of malloc'd
- blocks</para>
- </listitem>
- <listitem>
- <para>Reading/writing inappropriate areas on the
- stack</para>
- </listitem>
- <listitem>
- <para>Memory leaks -- where pointers to malloc'd
- blocks are lost forever</para>
- </listitem>
- <listitem>
- <para>Mismatched use of malloc/new/new [] vs
- free/delete/delete []</para>
- </listitem>
- <listitem>
- <para>Overlapping <computeroutput>src</computeroutput> and
- <computeroutput>dst</computeroutput> pointers in
- <computeroutput>memcpy()</computeroutput> and related
- functions</para></listitem>
- </itemizedlist>
-
- <para>Problems like these can be difficult to find by other means,
- often remaining undetected for long periods, then causing occasional,
- difficult-to-diagnose crashes.</para>
- </listitem>
+ <para><command>Memcheck</command> is a memory error detector. It helps
+ you make your programs, particularly those written in C and C++, more
+ correct.</para>
+ </listitem>
- <listitem>
- <para><command>Cachegrind</command> is a cache profiler. It
- performs detailed simulation of the I1, D1 and L2 caches in your CPU
- and so can accurately pinpoint the sources of cache misses in your
- code. It will show the number of cache misses,
- memory references and instructions accruing to each line of source
- code, with per-function, per-module and whole-program summaries. If
- you ask really nicely it will even show counts for each individual
- machine instruction.</para>
-
- <para>On x86 and and64, Cachegrind auto-detects your machine's cache
- configuration using the <computeroutput>CPUID</computeroutput>
- instruction, and so needs no further configuration info, in most
- cases.</para>
- </listitem>
-
- <listitem>
- <para><command>Callgrind</command> is a profiler similar in
- concept to Cachegrind, but which also tracks caller-callee
- relationships. By doing so it is able to show how instruction,
- memory reference and cache miss costs flow between callers and
- callees. Callgrind collects a large amount of data which is best
- navigated using Josef Weidendorfer's amazing KCachegrind
- visualisation tool (<ulink
- url="http://kcachegrind.sourceforge.net/cgi-bin/show.cgi/KcacheGrindIndex">http://kcachegrind.sourceforge.net</ulink>).
- KCachegrind is a KDE application which presents
- these profiling results in a
- graphical and easy-to-understand form.</para>
- </listitem>
-
- <listitem>
- <para><command>Helgrind</command> detects synchronisation errors
- in programs that use the POSIX pthreads threading primitives. It
- detects the following three classes of errors:</para>
-
- <itemizedlist>
- <listitem>
- <para>Misuses of the POSIX pthreads API.</para>
- </listitem>
- <listitem>
- <para>Potential deadlocks arising from lock ordering
- problems.</para>
- </listitem>
- <listitem>
- <para>Data races -- accessing memory without adequate locking.</para>
- </listitem>
- </itemizedlist>
-
- <para>Problems like these often result in unreproducible,
- timing-dependent crashes, deadlocks and other misbehaviour, and
- can be difficult to find by other means.</para>
- </listitem>
-
- <listitem>
- <para><command>DRD</command> is similar to Helgrind, but uses a
- different analysis technique and so may find different problems.
- </para>
- </listitem>
-
- <listitem>
- <para><command>Massif</command> is a heap profiler.
- It measures how much heap memory programs use. In particular,
- it can give you information about heap blocks, heap
- administration overheads, and stack sizes.</para>
-
- <para>Heap profiling can help you reduce the amount of
- memory your program uses. On modern machines with virtual
- memory, this reduces the chances that your program will run out
- of memory, and may make it faster by reducing the amount of
- paging needed.</para>
- </listitem>
-
- <listitem>
- <para><command>Ptrcheck</command> is an experimental pointer checking
- tool. Its functionality overlaps somewhat with Memcheck's, but it can
- find some problems that Memcheck would miss.</para>
- </listitem>
+ <listitem>
+ <para><command>Cachegrind</command> is a cache and branch-prediction
+ profiler. It can help you make your programs run faster.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>Callgrind</command> is a call-graph generating cache
+ profiler. It has some overlap with Cachegrind, but also gathers some
+ information that Cachegrind does not.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>Helgrind</command> is a thread error detector.
+ It can help you make your multi-threaded programs more correct.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para><command>DRD</command> is also a thread error detector. It is
+ similar to Helgrind but uses different analysis techniques and so may
+ find different problems.</para>
+ </listitem>
+ <listitem>
+ <para><command>Massif</command> is a heap profiler. It can help you
+ make your programs use less memory.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>Ptrcheck</command> is an experimental heap, stack and
+ global array overrun detector. Its functionality overlaps somewhat
+ with Memcheck's, but it can find some problems that Memcheck would
+ miss.</para>
+ </listitem>
+
+ <listitem>
+ <para><command>BBV</command> is an experimental SimPoint basic block
+ vector generator. It is useful to people doing computer architecture
+ research and development.</para>
+ </listitem>
</orderedlist>
-
-<para>A couple of minor tools (<command>Lackey</command> and
-<command>Nulgrind</command>) are also supplied. These aren't
-particularly useful -- they exist to illustrate how to create simple
-tools and to help the valgrind developers in various ways. Nulgrind is
-the null tool -- it adds no instrumentation. Lackey is a simple example
-tool which counts instructions, memory accesses, and the number of
-integer and floating point operations your program does.</para>
+<para>There are also a couple of minor tools that aren't useful to
+most users: <command>Lackey</command> is an example tool that illustrates
+some instrumentation basics; and <command>Nulgrind</command> is the minimal
+Valgrind tool that does no analysis or instrumentation, and is only useful
+for testing purposes.</para>
<para>Valgrind is closely tied to details of the CPU and operating
system, and to a lesser extent, the compiler and basic C libraries.
-Nonetheless, as of version 3.3.0 it supports several platforms:
-x86/Linux (mature), amd64/Linux (maturing), ppc32/Linux and
-ppc64/Linux (less mature but work well). There is also experimental
-support for ppc32/AIX5 and ppc64/AIX5 (AIX 5.2 and 5.3 only).
-Valgrind uses the standard Unix
+Nonetheless, it supports a number of widely-used platforms, listed in full
+at <ulink url="&vg-url;">&vg-url;</ulink>.</para>
+
+<para>Valgrind is built via the standard Unix
<computeroutput>./configure</computeroutput>,
<computeroutput>make</computeroutput>, <computeroutput>make
-install</computeroutput> mechanism, and we have attempted to ensure that
-it works on machines with Linux kernel 2.4.X or 2.6.X and glibc
-2.2.X to 2.7.X.</para>
+install</computeroutput> process; full details are given in the
+README file in the distribution.</para>
<para>Valgrind is licensed under the <xref linkend="license.gpl"/>,
version 2. The <computeroutput>valgrind/*.h</computeroutput> headers
contributions are licensed as "GPLv2, or (at your option) any later
version." This is so as to allow the possibility of easily upgrading
the license to GPLv3 in future. If you want to modify code in the VEX
-subdirectory, please also see VEX/HACKING.README.</para>
+subdirectory, please also see the file VEX/HACKING.README in the
+distribution.</para>
</sect1>
<sect1 id="manual-intro.navigation" xreflabel="How to navigate this manual">
<title>How to navigate this manual</title>
-<para>The Valgrind distribution consists of the Valgrind core, upon
-which are built Valgrind tools. The tools do different kinds of debugging
-and profiling. This manual is structured similarly.</para>
-
-<para>First, we describe the Valgrind core, how to use it, and the flags
+<para>This manual's structure reflects the structure of Valgrind itself.
+First, we describe the Valgrind core, how to use it, and the flags
it supports. Then, each tool has its own chapter in this manual. You
only need to read the documentation for the core and for the tool(s) you
actually use, although you may find it helpful to be at least a little
accepted -- you have to read the flags documentation both for
<xref linkend="manual-core"/> and for the tool you want to use.</para>
-<para>The manual is quite big and complex. If you are looking for a
-quick getting-started guide, have a look at
-<xref linkend="quick-start"/>.</para>
+<para>The manual is quite big and complex. If you want to start using
+Valgrind more quickly, read <xref linkend="quick-start"/>.</para>
</sect1>
<title>Introduction</title>
So you want to write a Valgrind tool? Here are some instructions that may
-help. They were last updated for Valgrind 3.2.2.
+help.
<sect2 id="writing-tools.tools" xreflabel="Tools">
<title>Tools</title>
<title>Introduction</title>
<para>The Valgrind tool suite provides a number of debugging and
-profiling tools. The most popular is
-Memcheck, a memory checking tool which can detect many common
-memory errors such as:</para>
+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.</para>
-<itemizedlist>
- <listitem>
- <para>Touching memory you shouldn't (eg. overrunning heap block
- boundaries, or reading/writing freed memory).</para>
- </listitem>
- <listitem>
- <para>Using values before they have been initialized.</para>
- </listitem>
- <listitem>
- <para>Incorrect freeing of memory, such as double-freeing heap
- blocks.</para>
- </listitem>
- <listitem>
- <para>Memory leaks.</para>
- </listitem>
-</itemizedlist>
-
-<para>Memcheck is only one of the tools in the Valgrind suite.
-Other tools you may find useful are:</para>
-
-<itemizedlist>
- <listitem>
- <para>Cachegrind: a profiling tool which produces detailed data on
- cache (miss) and branch (misprediction) events. Statistics are
- gathered for the entire program, for each function, and for each
- line of code, if you need that level of detail.</para>
- </listitem>
- <listitem>
- <para>Callgrind: a profiling tool that shows cost relationships
- across function calls, optionally with cache simulation similar to
- Cachegrind. Information gathered by Callgrind can be viewed
- either with an included command line tool, or by using the
- KCachegrind GUI. KCachegrind is not part of the Valgrind suite
- -- it is part of the KDE Desktop Environment.</para>
- </listitem>
- <listitem>
- <para>Massif: a space profiling tool. It allows you to explore
- in detail which parts of your program allocate memory.</para>
- </listitem>
- <listitem>
- <para>Helgrind: a debugging tool for threaded programs. Helgrind
- looks for various kinds of synchronisation errors in code that uses
- the POSIX PThreads API.</para>
- </listitem>
- <listitem>
- <para>In addition, there are a number of "experimental" tools in
- the codebase. They can be distinguished by the "exp-" prefix on
- their names. Experimental tools are not subject to the same
- quality control standards that apply to our production-grade tools
- (Memcheck, Cachegrind, Callgrind, Massif, Helgrind and DRD).</para>
- </listitem>
-</itemizedlist>
-
-<para>The rest of this guide discusses only the Memcheck tool. For
-full documentation on the other tools, and for Memcheck, see the
-Valgrind User Manual.</para>
-
-<para>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 3.4.0 and later. Some of the
-information is not quite right for earlier versions.</para>
+<para>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.
+</para>
</sect1>
numbers. Using <computeroutput>-O0</computeroutput> is also a good
idea, if you can tolerate the slowdown. With
<computeroutput>-O1</computeroutput> line numbers in error messages can
-be inaccurate, although generally speaking Memchecking code compiled at
-<computeroutput>-O1</computeroutput> works fairly well and is
-recommended. Use of
+be inaccurate, although generally speaking running Memcheck on code compiled
+at <computeroutput>-O1</computeroutput> works fairly well.
+Use of
<computeroutput>-O2</computeroutput> and above is not recommended as
Memcheck occasionally reports uninitialised-value errors which don't
really exist.</para>
<sect1 id="quick-start.interpret"
xreflabel="Interpreting Memcheck's output">
<title>Interpreting Memcheck's output</title>
-<para>Here's an example C program with a memory error and a memory
-leak.</para>
+<para>Here's an example C program, in a file called a.c, with a memory error
+and a memory leak.</para>
<programlisting>
#include <stdlib.h>
</listitem>
</itemizedlist>
-<para>It can be difficult to track down the root causes of
-uninitialised-value errors reported by Memcheck. Try using
-the <option>--track-origins=yes</option> 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.</para>
+<para>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 <option>--track-origins=yes</option> 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.</para>
<para>If you don't understand an error message, please consult
<xref linkend="mc-manual.errormsgs"/> in the <xref linkend="manual"/>
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 3.5.X, and recent versions of OpenOffice.org
-(2.3.0) are Memcheck-clean, or very close to it.</para>
+large parts of KDE, OpenOffice.org and Firefox are Memcheck-clean, or very
+close to it.</para>
</sect1>
<sect1 id="drd-manual.overview" xreflabel="Overview">
-<title>Background</title>
+<title>Overview</title>
<para>
DRD is a Valgrind tool for detecting errors in multithreaded C and C++
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
<chapter id="bbv-manual" xreflabel="BBV">
- <title>BBV: a Basic Block Vector generation tool</title>
+ <title>BBV: an experimental basic block vector generation tool</title>
<para>To use this tool, you must specify
<computeroutput>--tool=exp-bbv</computeroutput> on the Valgrind
command line.</para>
-<sect1 id="bbv-manual.background" xreflabel="BBV Background">
-<title>Basic Block Profiling and SimPoint</title>
+<sect1 id="bbv-manual.overview" xreflabel="Overview">
+<title>Overview</title>
<para>
A Basic Blocks Vector (BBV) is a list of all basic blocks entered
</para>
<para>
- This tool was written to generate basic block vectors
+ BBV is tool that generates basic block vectors
for use with the SimPoint analysis tool
(http://www.cse.ucsd.edu/~calder/simpoint/).
The SimPoint methodology enables speeding up architectural
In computer architecture research, running a
benchmark on a cycle-accurate simulator can cause slowdowns on the order
of 1000 times, making it take days, weeks, or even longer to run full
- benchmarks. By utilizing SimPoint this can be reduced significantly
- while still retaining reasonable accuracy, usually in the 5-10% range.
+ benchmarks. By utilizing SimPoint this can be reduced significantly,
+ usually by 90-95%, while still retaining reasonable accuracy.
</para>
<para>
A more complete introduction to how SimPoint works can be
found in the paper "Automatically Characterizing Large Scale
- Program Behavior" by T. Sherwood, E Perelman, G. Hamerly, and
+ Program Behavior" by T. Sherwood, E. Perelman, G. Hamerly, and
B. Calder.
</para>
<chapter id="pc-manual"
- xreflabel="Ptrcheck: an (experimental) pointer checking tool">
- <title>Ptrcheck: an (experimental) pointer checking tool</title>
+ xreflabel="Ptrcheck: an experimental heap, stack & global array overrun detector">
+ <title>Ptrcheck: an experimental heap, stack & global array overrun detector</title>
<para>To use this tool, you must specify
<computeroutput>--tool=exp-ptrcheck</computeroutput> on the Valgrind
<sect1 id="pc-manual.overview" xreflabel="Overview">
<title>Overview</title>
-<para>Ptrcheck is a Valgrind tool for finding overruns of heap, stack
+<para>Ptrcheck is a tool for finding overruns of heap, stack
and global arrays. Its functionality overlaps somewhat with
Memcheck's, but it is able to catch invalid accesses in a number of
cases that Memcheck would miss. A detailed comparison against
command line.</para>
-
-
<sect1 id="hg-manual.overview" xreflabel="Overview">
<title>Overview</title>
thread exit, mutexes (locks), condition variables (inter-thread event
notifications), reader-writer locks, semaphores and barriers.</para>
-<para>Helgrind is aware of all these abstractions and tracks their
-effects as accurately as it can. Currently it does not correctly
-handle pthread spinlocks, although it will not object if you use them.
-Adding support for spinlocks would be easy enough if the demand arises.
-On x86 and amd64 platforms, it understands and partially handles
-implicit locking arising from the use of the LOCK instruction prefix.
-</para>
-
<para>Helgrind can detect three classes of errors, which are discussed
in detail in the next three sections:</para>
</listitem>
</orderedlist>
+<para>Problems like these often result in unreproducible,
+timing-dependent crashes, deadlocks and other misbehaviour, and
+can be difficult to find by other means.</para>
+
+<para>Helgrind is aware of all the pthread abstractions and tracks their
+effects as accurately as it can. Currently it does not correctly
+handle pthread spinlocks, although it will not object if you use them.
+Adding support for spinlocks would be easy enough if the demand arises.
+On x86 and amd64 platforms, it understands and partially handles
+implicit locking arising from the use of the LOCK instruction prefix.
+</para>
+
+
<para>Following those is a section containing
<link linkend="hg-manual.effective-use">
hints and tips on how to get the best out of Helgrind.</link>
<chapter id="lk-manual" xreflabel="Lackey">
-<title>Lackey: a simple profiler and memory tracer</title>
+<title>Lackey: an example tool</title>
<para>To use this tool, you must specify
<computeroutput>--tool=lackey</computeroutput> on the Valgrind
<chapter id="ms-manual" xreflabel="Massif: a heap profiler">
<title>Massif: a heap profiler</title>
-<emphasis>Please note that this documentation describes Massif version 3.3.0
-and later. Massif was significantly overhauled for 3.3.0; versions 3.2.3
-and earlier presented the profiling information an a quite different manner,
-and so this documentation only pertains to the later versions.</emphasis>
-
<para>To use this tool, you must specify
<computeroutput>--tool=massif</computeroutput> on the Valgrind
command line.</para>
-<sect1 id="ms-manual.spaceprof" xreflabel="Heap profiling">
-<title>Heap profiling</title>
+<sect1 id="ms-manual.overview" xreflabel="Overview">
+<title>Overview</title>
<para>Massif is a heap profiler. It measures how much heap memory your
program uses. This includes both the useful space, and the extra bytes
-allocated for book-keeping purposes and alignment purposes. It can also
+allocated for book-keeping and alignment purposes. It can also
measure the size of your program's stack(s), although it does not do so by
default.</para>
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
-<chapter id="mc-manual" xreflabel="Memcheck: a heavyweight memory checker">
-<title>Memcheck: a heavyweight memory checker</title>
+<chapter id="mc-manual" xreflabel="Memcheck: a memory error detector">
+<title>Memcheck: a memory error detector</title>
<para>To use this tool, you may specify <option>--tool=memcheck</option>
on the Valgrind command line. You don't have to, though, since Memcheck
is the default tool.</para>
-<sect1 id="mc-manual.bugs"
- xreflabel="Kinds of bugs that Memcheck can find">
-<title>Kinds of bugs that Memcheck can find</title>
+<sect1 id="mc-manual.overview" xreflabel="Overview">
+<title>Overview</title>
-<para>Memcheck is Valgrind's heavyweight memory checking tool. All
-reads and writes of memory are checked, and calls to
-<function>malloc</function>/<computeroutput>new</computeroutput>/<function>free</function>/<computeroutput>delete</computeroutput>
-are intercepted. As a result, Memcheck can detect the following
-problems:</para>
+<para>Memcheck is a memory error detector. It can detect the following
+problems that are common in C and C++ programs.</para>
<itemizedlist>
<listitem>
- <para>Use of uninitialised memory</para>
- </listitem>
- <listitem>
- <para>Reading/writing memory after it has been free'd</para>
- </listitem>
- <listitem>
- <para>Reading/writing off the end of malloc'd blocks</para>
- </listitem>
- <listitem>
- <para>Reading/writing inappropriate areas on the stack</para>
+ <para>Accessing memory you shouldn't, e.g. overrunning and underrunning
+ heap blocks, overrunning the top of the stack, and accessing memory after
+ it has been freed.</para>
</listitem>
+
<listitem>
- <para>Memory leaks - where pointers to malloc'd blocks are
- lost forever</para>
+ <para>Using undefined values, i.e. values that have not been initialised,
+ or that have been derived from other undefined values.</para>
</listitem>
+
<listitem>
- <para>Mismatched use of
+ <para>Incorrect freeing of heap memory, such as double-freeing heap
+ blocks, or mismatched use of
<function>malloc</function>/<computeroutput>new</computeroutput>/<computeroutput>new[]</computeroutput>
versus
<function>free</function>/<computeroutput>delete</computeroutput>/<computeroutput>delete[]</computeroutput></para>
</listitem>
+
<listitem>
<para>Overlapping <computeroutput>src</computeroutput> and
<computeroutput>dst</computeroutput> pointers in
- <function>memcpy()</function> and related
- functions</para>
+ <computeroutput>memcpy()</computeroutput> and related
+ functions.</para>
+ </listitem>
+
+ <listitem>
+ <para>Memory leaks.</para>
</listitem>
</itemizedlist>
+<para>Problems like these can be difficult to find by other means,
+often remaining undetected for long periods, then causing occasional,
+difficult-to-diagnose crashes.</para>
+
</sect1>
<chapter id="nl-manual" xreflabel="Nulgrind">
-<title>Nulgrind: the "null" tool</title>
-<subtitle>A tool that does not very much at all</subtitle>
+<title>Nulgrind: the minimal Valgrind tool</title>
-<para>Nulgrind is the minimal tool for Valgrind. It does no
-initialisation or finalisation, and adds no instrumentation to
-the program's code. It is mainly of use for Valgrind's
-developers for debugging and regression testing.</para>
+<para>To use this tool, you must specify
+<computeroutput>--tool=none</computeroutput> on the Valgrind
+command line.</para>
+
+<sect1 id="ms-manual.overview" xreflabel="Overview">
+<title>Overview</title>
+
+<para>Nulgrind is the simplest possible Valgrind tool. It performs no
+instrumentation or analysis of a program, just runs it normally. It is
+mainly of use for Valgrind's developers for debugging and regression
+testing.</para>
<para>Nonetheless you can run programs with Nulgrind. They will run
roughly 5 times more slowly than normal, for no useful effect. Note
that you need to use the option <option>--tool=none</option> to run
Nulgrind (ie. not <option>--tool=nulgrind</option>).</para>
+</sect1>
+
</chapter>
/*--------------------------------------------------------------------*/
-/*--- Nulgrind: The null tool. nl_main.c ---*/
+/*--- Nulgrind: The minimal Valgrind tool. nl_main.c ---*/
/*--------------------------------------------------------------------*/
/*
- This file is part of Nulgrind, the simplest possible Valgrind tool,
- which does nothing.
+ This file is part of Nulgrind, the minimal Valgrind tool,
+ which does no instrumentation or analysis.
Copyright (C) 2002-2009 Nicholas Nethercote
njn@valgrind.org
{
VG_(details_name) ("Nulgrind");
VG_(details_version) (NULL);
- VG_(details_description) ("a binary JIT-compiler");
+ VG_(details_description) ("the minimal Valgrind tool");
VG_(details_copyright_author)(
"Copyright (C) 2002-2009, and GNU GPL'd, by Nicholas Nethercote.");
VG_(details_bug_reports_to) (VG_BUGS_TO);
Extra options read from ~/.valgrindrc, $VALGRIND_OPTS, ./.valgrindrc
Nulgrind is Copyright (C) 2002-2009, and GNU GPL'd, by Nicholas Nethercote.
- Valgrind is Copyright (C) 2000-2009, and GNU GPL'd, by Julian Seward et al
- LibVEX is Copyright (C) 2004-2009, and GNU GPL'd, by OpenWorks LLP
+ Valgrind is Copyright (C) 2000-2009, and GNU GPL'd, by Julian Seward et al.
+ LibVEX is Copyright (C) 2004-2009, and GNU GPL'd, by OpenWorks LLP.
Bug reports, feedback, admiration, abuse, etc, to: www.valgrind.org.
Extra options read from ~/.valgrindrc, $VALGRIND_OPTS, ./.valgrindrc
Nulgrind is Copyright (C) 2002-2009, and GNU GPL'd, by Nicholas Nethercote.
- Valgrind is Copyright (C) 2000-2009, and GNU GPL'd, by Julian Seward et al
- LibVEX is Copyright (C) 2004-2009, and GNU GPL'd, by OpenWorks LLP
+ Valgrind is Copyright (C) 2000-2009, and GNU GPL'd, by Julian Seward et al.
+ LibVEX is Copyright (C) 2004-2009, and GNU GPL'd, by OpenWorks LLP.
Bug reports, feedback, admiration, abuse, etc, to: www.valgrind.org.
$dir/../../tests/filter_stderr_basic |
# Remove "Nulgrind, ..." line and the following copyright line.
-sed "/^Nulgrind, a binary JIT-compiler./ , /./ d" |
+sed "/^Nulgrind, the minimal Valgrind tool./ , /./ d" |
# Anonymise addresses
$dir/../../tests/filter_addresses
projects / thirdparty / valgrind.git / commitdiff
