Valgrind

Purpose

Guide agents through Valgrind tools: Memcheck for memory errors, Cachegrind for cache simulation, Callgrind for call graphs, and Massif for heap profiling.

Triggers

• "My program has a memory leak / use-after-free"
• "I can't use ASan — can I use Valgrind instead?"
• "How do I profile cache behaviour without perf?"
• "How do I visualize call graphs with Callgrind?"
• "How do I profile heap allocation patterns?"
• "Valgrind reports errors in third-party code I can't fix"

Workflow

1. Memcheck — memory error detection

Compile with -g -O1 for best results. -O0 is also fine; avoid -O2+ which can produce false positives.

valgrind --tool=memcheck \
         --leak-check=full \
         --show-leak-kinds=all \
         --track-origins=yes \
         --error-exitcode=1 \
         ./prog [args]

Key flags:

Flag	Default	Effect
--leak-check=full	summary	Full leak details
--show-leak-kinds=all	definite	Show all leak kinds
--track-origins=yes	no	Show where uninit values came from (slow)
--error-exitcode=N	0	Exit N if errors found (CI integration)
--log-file=file	stderr	Save report to file
--suppressions=file	none	Suppress known FPs
--gen-suppressions=yes	no	Print suppression directives for errors
--max-stackframe=N	2000000	Increase for deep stacks
--malloc-fill=0xAB	off	Fill allocated memory (detect uninit use)
--free-fill=0xCD	off	Fill freed memory (detect use-after-free)

2. Understanding Memcheck output

==12345== Invalid read of size 4
==12345==    at 0x4007A2: foo (main.c:15)
==12345==    by 0x400846: main (main.c:30)
==12345==  Address 0x5204040 is 0 bytes after a block of size 40 alloc'd
==12345==    at 0x4C2FB0F: malloc (in /usr/lib/valgrind/vgpreload_memcheck.so)
==12345==    by 0x40074B: main (main.c:25)

• Invalid read/write: out-of-bounds access; check array bounds
• Use of uninitialised value: read before write; use --track-origins=yes
• Invalid free / double free: mismatched malloc/free; check ownership
• Definitely lost: reachable via no pointers; clear leak
• Indirectly lost: lost through a chain; usually means one root leak
• Possibly lost: might be pointing into the middle of a block; often FP with custom allocators

3. Leak kinds

Kind	Meaning
Definitely lost	No pointer to block
Indirectly lost	Lost via another lost block
Possibly lost	Pointer into middle of block
Still reachable	Pointer exists at exit; not a leak but never freed

For library code: --show-leak-kinds=definite,indirect reduces noise from still-reachable.

4. Suppressions

# Generate suppression for current error
valgrind --gen-suppressions=yes ./prog 2>&1 | grep -A20 '{'

# Example suppression file (valgrind.supp)
{
   openssl_uninit
   Memcheck:Cond
   fun:SHA256_Init
   ...
}

# Use suppression file
valgrind --suppressions=valgrind.supp ./prog

5. Cachegrind — cache simulation

valgrind --tool=cachegrind ./prog

# Output: cachegrind.out.PID
# Annotate source
cg_annotate cachegrind.out.12345 --auto=yes

# Diff two runs
cg_diff cachegrind.out.before cachegrind.out.after

Key metrics:

• I1mr / ILmr: L1/LL instruction cache miss rate
• D1mr / DLmr: L1/LL data read miss rate
• D1mw / DLmw: L1/LL data write miss rate

6. Callgrind — call graph profiling

valgrind --tool=callgrind --callgrind-out-file=callgrind.out ./prog

# Analyse
callgrind_annotate callgrind.out

# Visualise in KCachegrind (GUI)
kcachegrind callgrind.out

Callgrind is slower than perf but works without root and provides exact call counts.

7. Massif — heap profiling

valgrind --tool=massif ./prog

# Visualise
ms_print massif.out.PID | less

# GUI
massif-visualizer massif.out.PID

Massif shows heap usage over time; useful for finding peak allocation sites and tracking gradual leaks.

8. Performance considerations

Valgrind Memcheck runs ~10-50x slower than native. Mitigations:

• Use a shorter representative workload
• Use --error-exitcode=1 to fail fast in CI
• Use ASan (-fsanitize=address) for faster memory checking during development
• Reserve Valgrind for cases where ASan can't be used (old toolchains, production-like environments)

For a comparison of Valgrind vs ASan, see references/valgrind-vs-asan.md.

Related skills

• Use skills/runtimes/sanitizers for faster ASan/UBSan alternatives
• Use skills/profilers/linux-perf for CPU-level profiling (faster than Cachegrind)
• Use skills/profilers/flamegraphs to visualise Callgrind output