The content of this page is out of date. Please go to the GNOME Developers Documentation website for the up to date version.
Valgrind is a programmer tool that allows to track memory related errors in C and C++ programs. I'll spare you the introduction which you can find on the website.
This page includes some tips on how to proficiently use valgrind on GTK/GNOME programs. Feel free to add your own tricks or expand the page with more detailed explanations.
Memcheck is the main valgrind tool, it allows to detect memory leaks and other memory management errors. To run a gnome program under memcheck run:
valgrind --leak-check=full --leak-resolution=high --num-callers=20 --log-file=vgdump your-program
If the program you are debugging uses dynamically loaded modules with GModule (for instance it has a GModule based plugin system) you should use G_DEBUG=resident-modules to make sure that the modules do not get unloaded and valgrind can retrieve the function names when writing its log:
G_DEBUG=resident-modules valgrind --leak-check=full --leak-resolution=high --num-callers=20 --log-file=vgdump your-program
After running the program you can inspect the log in the vgdump file. The log contains a list of memory related issues and in particular memory leaks. Memory leaks are marked in three ways: definitely lost, possibly lost and still reachable: for a start concentrate on the definitely lost ones, which are bits of memory leaked for sure - you can filter for them by passing --show-leak-kinds=definite. For each leak valgrind provides a backtrace which lets you pinpoint exactly where the leaks happens, in particular if your program was compiled with debugging symbols, valgrind will tell you the exact line and file of the leak.
Note: If your binary is really a libtool-generated temporary wrapper, the above command line will run valgrind on your shell which is probably not what you want. Say instead
libtool --mode=execute valgrind --tool=memcheck --leak-check=full --leak-resolution=high --num-callers=20 --log-file=vgdump your-program
GLib and other libraries often make one-off allocations that are meant to exist until the end of the lifetime of you application. These are not leaks, but Valgrind will mark them as such. In order to avoid cluttering your reports, you can use "suppression files", to tell Valgrind to eliminate known one-off allocations. GLib and GTK provide suppression files that you can use.
Assuming your copy of GLib and GTK are installed under /usr, the Valgrind suppression files are located here:
You can use them with the --suppressions argument for the memcheck tool, e.g.:
valgrind --tool=memcheck --suppressions=/usr/share/glib-2.0/valgrind/glib.supp your-glib-app
You can use multiple --suppressions argument, one for each suppression file.
Massif is a memory usage profiler. See this page for an explanation of how to use it in GNOME.
It can be tricky to get Valgrind to run on session-wide programs like Nautilus or gnome-panel. Here is how to do it.
Ubuntu users can look at the Ubuntu documentation about Valgrind to know all the details to get Valgrind working.