Inspect GCC Coverage Files with gcov-dump
A .gcda file will not tell you why gcov's numbers look wrong, but x86_64-linux-gnu-gcov-dump-13 will. This guide reads coverage files without running a coverage report or changing anything: the normal record view, detailed counter values, stable output for comparisons, and the line between source data and the tool's interpretation of it.
The route
Jump straight to the step you need, or tick off Done means at the end.
Allow about fifteen minutes. You need GCC 13's coverage tools and at least one .gcda or .gcno file. The installed command is GCC 13.3.0 from Ubuntu package gcc-13 13.3.0-6ubuntu2~24.04.1. No command in this guide needs elevated privileges.
Checkpoint
This guide only reads profile files. It does not delete, rewrite or merge them. Keep the original files in place while you investigate.
1. Confirm the installed command
The versioned executable is useful on a host with more than one GCC installation. Check both its location and its version:
$ command -v x86_64-linux-gnu-gcov-dump-13
/usr/bin/x86_64-linux-gnu-gcov-dump-13
$ x86_64-linux-gnu-gcov-dump-13 --version
gcov-dump (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0The unversioned names, including gcov-dump, gcov-dump-13 and x86_64-linux-gnu-gcov-dump, are aliases in this installation group. For repeatable tooling, call the versioned name and record its version alongside your output.
2. Find the coverage files
gcov-dump accepts one or more coverage file names. GCC produces .gcno files when compiling with coverage instrumentation and .gcda files when the instrumented program runs. Search the build or test output directory rather than guessing a path:
$ find ./build -type f \( -name '*.gcda' -o -name '*.gcno' \) -print
./build/obj/sample.gcno
./build/obj/sample.gcdaA .gcno file describes compile-time coverage structure. A .gcda file carries run-time data, such as execution counts. They are related, but not interchangeable: inspect the one you actually need to explain.
Checkpoint
Preserve the exact path. Profile files can share a base name across different object directories, and looking at the wrong one produces a convincing but irrelevant answer.
3. Dump the readable record view
Pass a file with no display options first. This gives a compact view of the file type, format version, checksum records and other recognised records:
$ x86_64-linux-gnu-gcov-dump-13 ./build/obj/sample.gcda
./build/obj/sample.gcda:data:magic `gcda':version `B33*'
./build/obj/sample.gcda:stamp 3881863536
./build/obj/sample.gcda:checksum 2481506161
./build/obj/sample.gcda: a1000000: 8:OBJECT_SUMMARY runs=1, sum_max=1
./build/obj/sample.gcda: 01000000: 12:FUNCTION ident=108032747, lineno_checksum=0x13bbed93, cfg_checksum=0xdb5de9e8
./build/obj/sample.gcda: 01a10000: 8:COUNTERS arcs 1 countsThe numeric values are file data, not universal constants: a different build, source tree or run count will change them. Use this view to answer questions such as whether the file is a gcda or gcno file, and whether it contains a counter record.
4. Show record contents with long output
Add --long when the record headers are not enough. It asks the tool to print the contents of records too:
$ x86_64-linux-gnu-gcov-dump-13 --long ./build/obj/sample.gcda
./build/obj/sample.gcda: 01a10000: 8:COUNTERS arcs 1 counts
./build/obj/sample.gcda: 0: 1For a simple program that has run once, an arc count of 1 is a plausible result. Do not treat that number as expected for every program: it depends on which paths ran and how the compiler instrumented the code.
--raw changes how content records are printed, while --stable requests a stable format suitable for comparisons. Both are most useful when comparing two files produced by the same toolchain:
$ x86_64-linux-gnu-gcov-dump-13 --long --stable ./build/obj/sample.gcda > sample.gcda.dump
$ x86_64-linux-gnu-gcov-dump-13 --long --stable ./build/obj/sample.gcda | diff -u - sample.gcda.dump
$ printf 'diff status: %s\n' "$?"
diff status: 0The second command compares the command's output with the file just saved: a zero status means the two text streams match. The dump is derived text, so it is safe to remove; the coverage file is the original evidence and should not be replaced by the dump.
5. Include record positions when locating a problem
Use --positions when you need the positions of records in the coverage file, for example while investigating a damaged or truncated file:
$ x86_64-linux-gnu-gcov-dump-13 --positions ./build/obj/sample.gcda
./build/obj/sample.gcda:data:magic `gcda':version `B33*'
... record output continues ...The precise offsets and the records shown depend on the file. Treat this as diagnostic output, not a stable format, unless you also select --stable and keep the GCC version fixed.
6. Handle failures without mistaking them for empty data
Check the command's status and output together:
$ x86_64-linux-gnu-gcov-dump-13 ./build/obj/does-not-exist.gcda
./build/obj/does-not-exist.gcda:cannot open
$ printf 'gcov-dump status: %s\n' "$?"
gcov-dump status: 0Warning
On this installed GCC 13.3.0 build, a missing file prints cannot open but still returns status 0. That is a trap for scripts: do not use the exit status alone to claim every input was inspected. Capture standard output and standard error, check that each requested path produced meaningful records, and report the diagnostic text.
If you see a format or version complaint, first check that the file is really a gcda or gcno file and that you are using a compatible GCC tool. Do not edit a profile file to make the warning disappear. Rebuild the matching object, or collect a fresh profile, if the file is incomplete.
Done means
- Command confirmed: you checked the GCC 13.3.0 executable and its version.
- File identified: you found the exact
.gcdaor.gcnopath. - Normal view first: you used the plain dump before selecting extra output modes.
- Extra modes used deliberately:
--long,--raw,--stableor--positionsserved a stated diagnostic purpose. - Diagnostics checked: you read the diagnostic text as well as the process status.