addrcheck/docs/ac-manual.xml

<?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">


<chapter id="ac-manual" xreflabel="Addrcheck: a lightweight memory checker">
  <title>Addrcheck: a lightweight memory checker</title>

<para>To use this tool, you must specify
<option>--tool=addrcheck</option> on the Valgrind command line.</para>

<para>Note: Addrcheck does not work in Valgrind 3.1.0.  We may reinstate
it in later releases.</para>

<sect1>
<title>Kinds of bugs that Addrcheck can find</title>

<para>Addrcheck is a simplified version of the Memcheck tool described
in Section 3.  It is identical in every way to Memcheck, except for one
important detail: it does not do the undefined-value checks that
Memcheck does.  This means Addrcheck is faster than Memcheck, and uses
less memory.  Addrcheck can detect the following errors:</para>

<itemizedlist>
  <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>Rather than duplicate much of the Memcheck docs here, users of
Addrcheck are advised to read <xref linkend="mc-manual.bugs"/>.  Some
important points:</para>

<itemizedlist>

  <listitem>
    <para>Addrcheck is exactly like Memcheck, except that all the
    value-definedness tracking machinery has been removed.  Therefore,
    the Memcheck documentation which discusses definedess ("V-bits") is
    irrelevant.  The stuff on addressibility ("A-bits") is still
    relevant.</para>
  </listitem>

  <listitem>
    <para>Addrcheck accepts the same command-line flags as Memcheck,
    with the exception of ... (to be filled in).</para>
  </listitem>

  <listitem>
    <para>Like Memcheck, Addrcheck will do memory leak checking
    (internally, the same code does leak checking for both tools).  The
    only difference is how the two tools decide which memory locations
    to consider when searching for pointers to blocks.  Memcheck will
    only consider 4-byte aligned locations which are validly addressible
    and which hold defined values.  Addrcheck does not track definedness
    and so cannot apply the last, "defined value", criteria.</para>

    <para>The result is that Addrcheck's leak checker may "discover"
    pointers to blocks that Memcheck would not.  So it is possible that
    Memcheck could (correctly) conclude that a block is leaked, yet
    Addrcheck would not conclude that.</para>

    <para>Whether or not this has any effect in practice is unknown.  I
    suspect not, but that is mere speculation at this stage.</para>
  </listitem>

</itemizedlist>

<para>Addrcheck is, therefore, a fine-grained address checker.  All it
really does is check each memory reference to say whether or not that
location may validly be addressed.  Addrcheck has a memory overhead of
one bit per byte of used address space.  In contrast, Memcheck has an
overhead of nine bits per byte.</para>

<para>Addrcheck is quite pleasant to use.  It's faster than Memcheck,
and the lack of valid-value checks has another side effect: the errors
it does report are relatively easy to track down, compared to the
tedious and often confusing search sometimes needed to find the cause of
uninitialised-value errors reported by Memcheck.</para>

</sect1>

</chapter>