Valgrind User Manual

Release 3.2.3 29 January 2007


Table of Contents

1. Introduction
1.1. An Overview of Valgrind
1.2. How to navigate this manual
2. Using and understanding the Valgrind core
2.1. What Valgrind does with your program
2.2. Getting started
2.3. The Commentary
2.4. Reporting of errors
2.5. Suppressing errors
2.6. Command-line flags for the Valgrind core
2.6.1. Tool-selection option
2.6.2. Basic Options
2.6.3. Error-related options
2.6.4. malloc()-related Options
2.6.5. Uncommon Options
2.6.6. Debugging Valgrind Options
2.6.7. Setting default Options
2.7. The Client Request mechanism
2.8. Support for Threads
2.9. Handling of Signals
2.10. Function wrapping
2.10.1. A Simple Example
2.10.2. Wrapping Specifications
2.10.3. Wrapping Semantics
2.10.4. Debugging
2.10.5. Limitations - control flow
2.10.6. Limitations - original function signatures
2.10.7. Examples
2.11. Building and Installing
2.12. If You Have Problems
2.13. Limitations
2.14. An Example Run
2.15. Warning Messages You Might See
2.16. Debugging MPI Parallel Programs with Valgrind
2.16.1. Building and installing the wrappers
2.16.2. Getting started
2.16.3. Controlling the wrapper library
2.16.4. Abilities and limitations
2.16.5. Writing new wrappers
2.16.6. What to expect when using the wrappers
3. Memcheck: a heavyweight memory checker
3.1. Kinds of bugs that Memcheck can find
3.2. Command-line flags specific to Memcheck
3.3. Explanation of error messages from Memcheck
3.3.1. Illegal read / Illegal write errors
3.3.2. Use of uninitialised values
3.3.3. Illegal frees
3.3.4. When a block is freed with an inappropriate deallocation function
3.3.5. Passing system call parameters with inadequate read/write permissions
3.3.6. Overlapping source and destination blocks
3.3.7. Memory leak detection
3.4. Writing suppression files
3.5. Details of Memcheck's checking machinery
3.5.1. Valid-value (V) bits
3.5.2. Valid-address (A) bits
3.5.3. Putting it all together
3.6. Client Requests
4. Cachegrind: a cache profiler
4.1. Cache profiling
4.1.1. Overview
4.1.2. Cache simulation specifics
4.2. Profiling programs
4.2.1. Output file
4.2.2. Cachegrind options
4.2.3. Annotating C/C++ programs
4.2.4. Annotating assembler programs
4.3. cg_annotate options
4.3.1. Warnings
4.3.2. Things to watch out for
4.3.3. Accuracy
4.4. Implementation details
4.4.1. How Cachegrind works
4.4.2. Cachegrind output file format
5. Callgrind: a heavyweight profiler
5.1. Overview
5.2. Purpose
5.2.1. Profiling as part of Application Development
5.2.2. Profiling Tools
5.3. Usage
5.3.1. Basics
5.3.2. Multiple profiling dumps from one program run
5.3.3. Limiting the range of collected events
5.3.4. Avoiding cycles
5.4. Command line option reference
5.4.1. Miscellaneous options
5.4.2. Dump creation options
5.4.3. Activity options
5.4.4. Data collection options
5.4.5. Cost entity separation options
5.4.6. Cache simulation options
6. Massif: a heap profiler
6.1. Heap profiling
6.1.1. Why Use a Heap Profiler?
6.2. Using Massif
6.2.1. Overview
6.2.2. Basic Results of Profiling
6.2.3. Spacetime Graphs
6.3. Details of Heap Allocations
6.3.1. Accuracy
6.4. Massif Options
7. Helgrind: a data-race detector
7.1. Data Races
7.2. What Helgrind Does
7.3. Helgrind Options
8. Nulgrind: the "null" tool
9. Lackey: a simple profiler and memory tracer
9.1. Overview
9.2. Lackey Options
10. Writing a New Valgrind Tool
10.1. Introduction
10.1.1. Tools
10.2. Writing a Tool
10.2.1. How tools work
10.2.2. Getting the code
10.2.3. Getting started
10.2.4. Writing the code
10.2.5. Initialisation
10.2.6. Instrumentation
10.2.7. Finalisation
10.2.8. Other Important Information
10.2.9. Words of Advice
10.3. Advanced Topics
10.3.1. Suppressions
10.3.2. Documentation
10.3.3. Regression Tests
10.3.4. Profiling
10.3.5. Other Makefile Hackery
10.3.6. Core/tool Interface Versions
10.4. Final Words