--skin=memcheck
on the
Valgrind command line. But you don't have to, since this is the
default skin.
--leak-check=no
[default]--leak-check=yes
When enabled, search for memory leaks when the client program finishes. A memory leak means a malloc'd block, which has not yet been free'd, but to which no pointer can be found. Such a block can never be free'd by the program, since no pointer to it exists. Leak checking is disabled by default because it tends to generate dozens of error messages.
--show-reachable=no
[default]--show-reachable=yes
When disabled, the memory leak detector only shows blocks for
which it cannot find a pointer to at all, or it can only find a
pointer to the middle of. These blocks are prime candidates for
memory leaks. When enabled, the leak detector also reports on
blocks which it could find a pointer to. Your program could, at
least in principle, have freed such blocks before exit.
Contrast this to blocks for which no pointer, or only an
interior pointer could be found: they are more likely to
indicate memory leaks, because you do not actually have a
pointer to the start of the block which you can hand to
free
, even if you wanted to.
--leak-resolution=low
[default]--leak-resolution=med
--leak-resolution=high
When doing leak checking, determines how willing Memcheck is
to consider different backtraces to be the same. When set to
low
, the default, only the first two entries need
match. When med
, four entries have to match. When
high
, all entries need to match.
For hardcore leak debugging, you probably want to use
--leak-resolution=high
together with
--num-callers=40
or some such large number. Note
however that this can give an overwhelming amount of
information, which is why the defaults are 4 callers and
low-resolution matching.
Note that the --leak-resolution=
setting does not
affect Memcheck's ability to find leaks. It only changes how
the results are presented.
--freelist-vol=<number>
[default: 1000000]
When the client program releases memory using free (in C) or delete (C++), that memory is not immediately made available for re-allocation. Instead it is marked inaccessible and placed in a queue of freed blocks. The purpose is to delay the point at which freed-up memory comes back into circulation. This increases the chance that Memcheck will be able to detect invalid accesses to blocks for some significant period of time after they have been freed.
This flag specifies the maximum total size, in bytes, of the blocks in the queue. The default value is one million bytes. Increasing this increases the total amount of memory used by Memcheck but may detect invalid uses of freed blocks which would otherwise go undetected.
--workaround-gcc296-bugs=no
[default]--workaround-gcc296-bugs=yes
When enabled,
assume that reads and writes some small distance below the stack
pointer %esp
are due to bugs in gcc 2.96, and does
not report them. The "small distance" is 256 bytes by default.
Note that gcc 2.96 is the default compiler on some popular Linux
distributions (RedHat 7.X, Mandrake) and so you may well need to
use this flag. Do not use it if you do not have to, as it can
cause real errors to be overlooked. Another option is to use a
gcc/g++ which does not generate accesses below the stack
pointer. 2.95.3 seems to be a good choice in this respect.
Unfortunately (27 Feb 02) it looks like g++ 3.0.4 has a similar bug, so you may need to issue this flag if you use 3.0.4. A while later (early Apr 02) this is confirmed as a scheduling bug in g++-3.0.4.
--partial-loads-ok=yes
[the default]--partial-loads-ok=no
Controls how Memcheck handles word (4-byte) loads from
addresses for which some bytes are addressible and others
are not. When yes
(the default), such loads
do not elicit an address error. Instead, the loaded V bytes
corresponding to the illegal addresses indicate undefined, and
those corresponding to legal addresses are loaded from shadow
memory, as usual.
When no
, loads from partially
invalid addresses are treated the same as loads from completely
invalid addresses: an illegal-address error is issued,
and the resulting V bytes indicate valid data.
--cleanup=no
--cleanup=yes
[default]
This is a flag to help debug valgrind itself. It is of no use to end-users. When enabled, various improvments are applied to the post-instrumented intermediate code, aimed at removing redundant value checks.
Invalid read of size 4 at 0x40F6BBCC: (within /usr/lib/libpng.so.2.1.0.9) by 0x40F6B804: (within /usr/lib/libpng.so.2.1.0.9) by 0x40B07FF4: read_png_image__FP8QImageIO (kernel/qpngio.cpp:326) by 0x40AC751B: QImageIO::read() (kernel/qimage.cpp:3621) Address 0xBFFFF0E0 is not stack'd, malloc'd or free'd
This happens when your program reads or writes memory at a place which Memcheck reckons it shouldn't. In this example, the program did a 4-byte read at address 0xBFFFF0E0, somewhere within the system-supplied library libpng.so.2.1.0.9, which was called from somewhere else in the same library, called from line 326 of qpngio.cpp, and so on.
Memcheck tries to establish what the illegal address might relate to, since that's often useful. So, if it points into a block of memory which has already been freed, you'll be informed of this, and also where the block was free'd at. Likewise, if it should turn out to be just off the end of a malloc'd 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 malloc'd.
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 stack address -- it is below the stack pointer, %esp, and that isn't allowed. In this particular case it's probably caused by gcc generating invalid code, a known bug in various flavours of gcc.
Note that Memcheck only tells you that your program is about to access memory at an illegal address. It can't stop the access from happening. So, if your program makes an access which normally would result in a segmentation fault, you program will still suffer the same fate -- but you will get a message from Memcheck immediately prior to this. In this particular example, reading junk on the stack is non-fatal, and the program stays alive.
Conditional jump or move depends on uninitialised value(s) at 0x402DFA94: _IO_vfprintf (_itoa.h:49) by 0x402E8476: _IO_printf (printf.c:36) by 0x8048472: main (tests/manuel1.c:8) by 0x402A6E5E: __libc_start_main (libc-start.c:129)
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:
int main() { int x; printf ("x = %d\n", x); }
It is important to understand that your program can copy around junk (uninitialised) data to its heart's content. 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 _IO_printf and thence to _IO_vfprintf, but makes no comment. However, _IO_vfprintf 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.
Sources of uninitialised data tend to be:
Invalid free() at 0x4004FFDF: free (vg_clientmalloc.c:577) by 0x80484C7: main (tests/doublefree.c:10) by 0x402A6E5E: __libc_start_main (libc-start.c:129) by 0x80483B1: (within tests/doublefree) Address 0x3807F7B4 is 0 bytes inside a block of size 177 free'd at 0x4004FFDF: free (vg_clientmalloc.c:577) by 0x80484C7: main (tests/doublefree.c:10) by 0x402A6E5E: __libc_start_main (libc-start.c:129) by 0x80483B1: (within tests/doublefree)
Memcheck keeps track of the blocks allocated by your program with malloc/new, so it can know exactly whether or not the argument to free/delete is legitimate or not. Here, this test program has freed the same block twice. As with the illegal read/write errors, Memcheck attempts to make sense of the address free'd. 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.
new[]
has wrongly been deallocated with free
:
Mismatched free() / delete / delete [] at 0x40043249: free (vg_clientfuncs.c:171) by 0x4102BB4E: QGArray::~QGArray(void) (tools/qgarray.cpp:149) by 0x4C261C41: PptDoc::~PptDoc(void) (include/qmemarray.h:60) by 0x4C261F0E: PptXml::~PptXml(void) (pptxml.cc:44) Address 0x4BB292A8 is 0 bytes inside a block of size 64 alloc'd at 0x4004318C: __builtin_vec_new (vg_clientfuncs.c:152) by 0x4C21BC15: KLaola::readSBStream(int) const (klaola.cc:314) by 0x4C21C155: KLaola::stream(KLaola::OLENode const *) (klaola.cc:416) by 0x4C21788F: OLEFilter::convert(QCString const &) (olefilter.cc:272)The following was told to me be the KDE 3 developers. I didn't know any of it myself. They also implemented the check itself.
In C++ it's important to deallocate memory in a way compatible with how it was allocated. The deal is:
malloc
, calloc
,
realloc
, valloc
or
memalign
, you must deallocate with free
.
new[]
, you must deallocate with
delete[]
.
new
, you must deallocate with
delete
.
Pascal Massimino adds the following clarification:
delete[]
must be called associated with a
new[]
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 new
or
new[]
. It rather surprising how compilers [Ed:
runtime-support libraries?] are robust to mismatch in
new
/delete
new[]
/delete[]
.
Here's an example of a system call with an invalid parameter:
#include <stdlib.h> #include <unistd.h> int main( void ) { char* arr = malloc(10); (void) write( 1 /* stdout */, arr, 10 ); return 0; }
You get this complaint ...
Syscall param write(buf) contains uninitialised or unaddressable byte(s) at 0x4035E072: __libc_write by 0x402A6E5E: __libc_start_main (libc-start.c:129) by 0x80483B1: (within tests/badwrite) by <bogus frame pointer> ??? Address 0x3807E6D0 is 0 bytes inside a block of size 10 alloc'd at 0x4004FEE6: malloc (ut_clientmalloc.c:539) by 0x80484A0: main (tests/badwrite.c:6) by 0x402A6E5E: __libc_start_main (libc-start.c:129) by 0x80483B1: (within tests/badwrite)
... because the program has tried to write uninitialised junk from the malloc'd block to the standard output.
A suppression file describes a bunch of errors which, for one reason
or another, you don't want Valgrind to tell you about. Usually the
reason is that the system libraries are buggy but unfixable, at least
within the scope of the current debugging session. Multiple
suppressions files are allowed. By default, Valgrind uses
$PREFIX/lib/valgrind/default.supp
.
You can ask to add suppressions from another file, by specifying
--suppressions=/path/to/file.supp
.
A good way to get started writing your own suppressions is to
look at an existing suppressions file whilst reading the following
documentation. The file glibc-2.2.supp
, in the source
distribution, provides some good examples.
Each suppression has the following components:
Skins will complain, at startup, if a skin does not understand any suppression directed to it. Skins ignore suppressions which are not directed to them. As a result, it is quite practical to put suppressions for all skins into the same suppression file.
A suppression indicates the skins it is intended for by listing their names, separated by commas, then a colon. No spaces are allowed, since our parser is very inflexible. An example is:
Addrcheck,Memcheck:meaning that the suppression is intended for both the Memcheck and the Addrcheck skins.
Value1
,
Value2
,
Value4
or
Value8
,
meaning an uninitialised-value error when
using a value of 1, 2, 4 or 8 bytes.
Or
Cond
(or its old name, Value0
),
meaning use of an uninitialised CPU condition code. Or:
Addr1
,
Addr2
,
Addr4
or
Addr8
, meaning an invalid address during a
memory access of 1, 2, 4 or 8 bytes respectively. Or
Param
,
meaning an invalid system call parameter error. Or
Free
, meaning an invalid or mismatching free.
Or PThread
, meaning any kind of complaint to do
with the PThreads API.
Last but not least,
you can suppress leak reports with Leak
. Leak
suppression was added in valgrind-1.9.3, I believe.
free
, __builtin_vec_delete
, etc)
Locations may be either names of shared objects/executables or wildcards
matching function names. They begin obj:
and fun:
respectively. Function and object names to match against may use the
wildcard characters *
and ?
.
A suppression only suppresses an error when the error matches all the
details in the suppression. Here's an example:
{ __gconv_transform_ascii_internal/__mbrtowc/mbtowc Memcheck:Value4 fun:__gconv_transform_ascii_internal fun:__mbr*toc fun:mbtowc }
What is means is: in the Memcheck skin only, suppress a
use-of-uninitialised-value error, when the data size is 4, when it
occurs in the function __gconv_transform_ascii_internal
,
when that is called from any function of name matching
__mbr*toc
, when that is called from mbtowc
.
It doesn't apply under any other circumstances. The string by which
this suppression is identified to the user is
__gconv_transform_ascii_internal/__mbrtowc/mbtowc.
Another example, again for the Memcheck skin:
{ libX11.so.6.2/libX11.so.6.2/libXaw.so.7.0 Memcheck:Value4 obj:/usr/X11R6/lib/libX11.so.6.2 obj:/usr/X11R6/lib/libX11.so.6.2 obj:/usr/X11R6/lib/libXaw.so.7.0 }
Suppress any size 4 uninitialised-value error which occurs anywhere
in libX11.so.6.2
, when called from anywhere in the same
library, when called from anywhere in libXaw.so.7.0
. The
inexact specification of locations is regrettable, but is about all
you can hope for, given that the X11 libraries shipped with Red Hat
7.2 have had their symbol tables removed.
Note -- since the above two examples did not make it clear -- that
you can freely mix the obj:
and fun:
styles of description within a single suppression record.
Each byte in the system therefore has a 8 V bits which follow it wherever it goes. For example, when the CPU loads a word-size item (4 bytes) from memory, it also loads the corresponding 32 V bits from a bitmap which stores the V bits for the process' entire address space. If the CPU should later write the whole or some part of that value to memory at a different address, the relevant V bits will be stored back in the V-bit bitmap.
In short, each bit in the system has an associated V bit, which
follows it around everywhere, even inside the CPU. Yes, the CPU's
(integer and %eflags
) registers have their own V bit
vectors.
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.
Here's an (admittedly nonsensical) example:
int i, j; int a[10], b[10]; for (i = 0; i < 10; i++) { j = a[i]; b[i] = j; }
Memcheck emits no complaints about this, since it merely copies
uninitialised values from a[]
into b[]
, and
doesn't use them in any way. However, if the loop is changed to
for (i = 0; i < 10; i++) { j += a[i]; } if (j == 77) printf("hello there\n");then Valgrind will complain, at the
if
, that the
condition depends on uninitialised values. Note that it
doesn't complain at the j += a[i];
, since
at that point the undefinedness is not "observable". It's only
when a decision has to be made as to whether or not to do the
printf
-- an observable action of your program -- that
Memcheck complains.
Most low level operations, such as adds, cause Memcheck to use the V bits for the operands to calculate the V bits for the result. Even if the result is partially or wholly undefined, it does not complain.
Checks on definedness only occur in two places: when a value is used to generate a memory address, and where control flow decision needs to be made. Also, when a system call is detected, valgrind checks definedness of parameters as required.
If a check should detect undefinedness, an error message is issued. The resulting value is subsequently regarded as well-defined. To do otherwise would give long chains of error messages. In effect, we say that undefined values are non-infectious.
This sounds overcomplicated. Why not just check all reads from memory, and complain if an undefined value is loaded into a CPU register? Well, that doesn't work well, because perfectly legitimate C programs routinely copy uninitialised values around in memory, and we don't want endless complaints about that. Here's the canonical example. Consider a struct like this:
struct S { int x; char c; }; struct S s1, s2; s1.x = 42; s1.c = 'z'; s2 = s1;
The question to ask is: how large is struct S
, in
bytes? An int is 4 bytes and a char one byte, so perhaps a struct S
occupies 5 bytes? Wrong. All (non-toy) compilers we know of will
round the size of struct S
up to a whole number of words,
in this case 8 bytes. Not doing this forces compilers to generate
truly appalling code for subscripting arrays of struct
S
's.
So s1 occupies 8 bytes, yet only 5 of them will be initialised.
For the assignment s2 = s1
, gcc generates code to copy
all 8 bytes wholesale into s2
without regard for their
meaning. If Memcheck simply checked values as they came out of
memory, it would yelp every time a structure assignment like this
happened. So the more complicated semantics described above is
necessary. This allows gcc to copy s1
into
s2
any way it likes, and a warning will only be emitted
if the uninitialised values are later used.
One final twist to this story. The above scheme allows garbage to pass through the CPU's integer registers without complaint. It does this by giving the integer registers V tags, passing these around in the expected way. This complicated and computationally expensive to do, but is necessary. Memcheck is more simplistic about floating-point loads and stores. In particular, V bits for data read as a result of floating-point loads are checked at the load instruction. So if your program uses the floating-point registers to do memory-to-memory copies, you will get complaints about uninitialised values. Fortunately, I have not yet encountered a program which (ab)uses the floating-point registers in this way.
As described above, every bit in memory or in the CPU has an associated valid-value (V) bit. In addition, all bytes in memory, but not in the CPU, have an associated valid-address (A) bit. This indicates whether or not the program can legitimately read or write that location. It does not give any indication of the validity or the data at that location -- that's the job of the V bits -- only whether or not the location may be accessed.
Every time your program reads or writes memory, Memcheck checks the A bits associated with the address. If any of them indicate an invalid address, an error is emitted. Note that the reads and writes themselves do not change the A bits, only consult them.
So how do the A bits get set/cleared? Like this:
This apparently strange choice reduces the amount of confusing information presented to the user. It avoids the unpleasant phenomenon in which memory is read from a place which is both unaddressible and contains invalid values, and, as a result, you get not only an invalid-address (read/write) error, but also a potentially large set of uninitialised-value errors, one for every time the value is used.
There is a hazy boundary case to do with multi-byte loads from
addresses which are partially valid and partially invalid. See
details of the flag --partial-loads-ok
for details.
For each such block, Memcheck scans the entire address space of the process, looking for pointers to the block. One of three situations may result:
The precise area of memory in which Memcheck searches for pointers is: all naturally-aligned 4-byte words for which all A bits indicate addressibility and all V bits indicated that the stored value is actually valid.