Various fix-ups for Memcheck's manual chapter.
git-svn-id: svn://svn.valgrind.org/valgrind/trunk@10716 a5019735-40e9-0310-863c-91ae7b9d1cf9
diff --git a/memcheck/docs/mc-manual.xml b/memcheck/docs/mc-manual.xml
index 83bdb15..8a3da0d 100644
--- a/memcheck/docs/mc-manual.xml
+++ b/memcheck/docs/mc-manual.xml
@@ -40,7 +40,7 @@
<listitem>
<para>Overlapping <computeroutput>src</computeroutput> and
<computeroutput>dst</computeroutput> pointers in
- <computeroutput>memcpy()</computeroutput> and related
+ <computeroutput>memcpy</computeroutput> and related
functions.</para>
</listitem>
@@ -94,7 +94,9 @@
the block was freed. Likewise, if it should turn out to be just off
the end of a heap block, a common result of off-by-one-errors in
array subscripting, you'll be informed of this fact, and also where the
-block was allocated.</para>
+block was allocated. If you use the <option><xref
+linkend="opt.read-var-info"/></option> option Memcheck will run more slowly
+but may give a more detailed description of any illegal address.</para>
<para>In this example, Memcheck can't identify the address. Actually
the address is on the stack, but, for some reason, this is not a valid
@@ -129,8 +131,8 @@
<para>An uninitialised-value use error is reported when your program
uses a value which hasn't been initialised -- in other words, is
undefined. Here, the undefined value is used somewhere inside the
-printf() machinery of the C library. This error was reported when
-running the following small program:</para>
+<function>printf</function> machinery of the C library. This error was
+reported when running the following small program:</para>
<programlisting><![CDATA[
int main()
{
@@ -142,13 +144,13 @@
junk (uninitialised) data as much as it likes. Memcheck observes this
and keeps track of the data, but does not complain. A complaint is
issued only when your program attempts to make use of uninitialised
-data. In this example, x is uninitialised. Memcheck observes the value
-being passed to <literal>_IO_printf</literal> and thence to
-<literal>_IO_vfprintf</literal>, but makes no comment. However,
-<literal>_IO_vfprintf</literal> has to examine the value of
-x so it can turn it into the
-corresponding ASCII string, and it is at this point that Memcheck
-complains.</para>
+data in a way that might affect your program's externally-visible behaviour.
+In this example, <varname>x</varname> is uninitialised. Memcheck observes
+the value being passed to <function>_IO_printf</function> and thence to
+<function>_IO_vfprintf</function>, but makes no comment. However,
+<function>_IO_vfprintf</function> has to examine the value of
+<varname>x</varname> so it can turn it into the corresponding ASCII string,
+and it is at this point that Memcheck complains.</para>
<para>Sources of uninitialised data tend to be:</para>
<itemizedlist>
@@ -173,6 +175,74 @@
+<sect2 id="mc-manual.bad-syscall-args"
+ xreflabel="Use of uninitialised or unaddressable values in system
+ calls">
+<title>Use of uninitialised or unaddressable values in system
+ calls</title>
+
+<para>Memcheck checks all parameters to system calls:
+<itemizedlist>
+ <listitem>
+ <para>It checks all the direct parameters themselves, whether they are
+ initialised.</para>
+ </listitem>
+ <listitem>
+ <para>Also, if a system call needs to read from a buffer provided by
+ your program, Memcheck checks that the entire buffer is addressable
+ and its contents are initialised.</para>
+ </listitem>
+ <listitem>
+ <para>Also, if the system call needs to write to a user-supplied
+ buffer, Memcheck checks that the buffer is addressable.</para>
+ </listitem>
+</itemizedlist>
+</para>
+
+<para>After the system call, Memcheck updates its tracked information to
+precisely reflect any changes in memory state caused by the system
+call.</para>
+
+<para>Here's an example of two system calls with invalid parameters:</para>
+<programlisting><![CDATA[
+ #include <stdlib.h>
+ #include <unistd.h>
+ int main( void )
+ {
+ char* arr = malloc(10);
+ int* arr2 = malloc(sizeof(int));
+ write( 1 /* stdout */, arr, 10 );
+ exit(arr2[0]);
+ }
+]]></programlisting>
+
+<para>You get these complaints ...</para>
+<programlisting><![CDATA[
+ Syscall param write(buf) points to uninitialised byte(s)
+ at 0x25A48723: __write_nocancel (in /lib/tls/libc-2.3.3.so)
+ by 0x259AFAD3: __libc_start_main (in /lib/tls/libc-2.3.3.so)
+ by 0x8048348: (within /auto/homes/njn25/grind/head4/a.out)
+ Address 0x25AB8028 is 0 bytes inside a block of size 10 alloc'd
+ at 0x259852B0: malloc (vg_replace_malloc.c:130)
+ by 0x80483F1: main (a.c:5)
+
+ Syscall param exit(error_code) contains uninitialised byte(s)
+ at 0x25A21B44: __GI__exit (in /lib/tls/libc-2.3.3.so)
+ by 0x8048426: main (a.c:8)
+]]></programlisting>
+
+<para>... because the program has (a) written uninitialised junk
+from the heap block to the standard output, and (b) passed an
+uninitialised value to <function>exit</function>. Note that the first
+error refers to the memory pointed to by
+<computeroutput>buf</computeroutput> (not
+<computeroutput>buf</computeroutput> itself), but the second error
+refers directly to <computeroutput>exit</computeroutput>'s argument
+<computeroutput>arr2[0]</computeroutput>.</para>
+
+</sect2>
+
+
<sect2 id="mc-manual.badfrees" xreflabel="Illegal frees">
<title>Illegal frees</title>
@@ -194,15 +264,17 @@
twice. As with the illegal read/write errors, Memcheck attempts to
make sense of the address freed. If, as here, the address is one
which has previously been freed, you wil be told that -- making
-duplicate frees of the same block easy to spot.</para>
+duplicate frees of the same block easy to spot. You will also get this
+message if you try to free a pointer that doesn't point to the start of a
+heap block.</para>
</sect2>
<sect2 id="mc-manual.rudefn"
- xreflabel="When a block is freed with an inappropriate deallocation
+ xreflabel="When a heap block is freed with an inappropriate deallocation
function">
-<title>When a block is freed with an inappropriate deallocation
+<title>When a heap block is freed with an inappropriate deallocation
function</title>
<para>In the following example, a block allocated with
@@ -234,13 +306,13 @@
deallocate with <function>free</function>.</para>
</listitem>
<listitem>
- <para>If allocated with <function>new[]</function>, you must
- deallocate with <function>delete[]</function>.</para>
- </listitem>
- <listitem>
<para>If allocated with <function>new</function>, you must deallocate
with <function>delete</function>.</para>
</listitem>
+ <listitem>
+ <para>If allocated with <function>new[]</function>, you must
+ deallocate with <function>delete[]</function>.</para>
+ </listitem>
</itemizedlist>
<para>The worst thing is that on Linux apparently it doesn't matter if
@@ -254,94 +326,30 @@
objects allocated by <function>new[]</function> because the compiler
stores the size of the array and the pointer-to-member to the
destructor of the array's content just before the pointer actually
-returned. This implies a variable-sized overhead in what's returned
-by <function>new</function> or <function>new[]</function>.</para>
+returned. <function>delete</function> doesn't account for this and will get
+confused, possibly corrupting the heap.</para>
</sect2>
-<sect2 id="mc-manual.badperm"
- xreflabel="Passing system call parameters with
- inadequate read/write permissions">
-<title>Passing system call parameters with inadequate read/write
-permissions</title>
-
-<para>Memcheck checks all parameters to system calls:
-<itemizedlist>
- <listitem>
- <para>It checks all the direct parameters themselves.</para>
- </listitem>
- <listitem>
- <para>Also, if a system call needs to read from a buffer provided by
- your program, Memcheck checks that the entire buffer is addressable
- and has valid data, ie, it is readable.</para>
- </listitem>
- <listitem>
- <para>Also, if the system call needs to write to a user-supplied
- buffer, Memcheck checks that the buffer is addressable.</para>
- </listitem>
-</itemizedlist>
-</para>
-
-<para>After the system call, Memcheck updates its tracked information to
-precisely reflect any changes in memory permissions caused by the system
-call.</para>
-
-<para>Here's an example of two system calls with invalid parameters:</para>
-<programlisting><![CDATA[
- #include <stdlib.h>
- #include <unistd.h>
- int main( void )
- {
- char* arr = malloc(10);
- int* arr2 = malloc(sizeof(int));
- write( 1 /* stdout */, arr, 10 );
- exit(arr2[0]);
- }
-]]></programlisting>
-
-<para>You get these complaints ...</para>
-<programlisting><![CDATA[
- Syscall param write(buf) points to uninitialised byte(s)
- at 0x25A48723: __write_nocancel (in /lib/tls/libc-2.3.3.so)
- by 0x259AFAD3: __libc_start_main (in /lib/tls/libc-2.3.3.so)
- by 0x8048348: (within /auto/homes/njn25/grind/head4/a.out)
- Address 0x25AB8028 is 0 bytes inside a block of size 10 alloc'd
- at 0x259852B0: malloc (vg_replace_malloc.c:130)
- by 0x80483F1: main (a.c:5)
-
- Syscall param exit(error_code) contains uninitialised byte(s)
- at 0x25A21B44: __GI__exit (in /lib/tls/libc-2.3.3.so)
- by 0x8048426: main (a.c:8)
-]]></programlisting>
-
-<para>... because the program has (a) tried to write uninitialised junk
-from the heap block to the standard output, and (b) passed an
-uninitialised value to <function>exit</function>. Note that the first
-error refers to the memory pointed to by
-<computeroutput>buf</computeroutput> (not
-<computeroutput>buf</computeroutput> itself), but the second error
-refers directly to <computeroutput>exit</computeroutput>'s argument
-<computeroutput>arr2[0]</computeroutput>.</para>
-
-</sect2>
-
-
<sect2 id="mc-manual.overlap"
xreflabel="Overlapping source and destination blocks">
<title>Overlapping source and destination blocks</title>
<para>The following C library functions copy some data from one
memory block to another (or something similar):
-<function>memcpy()</function>,
-<function>strcpy()</function>,
-<function>strncpy()</function>,
-<function>strcat()</function>,
-<function>strncat()</function>.
+<function>memcpy</function>,
+<function>strcpy</function>,
+<function>strncpy</function>,
+<function>strcat</function>,
+<function>strncat</function>.
The blocks pointed to by their <computeroutput>src</computeroutput> and
<computeroutput>dst</computeroutput> pointers aren't allowed to overlap.
-Memcheck checks for this.</para>
+The POSIX standards have wording along the lines "If copying takes place
+between objects that overlap, the behavior is undefined." Therefore,
+Memcheck checks for this.
+</para>
<para>For example:</para>
<programlisting><![CDATA[
@@ -356,18 +364,13 @@
<para>You might think that Memcheck is being overly pedantic reporting
this in the case where <computeroutput>dst</computeroutput> is less than
<computeroutput>src</computeroutput>. For example, the obvious way to
-implement <function>memcpy()</function> is by copying from the first
+implement <function>memcpy</function> is by copying from the first
byte to the last. However, the optimisation guides of some
architectures recommend copying from the last byte down to the first.
-Also, some implementations of <function>memcpy()</function> zero
+Also, some implementations of <function>memcpy</function> zero
<computeroutput>dst</computeroutput> before copying, because zeroing the
destination's cache line(s) can improve performance.</para>
-<para>In addition, for many of these functions, the POSIX standards
-have wording along the lines "If copying takes place between objects
-that overlap, the behavior is undefined." Hence overlapping copies
-violate the standard.</para>
-
<para>The moral of the story is: if you want to write truly portable
code, don't make any assumptions about the language
implementation.</para>
@@ -378,9 +381,9 @@
<sect2 id="mc-manual.leaks" xreflabel="Memory leak detection">
<title>Memory leak detection</title>
-<para>Memcheck keeps track of all memory blocks issued in response to
+<para>Memcheck keeps track of all heap blocks issued in response to
calls to
-<function>malloc</function>/<function>calloc</function>/<function>realloc</function>/<computeroutput>new</computeroutput>.
+<function>malloc</function>/<function>new</function> et al.
So when the program exits, it knows which blocks have not been freed.
</para>
@@ -393,7 +396,7 @@
<para>There are two ways a block can be reached. The first is with a
"start-pointer", i.e. a pointer to the start of the block. The second is with
an "interior-pointer", i.e. a pointer to the middle of the block. There are
-three possibilities we know of:</para>
+three ways we know of that an interior-pointer can occur:</para>
<itemizedlist>
<listitem>
@@ -879,7 +882,7 @@
<para><varname>Overlap</varname>, meaning a
<computeroutput>src</computeroutput> /
<computeroutput>dst</computeroutput> overlap in
- <function>memcpy()</function> or a similar function.</para>
+ <function>memcpy</function> or a similar function.</para>
</listitem>
<listitem>
@@ -894,15 +897,16 @@
system call parameter. No other error kinds have this extra
line.</para>
-<para>The first line of the calling context: for Value and Addr errors,
-it is either the name of the function in which the error occurred, or,
-failing that, the full path of the .so file or executable containing the
-error location. For Free errors, is the name of the function doing the
-freeing (eg, <function>free</function>,
-<function>__builtin_vec_delete</function>, etc). For Overlap errors, is
-the name of the function with the overlapping arguments (eg.
-<function>memcpy()</function>, <function>strcpy()</function>,
-etc).</para>
+<para>The first line of the calling context: for <varname>ValueN</varname>
+and <varname>AddrN</varname> errors, it is either the name of the function
+in which the error occurred, or, failing that, the full path of the
+<filename>.so</filename> file
+or executable containing the error location. For <varname>Free</varname> errors, is the name
+of the function doing the freeing (eg, <function>free</function>,
+<function>__builtin_vec_delete</function>, etc). For
+<varname>Overlap</varname> errors, is the name of the function with the
+overlapping arguments (eg. <function>memcpy</function>,
+<function>strcpy</function>, etc).</para>
<para>Lastly, there's the rest of the calling context.</para>
@@ -937,16 +941,17 @@
memory at a different address, the relevant V bits will be stored back
in the V-bit bitmap.</para>
-<para>In short, each bit in the system has an associated V bit, which
-follows it around everywhere, even inside the CPU. Yes, all the CPU's
-registers (integer, floating point, vector and condition registers) have
-their own V bit vectors.</para>
+<para>In short, each bit in the system has (conceptually) an associated V
+bit, which follows it around everywhere, even inside the CPU. Yes, all the
+CPU's registers (integer, floating point, vector and condition registers)
+have their own V bit vectors. For this to work, Memcheck uses a great deal
+of compression to represent the V bits compactly.</para>
<para>Copying values around does not cause Memcheck to check for, or
report on, errors. However, when a value is used in a way which might
-conceivably affect the outcome of your program's computation, the
-associated V bits are immediately checked. If any of these indicate
-that the value is undefined, an error is reported.</para>
+conceivably affect your program's externally-visible behaviour,
+the associated V bits are immediately checked. If any of these indicate
+that the value is undefined (even partially), an error is reported.</para>
<para>Here's an (admittedly nonsensical) example:</para>
<programlisting><![CDATA[
@@ -1112,7 +1117,8 @@
<para>Each byte in memory has 8 associated V (valid-value) bits,
saying whether or not the byte has a defined value, and a single A
(valid-address) bit, saying whether or not the program currently has
- the right to read/write that address.</para>
+ the right to read/write that address. (But, as mentioned above, heavy
+ use of compression means the overhead is typically less than 25%.)</para>
</listitem>
<listitem>
@@ -1201,12 +1207,8 @@
<listitem>
<para><function>realloc</function>: if the new size is larger than
the old, the new section is addressable but invalid, as with
- <function>malloc</function>.</para>
- </listitem>
-
- <listitem>
- <para>If the new size is smaller, the dropped-off section is
- marked as unaddressable. You may only pass to
+ <function>malloc</function>. If the new size is smaller, the
+ dropped-off section is marked as unaddressable. You may only pass to
<function>realloc</function> a pointer previously issued to you by
<function>malloc</function>/<function>calloc</function>/<function>realloc</function>.</para>
</listitem>
@@ -1293,7 +1295,7 @@
<listitem>
<para><varname>VALGRIND_DO_LEAK_CHECK</varname>: does a full memory leak
- check (like <option>--leak-check=full</option> right now.
+ check (like <option>--leak-check=full</option>) right now.
This is useful for incrementally checking for leaks between arbitrary
places in the program's execution. It has no return value.</para>
</listitem>
@@ -1309,7 +1311,7 @@
<para><varname>VALGRIND_COUNT_LEAKS</varname>: fills in the four
arguments with the number of bytes of memory found by the previous
leak check to be leaked (i.e. the sum of direct leaks and indirect leaks),
- dubious, reachable and suppressed. Again, useful in test harness code,
+ dubious, reachable and suppressed. This is useful in test harness code,
after calling <varname>VALGRIND_DO_LEAK_CHECK</varname> or
<varname>VALGRIND_DO_QUICK_LEAK_CHECK</varname>.</para>
</listitem>
@@ -1369,8 +1371,8 @@
<listitem>
<para>Typically the pool's chunks are drawn from a contiguous
"superblock" acquired through the system
- <function>malloc()</function> or
- <function>mmap()</function>.</para>
+ <function>malloc</function> or
+ <function>mmap</function>.</para>
</listitem>
</itemizedlist>
@@ -1508,7 +1510,7 @@
request informs Memcheck that the pool previously anchored at
address "poolA" has moved to anchor address "poolB". This is a
rare request, typically only needed if you
- <function>realloc()</function> the header of a mempool.</para>
+ <function>realloc</function> the header of a mempool.</para>
<para>No memory-status bits are altered by this request.</para>
</listitem>
@@ -1519,7 +1521,7 @@
previously allocated at address "addrA" within "pool" has been
moved and/or resized, and should be changed to cover the region
[addrB,addrB+size). This is a rare request, typically only needed
- if you <function>realloc()</function> a superblock or wish to
+ if you <function>realloc</function> a superblock or wish to
extend a chunk without changing its memory-status bits.
</para>
<para>No memory-status bits are altered by this request.
@@ -1549,7 +1551,7 @@
<sect1 id="mc-manual.mpiwrap" xreflabel="MPI Wrappers">
<title>Debugging MPI Parallel Programs with Valgrind</title>
-<para> Valgrind supports debugging of distributed-memory applications
+<para>Memcheck supports debugging of distributed-memory applications
which use the MPI message passing standard. This support consists of a
library of wrapper functions for the
<computeroutput>PMPI_*</computeroutput> interface. When incorporated
@@ -1557,7 +1559,7 @@
<computeroutput>LD_PRELOAD</computeroutput>, the wrappers intercept
calls to <computeroutput>PMPI_Send</computeroutput>,
<computeroutput>PMPI_Recv</computeroutput>, etc. They then
-use client requests to inform Valgrind of memory state changes caused
+use client requests to inform Memcheck of memory state changes caused
by the function being wrapped. This reduces the number of false
positives that Memcheck otherwise typically reports for MPI
applications.</para>
@@ -1602,7 +1604,7 @@
<para>If the configure test succeeds, continue in the usual way with
<computeroutput>make</computeroutput> and <computeroutput>make
install</computeroutput>. The final install tree should then contain
-<computeroutput>libmpiwrap.so</computeroutput>.
+<computeroutput>libmpiwrap-<platform>.so</computeroutput>.
</para>
<para>Compile up a test MPI program (eg, MPI hello-world) and try
@@ -1715,12 +1717,8 @@
</sect2>
-<sect2 id="mc-manual.mpiwrap.limitations"
- xreflabel="Abilities and Limitations of MPI Wrappers">
-<title>Abilities and limitations</title>
-
-<sect3 id="mc-manual.mpiwrap.limitations.functions"
- xreflabel="Functions">
+<sect2 id="mc-manual.mpiwrap.limitations.functions"
+ xreflabel="Functions: Abilities and Limitations">
<title>Functions</title>
<para>All MPI2 functions except
@@ -1728,9 +1726,9 @@
<computeroutput>MPI_Wtime</computeroutput> and
<computeroutput>MPI_Pcontrol</computeroutput> have wrappers. The
first two are not wrapped because they return a
-<computeroutput>double</computeroutput>, and Valgrind's
-function-wrap mechanism cannot handle that (it could easily enough be
-extended to). <computeroutput>MPI_Pcontrol</computeroutput> cannot be
+<computeroutput>double</computeroutput>, which Valgrind's
+function-wrap mechanism cannot handle (but it could easily be
+extended to do so). <computeroutput>MPI_Pcontrol</computeroutput> cannot be
wrapped as it has variable arity:
<computeroutput>int MPI_Pcontrol(const int level, ...)</computeroutput></para>
@@ -1783,10 +1781,10 @@
<computeroutput>PMPI_Type_get_envelope</computeroutput>,
<computeroutput>PMPI_Type_get_contents</computeroutput>, and
<computeroutput>PMPI_Type_free</computeroutput>. </para>
-</sect3>
+</sect2>
-<sect3 id="mc-manual.mpiwrap.limitations.types"
- xreflabel="Types">
+<sect2 id="mc-manual.mpiwrap.limitations.types"
+ xreflabel="Types: Abilities and Limitations">
<title>Types</title>
<para> MPI-1.1 structured types are supported, and walked exactly.
@@ -1838,8 +1836,6 @@
wrappers handle each element individually and so there can be a very
large performance cost.</para>
-</sect3>
-
</sect2>