---------------------------
  • --partial-loads-ok=yes [the default]
    --partial-loads-ok=no

    Controls how Valgrind 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.


  • --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 Valgrind 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 Valgrind but may detect invalid uses of freed blocks which would otherwise go undetected.


  • --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 Valgrind 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 Valgrind's ability to find leaks. It only changes how the results are presented.


  • --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.


  • --cleanup=no
    --cleanup=yes [default]

    When enabled, various improvments are applied to the post-instrumented intermediate code, aimed at removing redundant value checks.


  • 2.6  Explaination of error messages

    Despite considerable sophistication under the hood, Valgrind can only really detect two kinds of errors, use of illegal addresses, and use of undefined values. Nevertheless, this is enough to help you discover all sorts of memory-management nasties in your code. This section presents a quick summary of what error messages mean. The precise behaviour of the error-checking machinery is described in Section 4.

    2.6.1  Illegal read / Illegal write errors

    For example:
      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 Valgrind 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.

    Valgrind 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, Valgrind 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 Valgrind 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 Valgrind immediately prior to this. In this particular example, reading junk on the stack is non-fatal, and the program stays alive.

    2.6.2  Use of uninitialised values

    For example:
      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. Valgrind 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. Valgrind 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 Valgrind complains.

    Sources of uninitialised data tend to be:

    2.6.3  Illegal frees

    For example:
      Invalid free()
         at 0x4004FFDF: free (ut_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 (ut_clientmalloc.c:577)
         by 0x80484C7: main (tests/doublefree.c:10)
         by 0x402A6E5E: __libc_start_main (libc-start.c:129)
         by 0x80483B1: (within tests/doublefree)
    

    Valgrind 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, Valgrind 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.

    2.6.4  When a block is freed with an inappropriate deallocation function

    In the following example, a block allocated with 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:

    The worst thing is that on Linux apparently it doesn't matter if you do muddle these up, and it all seems to work ok, but the same program may then crash on a different platform, Solaris for example. So it's best to fix it properly. According to the KDE folks "it's amazing how many C++ programmers don't know this".

    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[].

    2.6.5  Passing system call parameters with inadequate read/write permissions

    Valgrind checks all parameters to system calls. If a system call needs to read from a buffer provided by your program, Valgrind checks that the entire buffer is addressible and has valid data, ie, it is readable. And if the system call needs to write to a user-supplied buffer, Valgrind checks that the buffer is addressible. After the system call, Valgrind updates its administrative information to precisely reflect any changes in memory permissions caused by the system call.

    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.

    2.6.6  Warning messages you might see

    Most of these only appear if you run in verbose mode (enabled by -v):

    2.7  Writing suppressions files

    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.

    Each suppression has the following components:

    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
        Value4
        fun:__gconv_transform_ascii_internal
        fun:__mbr*toc
        fun:mbtowc
      }
    

    What is means is: 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:

      {
        libX11.so.6.2/libX11.so.6.2/libXaw.so.7.0
        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.

    3  Details of the checking machinery

    Read this section if you want to know, in detail, exactly what and how Valgrind is checking.

    3.1  Valid-value (V) bits

    It is simplest to think of Valgrind implementing a synthetic Intel x86 CPU which is identical to a real CPU, except for one crucial detail. Every bit (literally) of data processed, stored and handled by the real CPU has, in the synthetic CPU, an associated "valid-value" bit, which says whether or not the accompanying bit has a legitimate value. In the discussions which follow, this bit is referred to as the V (valid-value) bit.

    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 Valgrind 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;
      }
    

    Valgrind 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.

    Most low level operations, such as adds, cause Valgrind 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 I 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 Valgrind 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. Valgrind 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.

    3.2  Valid-address (A) bits

    Notice that the previous section describes how the validity of values is established and maintained without having to say whether the program does or does not have the right to access any particular memory location. We now consider the latter issue.

    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, Valgrind 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:

    3.3  Putting it all together

    Valgrind's checking machinery can be summarised as follows: Valgrind intercepts calls to malloc, calloc, realloc, valloc, memalign, free, new and delete. The behaviour you get is:

    3.5  Memory leak detection

    Valgrind keeps track of all memory blocks issued in response to calls to malloc/calloc/realloc/new. So when the program exits, it knows which blocks are still outstanding -- have not been returned, in other words. Ideally, you want your program to have no blocks still in use at exit. But many programs do.

    For each such block, Valgrind scans the entire address space of the process, looking for pointers to the block. One of three situations may result:

    Valgrind reports summaries about leaked and dubious blocks. For each such block, it will also tell you where the block was allocated. This should help you figure out why the pointer to it has been lost. In general, you should attempt to ensure your programs do not have any leaked or dubious blocks at exit.

    The precise area of memory in which Valgrind 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.