			Valgrind Documentation

Valgrind User Manual

Release 3.23.0.verrou-dev 26 Apr 2024

Email: valgrind@valgrind.org

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

2.7. Core Command-line Options

2.7.1. Tool-selection Option
2.7.2. Basic Options
2.7.3. Error-related Options
2.7.4. malloc-related Options
2.7.5. Uncommon Options
2.7.6. Debugging Options
2.7.7. Setting Default Options
2.7.8. Dynamically Changing Options

2.8. Support for Threads

2.8.1. Scheduling and Multi-Thread Performance

2.9. Handling of Signals

2.10. Execution Trees

2.11. Building and Installing Valgrind

2.12. If You Have Problems

2.13. Limitations

2.14. An Example Run

2.15. Warning Messages You Might See

3. Using and understanding the Valgrind core: Advanced Topics

3.1. The Client Request mechanism

3.2. Debugging your program using Valgrind gdbserver and GDB

3.2.1. Quick Start: debugging in 3 steps
3.2.2. Valgrind gdbserver overall organisation
3.2.3. Connecting GDB to a Valgrind gdbserver
3.2.4. Connecting to an Android gdbserver
3.2.5. Monitor command handling by the Valgrind gdbserver
3.2.6. GDB front end commands for Valgrind gdbserver monitor commands
3.2.7. Valgrind gdbserver thread information
3.2.8. Examining and modifying Valgrind shadow registers
3.2.9. Limitations of the Valgrind gdbserver
3.2.10. vgdb command line options
3.2.11. Valgrind monitor commands

3.3. Function wrapping

3.3.1. A Simple Example
3.3.2. Wrapping Specifications
3.3.3. Wrapping Semantics
3.3.4. Debugging
3.3.5. Limitations - control flow
3.3.6. Limitations - original function signatures
3.3.7. Examples

4. Memcheck: a memory error detector

4.1. Overview

4.2. Explanation of error messages from Memcheck

4.2.1. Illegal read / Illegal write errors
4.2.2. Use of uninitialised values
4.2.3. Use of uninitialised or unaddressable values in system calls
4.2.4. Illegal frees
4.2.5. When a heap block is freed with an inappropriate deallocation function
4.2.6. Overlapping source and destination blocks
4.2.7. Fishy argument values
4.2.8. Realloc size zero
4.2.9. Alignment Errors
4.2.10. Memory leak detection

4.3. Memcheck Command-Line Options

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. Memcheck Monitor Commands

4.7. Client Requests

4.8. Memory Pools: describing and working with custom allocators

4.9. Debugging MPI Parallel Programs with Valgrind

4.9.1. Building and installing the wrappers
4.9.2. Getting started
4.9.3. Controlling the wrapper library
4.9.4. Functions
4.9.5. Types
4.9.6. Writing new wrappers
4.9.7. What to expect when using the wrappers

5. Cachegrind: a high-precision tracing profiler

5.1. Overview

5.2. Using Cachegrind and cg_annotate

5.2.1. Running Cachegrind
5.2.2. Output File
5.2.3. Running cg_annotate
5.2.4. The Metadata Section
5.2.5. Global, File, and Function-level Counts
5.2.6. Per-line Counts
5.2.7. Forking Programs
5.2.8. cg_annotate Warnings
5.2.9. Merging Cachegrind Output Files
5.2.10. Differencing Cachegrind output files
5.2.11. Cache and Branch Simulation

5.3. Cachegrind Command-line Options

5.4. cg_annotate Command-line Options

5.5. cg_merge Command-line Options

5.6. cg_diff Command-line Options

5.7. Cachegrind Client Requests

5.8. Simulation Details

5.8.1. Cache Simulation Specifics
5.8.2. Branch Simulation Specifics
5.8.3. Accuracy

5.9. Implementation Details

5.9.1. How Cachegrind Works
5.9.2. Cachegrind Output File Format

6. Callgrind: a call-graph generating cache and branch prediction 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. Counting global bus events
6.2.4. Avoiding cycles
6.2.5. Forking Programs

6.3. Callgrind Command-line Options

6.3.1. Dump creation options
6.3.2. Activity options
6.3.3. Data collection options
6.3.4. Cost entity separation options
6.3.5. Simulation options
6.3.6. Cache simulation options

6.4. Callgrind Monitor Commands

6.5. Callgrind specific client requests

6.6. callgrind_annotate Command-line Options

6.7. callgrind_control Command-line Options

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 Command-line Options

7.7. Helgrind Monitor Commands

7.8. Helgrind Client Requests

7.9. A To-Do List for Helgrind

8. DRD: a thread error detector

8.1. Overview

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. DRD 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 C++11 Programs
8.2.7. Debugging GNOME 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.4. Limitations

8.5. Feedback

9. Massif: a heap profiler

9.1. Overview

9.2. Using Massif and ms_print

9.2.1. An Example Program
9.2.2. Running Massif
9.2.3. Running ms_print
9.2.4. The Output Preamble
9.2.5. The Output Graph
9.2.6. The Snapshot Details
9.2.7. Forking Programs
9.2.8. Measuring All Memory in a Process
9.2.9. Acting on Massif's Information

9.3. Using massif-visualizer

9.4. Massif Command-line Options

9.5. Massif Monitor Commands

9.6. Massif Client Requests

9.7. ms_print Command-line Options

9.8. Massif's Output File Format

10. DHAT: a dynamic heap analysis tool

10.1. Overview

10.2. Using DHAT

10.2.1. Running DHAT
10.2.2. Output File

10.3. DHAT's Viewer

10.3.1. The Output Header
10.3.2. The PP Tree
10.3.3. The Output Footer
10.3.4. Sort Metrics

10.4. Treatment of realloc

10.5. Copy profiling

10.6. Ad hoc profiling

10.7. DHAT Command-line Options

11. Lackey: an example tool

11.1. Overview
11.2. Lackey Command-line Options

12. Verrou: a floating-point rounding errors checker

12.1. Overview

12.1.1. Basic usage
12.1.2. Restriction of the perturbations scope

12.2. Standard features

12.2.1. Floating-point instructions counting
12.2.2. Rounding-mode switching

12.3. Restriction of the perturbations scope

12.3.1. Excluded symbols
12.3.2. Instrumented sections

12.4. Debugging and error localization

12.4.1. Delta-debugging with the verrou_dd_sym, verrou_dd_line, verrou_dd_task and verrou_dd_stdout commands
12.4.2. Code coverage comparison
12.4.3. Basic Block coverage comparison
12.4.4. post_verrou_dd
12.4.5. verrou_plot_stat

12.5. Advanced features

12.5.1. Deterministic sections

12.6. Reference

12.6.1. Command-line options
12.6.2. Client requests
12.6.3. IOMatch script
12.6.4. Monitor commands

13. Nulgrind: the minimal Valgrind tool

13.1. Overview

14. BBV: an experimental basic block vector generation tool

14.1. Overview
14.2. Using Basic Block Vectors to create SimPoints
14.3. BBV Command-line Options
14.4. Basic Block Vector File Format
14.5. Implementation
14.6. Threaded Executable Support
14.7. Validation
14.8. Performance