Inspect GCC Coverage Files Safely with gcov-dump-13

aarch64-linux-gnu-gcov-dump-13 reads a .gcno or .gcda file and shows you exactly what is inside without changing a byte of it. You will identify which kind of file you have, then choose a readable or comparison-friendly dump.

Allow about 15 minutes if the files already exist. The examples use the installed cross-tool aarch64-linux-gnu-gcov-dump-13, from GCC 13.3.0 on this system. This is a read-only investigation: the command does not collect coverage, merge runs, or rewrite profile data. You normally do not need elevated privileges. Use sudo only if the coverage directory is genuinely unreadable, and prefer fixing a copy or its permissions rather than granting a broad root shell.

1. Confirm the installed command

Check the exact executable and its version before interpreting a dump. GCC coverage formats and diagnostic details are version-sensitive, so do not silently substitute an unqualified gcov-dump from another toolchain.

$ command -v aarch64-linux-gnu-gcov-dump-13
/usr/bin/aarch64-linux-gnu-gcov-dump-13
$ aarch64-linux-gnu-gcov-dump-13 --version
gcov-dump (Ubuntu 13.3.0-6ubuntu2~24.04.1) 13.3.0
$ dpkg-query -W -f='${Package} ${Version}\n' gcc-13-aarch64-linux-gnu
gcc-13-aarch64-linux-gnu 13.3.0-6ubuntu2~24.04.1cross1

2. Check the available switches

Ask the installed binary for its own option list rather than trusting memory. Each documented switch has a one-letter form:

$ aarch64-linux-gnu-gcov-dump-13 --help
Usage: gcov-dump [OPTION] ... gcovfiles
Print coverage file contents
  -h, --help           Print this help
  -l, --long           Dump record contents too
  -p, --positions      Dump record positions
  -r, --raw            Print content records in raw format
  -s, --stable         Print content in stable format usable for comparison
  -v, --version        Print version number

Use one or more coverage file paths after the options. A path can be a .gcno graph file, a .gcda execution-data file, or both. Keep the option area separate from the file names, especially in scripts.

3. Dump a graph file first

A compiler creates a .gcno file when coverage instrumentation is enabled. It describes functions, basic blocks, arcs, and source-line records. Inspect it directly:

$ aarch64-linux-gnu-gcov-dump-13 /path/to/fixture.gcno
/path/to/fixture.gcno:note:magic `gcno':version `B33*'
/path/to/fixture.gcno:stamp 3357659240
/path/to/fixture.gcno:checksum 0
/path/to/fixture.gcno:  01000000:  83:FUNCTION ident=108032747, ...
/path/to/fixture.gcno:    01410000:   4:BLOCKS 5 blocks
/path/to/fixture.gcno:    01430000:  12:ARCS 1 arcs

The exact stamp, checksum, function identifier, source path and record counts depend on the build. The useful first checks are the gcno magic, the format version, and the presence of the expected function or graph records. This is a report, not a compiler or source-code reconstruction tool.

4. Inspect execution data

A .gcda file is normally written when an instrumented program runs. It contains execution summaries and counter records. Point the same tool at it:

$ aarch64-linux-gnu-gcov-dump-13 /path/to/fixture.gcda
/path/to/fixture.gcda:data:magic `gcda':version `B33*'
/path/to/fixture.gcda:stamp 3357670299
/path/to/fixture.gcda:checksum 224192995
/path/to/fixture.gcda:  a1000000:   8:OBJECT_SUMMARY runs=1, sum_max=1
/path/to/fixture.gcda:    01a10000:   8:COUNTERS arcs 1 counts

Use runs and the counter records as clues about whether the program has executed. Do not treat a present file as proof that every path ran: the graph in .gcno and the counters in .gcda answer different questions.

$ aarch64-linux-gnu-gcov-dump-13 /path/to/fixture.gcno /path/to/fixture.gcda

5. Select detail for the question

• Default dump: start here for a quick look.
• --long: add it when you need record contents such as individual arc details.
• --positions: add it when file offsets or record positions matter during a binary-format investigation.
• --raw: add it when you need records in the tool's raw representation.

$ aarch64-linux-gnu-gcov-dump-13 --long /path/to/fixture.gcno
$ aarch64-linux-gnu-gcov-dump-13 --positions /path/to/fixture.gcno
$ aarch64-linux-gnu-gcov-dump-13 --raw /path/to/fixture.gcda

Use --stable for output intended for comparison. Stable output is useful in a review or a regression check, but it does not make unrelated builds identical: source paths, checksums, function identifiers and recorded content can still differ.

$ aarch64-linux-gnu-gcov-dump-13 --stable /path/to/fixture.gcda > /tmp/fixture-gcda.txt
$ diff -u /tmp/fixture-gcda-before.txt /tmp/fixture-gcda.txt

6. Diagnose the common traps

A missing file produces a cannot open diagnostic. Check the path and readability without changing anything:

$ test -r /path/to/fixture.gcda && echo readable
$ ls -l /path/to/fixture.gcda
$ aarch64-linux-gnu-gcov-dump-13 /path/to/fixture.gcda

If there is no .gcda, the instrumented target may not have run, may have written data in another working directory, or may have been unable to write its profile directory. A cross-compiled AArch64 executable cannot be run directly on an x86-64 host; run it on a suitable AArch64 system or emulator, then inspect the resulting data on the host.

Do not confuse a warning or malformed-record diagnostic with a successful coverage result. Save the complete output, check the command's exit status, and compare the .gcno and .gcda produced by the same compatible build. Keep the original files untouched while investigating.