Valgrind User Manual

Release 3.4.0 2 January 2009


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. Support for Threads
2.8. Handling of Signals
2.9. Building and Installing Valgrind
2.10. If You Have Problems
2.11. Limitations
2.12. An Example Run
2.13. Warning Messages You Might See
3. Using and understanding the Valgrind core: Advanced Topics
3.1. The Client Request mechanism
3.2. Function wrapping
3.2.1. A Simple Example
3.2.2. Wrapping Specifications
3.2.3. Wrapping Semantics
3.2.4. Debugging
3.2.5. Limitations - control flow
3.2.6. Limitations - original function signatures
3.2.7. Examples
4. Memcheck: a heavyweight memory checker
4.1. Kinds of bugs that Memcheck can find
4.2. Command-line flags specific to Memcheck
4.3. Explanation of error messages from Memcheck
4.3.1. Illegal read / Illegal write errors
4.3.2. Use of uninitialised values
4.3.3. Illegal frees
4.3.4. When a block is freed with an inappropriate deallocation function
4.3.5. Passing system call parameters with inadequate read/write permissions
4.3.6. Overlapping source and destination blocks
4.3.7. Memory leak detection
4.4. Writing suppression files
4.5. Details of Memcheck's checking machinery
4.5.1. Valid-value (V) bits
4.5.2. Valid-address (A) bits
4.5.3. Putting it all together
4.6. Client Requests
4.7. Memory Pools: describing and working with custom allocators
4.8. Debugging MPI Parallel Programs with Valgrind
4.8.1. Building and installing the wrappers
4.8.2. Getting started
4.8.3. Controlling the wrapper library
4.8.4. Abilities and limitations
4.8.5. Writing new wrappers
4.8.6. What to expect when using the wrappers
5. Cachegrind: a cache and branch profiler
5.1. Cache and branch profiling
5.1.1. Overview
5.1.2. Cache simulation specifics
5.1.3. Branch simulation specifics
5.2. Profiling programs
5.2.1. Output file
5.2.2. Cachegrind options
5.2.3. Annotating C/C++ programs
5.2.4. Annotating assembly code programs
5.2.5. Forking Programs
5.3. cg_annotate options
5.3.1. Warnings
5.3.2. Things to watch out for
5.3.3. Accuracy
5.4. Merging profiles with cg_merge
5.5. Acting on Cachegrind's information
5.6. Implementation details
5.6.1. How Cachegrind works
5.6.2. Cachegrind output file format
6. Callgrind: a call graph profiler
6.1. Overview
6.1.1. Functionality
6.1.2. Basic Usage
6.2. Advanced Usage
6.2.1. Multiple profiling dumps from one program run
6.2.2. Limiting the range of collected events
6.2.3. Avoiding cycles
6.2.4. Forking Programs
6.3. Command line option reference
6.3.1. Miscellaneous options
6.3.2. Dump creation options
6.3.3. Activity options
6.3.4. Data collection options
6.3.5. Cost entity separation options
6.3.6. Cache simulation options
6.4. Callgrind specific client requests
7. Helgrind: a thread error detector
7.1. Overview
7.2. Detected errors: Misuses of the POSIX pthreads API
7.3. Detected errors: Inconsistent Lock Orderings
7.4. Detected errors: Data Races
7.4.1. A Simple Data Race
7.4.2. Helgrind's Race Detection Algorithm
7.4.3. Interpreting Race Error Messages
7.5. Hints and Tips for Effective Use of Helgrind
7.6. Helgrind Options
7.7. A To-Do List for Helgrind
8. DRD: a thread error detector
8.1. Background
8.1.1. Multithreaded Programming Paradigms
8.1.2. POSIX Threads Programming Model
8.1.3. Multithreaded Programming Problems
8.1.4. Data Race Detection
8.2. Using DRD
8.2.1. Command Line Options
8.2.2. Detected Errors: Data Races
8.2.3. Detected Errors: Lock Contention
8.2.4. Detected Errors: Misuse of the POSIX threads API
8.2.5. Client Requests
8.2.6. Debugging GNOME Programs
8.2.7. Debugging Qt Programs
8.2.8. Debugging Boost.Thread Programs
8.2.9. Debugging OpenMP Programs
8.2.10. DRD and Custom Memory Allocators
8.2.11. DRD Versus Memcheck
8.2.12. Resource Requirements
8.2.13. Hints and Tips for Effective Use of DRD
8.3. Using the POSIX Threads API Effectively
8.3.1. Mutex types
8.3.2. Condition variables
8.3.3. pthread_cond_timedwait() and timeouts
8.3.4. Assigning names to threads
8.4. Limitations
8.5. Feedback
9. Massif: a heap profiler
9.1. Heap profiling
9.2. Using Massif
9.2.1. An Example Program
9.2.2. The Output Preamble
9.2.3. The Output Graph
9.2.4. The Snapshot Details
9.2.5. Forking Programs
9.3. Massif Options
9.4. ms_print Options
9.5. Massif's output file format
10. Ptrcheck: an (experimental) pointer checking tool
10.1. Overview
10.2. Ptrcheck Options
10.3. How Ptrcheck Works: Heap Checks
10.4. How Ptrcheck Works: Stack and Global Checks
10.5. Comparison with Memcheck
10.6. Limitations
10.7. Still To Do: User Visible Functionality
10.8. Still To Do: Implementation Tidying
11. Nulgrind: the "null" tool
12. Lackey: a simple profiler and memory tracer
12.1. Overview
12.2. Lackey Options
13. Writing a New Valgrind Tool
13.1. Introduction
13.1.1. Tools
13.2. Writing a Tool
13.2.1. How tools work
13.2.2. Getting the code
13.2.3. Getting started
13.2.4. Writing the code
13.2.5. Initialisation
13.2.6. Instrumentation
13.2.7. Finalisation
13.2.8. Other Important Information
13.2.9. Words of Advice
13.3. Advanced Topics
13.3.1. Suppressions
13.3.2. Documentation
13.3.3. Regression Tests
13.3.4. Profiling
13.3.5. Other Makefile Hackery
13.3.6. Core/tool Interface Versions
13.4. Final Words