Inspect GCC Coverage Files with gcov-dump

You will use x86_64-linux-gnu-gcov-dump-13 to inspect GCC coverage files without running a coverage report or changing the files. The examples show the normal record view, detailed counter values, stable output for comparisons, and the boundary between source data and the tool's interpretation.

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.

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

The unversioned names, including gcov-dump, gcov-dump-13 and x86_64-linux-gnu-gcov-dump, are aliases in this installation group. If you need 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 normally 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.gcda

A .gcno file describes compile-time coverage structure. A .gcda file carries run-time data, such as execution counts. They are related, but they are not interchangeable: inspect the file you actually need to explain.

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 counts

The 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: 1

For 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. These options are most useful when you are 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: 0

The 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 as 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: 0

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