GCOV(1)

gcov — the coverage testing tool bestie 💖

okay so this is the GCOV(1) page, from the GNU manual set. it's giving "let me spy on your code and tell you which lines never got any love." let's go 🫶

---

✨ NAME ✨

gcov — coverage testing tool 💅

---

🎀 SYNOPSIS 🎀

gcov [-v|--version] [-h|--help]
     [-a|--all-blocks]
     [-b|--branch-probabilities]
     [-c|--branch-counts]
     [-g|--conditions]
     [-d|--display-progress]
     [-f|--function-summaries]
     [-j|--json-format]
     [-H|--human-readable]
     [-k|--use-colors]
     [-l|--long-file-names]
     [-m|--demangled-names]
     [-n|--no-output]
     [-o|--object-directory directory|file]
     [-p|--preserve-paths]
     [-q|--use-hotness-colors]
     [-r|--relative-only]
     [-s|--source-prefix directory]
     [-t|--stdout]
     [-u|--unconditional-branches]
     [-x|--hash-filenames]
     files

---

🌸 DESCRIPTION 🌸

so gcov is a test coverage program, bestie. you run it in concert with GCC to analyze your programs, and it helps you make more efficient, faster-running code and find the untested parts of your program. it's literally a detective for your source files 🔍. you can also use it as a profiling tool to figure out where your optimization efforts will best affect your code. and plot twist: you can use it alongside the other profiling tool, gprof, to assess which parts of your code are eating the greatest amount of computing time. obsessed.

profiling tools help you analyze your code's performance, periodt. using a profiler like gcov or gprof, you can find out some basic performance statistics, such as:

• how often each line of code executes
• what lines of code are actually executed
• how much computing time each section of code uses

once you know these things about how your code works when compiled, you can look at each module to see which modules should be optimized. gcov helps you determine where to work on optimization. main character behavior fr fr 👑

software developers also use coverage testing in concert with testsuites, to make sure software is actually good enough for a release. testsuites can verify that a program works as expected; a coverage program tests to see how much of the program is exercised by the testsuite. developers can then determine what kinds of test cases need to be added to the testsuites to create both better testing and a better final product. it's the glow-up pipeline 💖

you should compile your code without optimization if you plan to use gcov. why? because the optimization, by combining some lines of code into one function, may not give you as much information as you need to look for 'hot spots' where the code is using a great deal of computer time. iykyk.

likewise, because gcov accumulates statistics by line (at the lowest resolution), it works best with a programming style that places only one statement on each line. if you use complicated macros that expand to loops or to other control structures, the statistics are less helpful — they only report on the line where the macro call appears 😭. if your complex macros behave like functions, you can replace them with inline functions to solve this problem. slay.

gcov creates a logfile called sourcefile.gcov which indicates how many times each line of a source file sourcefile.c has executed. you can use these logfiles along with gprof to aid in fine-tuning the performance of your programs. gprof gives timing information you can use along with the information you get from gcov. dynamic duo energy 🦋

real talk though: gcov works only on code compiled with GCC. it is not compatible with any other profiling or test coverage mechanism. no crossovers, sorry 💀

---

💅 OPTIONS 💅

• -a, --all-blocks — write individual execution counts for every basic block. normally gcov outputs execution counts only for the main blocks of a line. with this option you can determine if blocks within a single line are not being executed. zoom in on the details bestie 🔍
• -b, --branch-probabilities — write branch frequencies to the output file, and write branch summary info to the standard output. this option allows you to see how often each branch in your program was taken. unconditional branches will not be shown, unless the -u option is given.
• -c, --branch-counts — write branch frequencies as the number of branches taken, rather than the percentage of branches taken. numbers over percentages, we love that 🍓
• -g, --conditions — write condition coverage to the output file, and write condition summary info to the standard output. this option allows you to see if the conditions in your program at least once had an independent effect on the outcome of the boolean expression (modified condition/decision coverage). > heads up: this requires you to compile the source with -fcondition-coverage. no flag, no data ✨
• -d, --display-progress — display the progress on the standard output. watching it load ✨
• -f, --function-summaries — output summaries for each function in addition to the file level summary. per-function receipts 💖
• -h, --help — display help about using gcov (on the standard output), and exit without doing any further processing. classic.
• -j, --json-format — output gcov file in an easy-to-parse JSON intermediate format which does not require source code for generation. the JSON file is compressed with gzip compression algorithm and the files have the .gcov.json.gz extension. machine-readable era 🎀

structure of the JSON is following:

{
  "current_working_directory": "foo/bar",
  "data_file": "a.out",
  "format_version": "2",
  "gcc_version": "11.1.1 20210510"
  "files": ["$file"]
}

fields of the root element have following semantics:

• current_working_directory: working directory where a compilation unit was compiled
• data_file: name of the data file (GCDA)
• format_version: semantic version of the format

changes in version 2:

• calls: information about function calls is added

• gcc_version: version of the GCC compiler

each file has the following form:

{
  "file": "a.c",
  "functions": ["$function"],
  "lines": ["$line"]
}

fields of the file element have following semantics:

• file_name: name of the source file

each function has the following form:

{
  "blocks": 2,
  "blocks_executed": 2,
  "demangled_name": "foo",
  "end_column": 1,
  "end_line": 4,
  "execution_count": 1,
  "name": "foo",
  "start_column": 5,
  "start_line": 1
}

fields of the function element have following semantics:

• blocks: number of blocks that are in the function
• blocks_executed: number of executed blocks of the function
• demangled_name: demangled name of the function
• end_column: column in the source file where the function ends
• end_line: line in the source file where the function ends
• execution_count: number of executions of the function
• name: name of the function
• start_column: column in the source file where the function begins
• start_line: line in the source file where the function begins

note that line numbers and column numbers number from 1. in the current implementation, start_line and start_column do not include any template parameters and the leading return type but that this is likely to be fixed in the future. 🙈

each line has the following form:

{
  "block_ids": ["$block_id"],
  "branches": ["$branch"],
  "calls": ["$call"],
  "count": 2,
  "conditions": ["$condition"],
  "line_number": 15,
  "unexecuted_block": false,
  "function_name": "foo",
}

branches and calls are present only with -b option. fields of the line element have following semantics:

• block_ids: IDs of basic blocks that belong to the line
• count: number of executions of the line
• line_number: line number
• unexecuted_block: flag whether the line contains an unexecuted block (not all statements on the line are executed)
• function_name: a name of a function this line belongs to (for a line with an inlined statements can be not set)

each branch has the following form:

{
  "count": 11,
  "destination_block_id": 17,
  "fallthrough": true,
  "source_block_id": 13,
  "throw": false
}

fields of the branch element have following semantics:

• count: number of executions of the branch
• fallthrough: true when the branch is a fall through branch
• throw: true when the branch is an exceptional branch
• isource_block_id: ID of the basic block where this branch happens
• destination_block_id: ID of the basic block this branch jumps to

each call has the following form:

{
  "destination_block_id": 1,
  "returned": 11,
  "source_block_id": 13
}

fields of the call element have following semantics:

• returned: number of times a function call returned (call count is equal to line::count)
• isource_block_id: ID of the basic block where this call happens
• destination_block_id: ID of the basic block this calls continues after return

each condition has the following form:

{
  "count": 4,
  "covered": 2,
  "not_covered_false": [],
  "not_covered_true": [0, 1],
}

fields of the condition element have following semantics:

• count: number of condition outcomes in this expression
• covered: number of covered condition outcomes in this expression
• not_covered_true: terms, by index, not seen as true in this expression
• not_covered_false: terms, by index, not seen as false in this expression

• -H, --human-readable — write counts in human readable format (like 24.6k). our brains are not built for long digits 🧚
• -k, --use-colors — use colors for lines of code that have zero coverage. we use red color for non-exceptional lines and cyan for exceptional. same colors are used for basic blocks with -a option. aesthetic and informative, we stay winning 🌈

---

• -l, --long-file-names — bestie this one makes long file names for included source files. Say your header x.h has code in it and it got included into a.c — running gcov on a.c will spit out a file called a.c##x.h.gcov instead of just x.h.gcov. Obsessed, honestly. Super handy when x.h shows up in a bunch of source files and you wanna see each individual contribution. And if you also pass -p, both the including and the included file names go full path-name mode. 💅
• -m, --demangled-names — shows demangled function names in the output. Default behavior is to show the mangled ones (iykyk, the ugly ones).
• -n, --no-output — do not create the gcov output file. Nothing. Nada. 🚫
• -o directory|file, --object-directory directory, --object-file file — tell gcov either the directory that's holding your gcov data files, or the object path name itself. The .gcno and .gcda data files get searched for using this option.
  • If you give it a directory, the data files live in that directory and are named after the input file name, minus its extension.
  • If you give it a file, the data files are named after that file, minus its extension.
• -p, --preserve-paths — keeps the complete path info in the names of the generated .gcov files. Without this, only the filename component gets used. With it, every directory is used, with / characters translated to # characters, . directory components removed, and unremoveable .. components renamed to ^. Lowkey essential when your source files are scattered across several different directories. 🌈
• -q, --use-hotness-colors — emits perf-like colored output for hot lines 🔥. The legend of the color scale gets printed at the very beginning of the output file.
• -r, --relative-only — only outputs info about source files with a relative pathname (after source prefix elision, bestie). Absolute paths are usually system header files, and coverage of any inline functions in those is normally... not it. Uninteresting, we say. 💀
• -s directory, --source-prefix directory — a prefix for source file names to remove when generating the output coverage files. This one's a lifesaver when you're building in a separate directory and you don't want the pathname to the source directory showing up when it's determining the output file names. Note bestie: this prefix detection gets applied before determining whether the source file is absolute. Important order of operations, no cap.
• -t, --stdout — output to standard output instead of to output files. Straight to the terminal, main character energy. ✨
• -u, --unconditional-branches — when branch probabilities are given, include the ones from unconditional branches too. Unconditional branches are normally not interesting, fr fr.
• -v, --version — display the gcov version number (on the standard output), and exit without doing any further processing. Just a lil vibe check and then it's out. 👑
• -w, --verbose — prints verbose informations related to basic blocks and arcs. (Yes, "informations". We keep it exactly as written, don't @ me.) 🫶
• -x, --hash-filenames — okay so when you use --preserve-paths, gcov uses the full pathname of the source files to create an output filename. That can lead to long filenames that can overflow filesystem limits 😭. This option instead creates names of the form source-file##md5.gcov, where the source-file component is the final filename part and the md5 component is calculated from the full mangled name that would have been used otherwise. It's an alternative to --preserve-paths on systems which have a filesystem limit.

---

okay now the actual ~lore~ of how this thing works, bestie, sit down 🎀

gcov should be run with the current directory the same as that when you invoked the compiler. Otherwise it will not be able to locate the source files. (Yes, that's a real requirement, not a suggestion. 🙈)

gcov produces files called mangledname.gcov in the current directory. These contain the coverage information of the source file they correspond to. One .gcov file is produced for each source (or header) file containing code, which was compiled to produce the data files. The mangledname part of the output file name is usually simply the source file name, but can be something more complicated if the -l or -p options are given. Refer to those options for details. 💅

If you invoke gcov with multiple input files, the contributions from each input file are summed. Typically you would invoke it with the same list of files as the final link of your executable.

---

🌸 the .gcov file format 🌸

The .gcov files contain : separated fields along with program source code. The format is:

<execution_count>:<line_number>:<source line text>

Additional block information may succeed each line, when requested by command line option. The execution_count is - for lines containing no code. Unexecuted lines are marked ##### or =====, depending on whether they are reachable by non-exceptional paths or only exceptional paths such as C++ exception handlers, respectively. Given the -a option, unexecuted blocks are marked $$$$$ or %%%%%, depending on whether a basic block is reachable via non-exceptional or exceptional paths. Executed basic blocks having a statement with zero execution_count end with * character and are colored with magenta color with the -k option. This functionality is not supported in Ada. 🚫

Note that GCC can completely remove the bodies of functions that are not needed — for instance if they are inlined everywhere. Such functions are marked with -, which can be confusing. Use the -fkeep-inline-functions and -fkeep-static-functions options to retain these functions and allow gcov to properly show their execution_count.

Some lines of information at the start have line_number of zero. These preamble lines are of the form:

-:0:<tag>:<value>

The ordering and number of these preamble lines will be augmented as gcov development progresses — do not rely on them remaining unchanged. Use tag to locate a particular preamble line. 👀

The additional block information is of the form:

<tag> <information>

The information is human readable, but designed to be simple enough for machine parsing too. Best of both worlds, honestly.

---

✨ percentages, and the way they get printed ✨

When printing percentages, 0% and 100% are only printed when the values are exactly 0% and 100% respectively. Other values which would conventionally be rounded to 0% or 100% are instead printed as the nearest non-boundary value. So no fake-perfect scores around here, no cap. 💯

---

🦋 how to actually use it 🦋

When using gcov, you must first compile your program with a special GCC option --coverage. This tells the compiler to generate additional information needed by gcov (basically a flow graph of the program) and also includes additional code in the object files for generating the extra profiling information needed by gcov. These additional files are placed in the directory where the object file is located.

Running the program will cause profile output to be generated. For each source file compiled with -fprofile-arcs, an accompanying .gcda file will be placed in the object file directory.

Running gcov with your program's source file names as arguments will now produce a listing of the code along with frequency of execution for each line. For example, if your program is called tmp.cpp, this is what you see when you use the basic gcov facility:

$ g++ --coverage tmp.cpp -c
$ g++ --coverage tmp.o
$ a.out
$ gcov tmp.cpp -m
File 'tmp.cpp'
Lines executed:92.86% of 14
Creating 'tmp.cpp.gcov'

The file tmp.cpp.gcov contains output from gcov. Here is a sample:

        -:    0:Source:tmp.cpp
        -:    0:Working directory:/home/gcc/testcase
        -:    0:Graph:tmp.gcno
        -:    0:Data:tmp.gcda
        -:    0:Runs:1
        -:    0:Programs:1
        -:    1:#include <stdio.h>
        -:    2:
        -:    3:template<class T>
        -:    4:class Foo
        -:    5:{
        -:    6:  public:
       1*:    7:  Foo(): b (1000) {}
------------------
Foo<char>::Foo():
    #####:    7:  Foo(): b (1000) {}
------------------
Foo<int>::Foo():
        1:    7:  Foo(): b (1000) {}
------------------
       2*:    8:  void inc () { b++; }
------------------
Foo<char>::inc():
    #####:    8:  void inc () { b++; }
------------------
Foo<int>::inc():
        2:    8:  void inc () { b++; }
------------------
        -:    9:
        -:   10:  private:
        -:   11:  int b;
        -:   12:};
        -:   13:
        -:   14:template class Foo<int>;
        -:   15:template class Foo<char>;
        -:   16:
        -:   17:int
        1:   18:main (void)
        -:   19:{
        -:   20:  int i, total;
        1:   21:  Foo<int> counter;
        -:   22:
        1:   23:  counter.inc();
        1:   24:  counter.inc();
        1:   25:  total = 0;
        -:   26:
       11:   27:  for (i = 0; i < 10; i++)
       10:   28:    total += i;
        -:   29:
       1*:   30:  int v = total > 100 ? 1 : 2;
        -:   31:
        1:   32:  if (total != 45)
    #####:   33:    printf ("Failure\n");
        -:   34:  else
        1:   35:    printf ("Success\n");
        1:   36:  return 0;
        -:   37:}

Note that line 7 is shown in the report multiple times. First occurrence presents total number of execution of the line and the next two belong to instances of class Foo constructors. As you can also see, line 30 contains some unexecuted basic blocks and thus execution count has asterisk symbol. ⭐

When you use the -a option, you will get individual block counts, and the output looks like this:

---

okay so picking up right where we left off — here's the rest of that output, bestie:

                       -:    0:Source:tmp.cpp
                       -:    0:Working directory:/home/gcc/testcase
                       -:    0:Graph:tmp.gcno
                       -:    0:Data:tmp.gcda
                       -:    0:Runs:1
                       -:    0:Programs:1
                       -:    1:#include <stdio.h>
                       -:    2:
                       -:    3:template<class T>
                       -:    4:class Foo
                       -:    5:{
                       -:    6:  public:
                      1*:    7:  Foo(): b (1000) {}
               ------------------
               Foo<char>::Foo():
                   #####:    7:  Foo(): b (1000) {}
               ------------------
               Foo<int>::Foo():
                       1:    7:  Foo(): b (1000) {}
               ------------------
                      2*:    8:  void inc () { b++; }
               ------------------
               Foo<char>::inc():
                   #####:    8:  void inc () { b++; }
               ------------------
               Foo<int>::inc():
                       2:    8:  void inc () { b++; }
               ------------------
                       -:    9:
                       -:   10:  private:
                       -:   11:  int b;
                       -:   12:};
                       -:   13:
                       -:   14:template class Foo<int>;
                       -:   15:template class Foo<char>;
                       -:   16:
                       -:   17:int
                       1:   18:main (void)
                       -:   19:{
                       -:   20:  int i, total;
                       1:   21:  Foo<int> counter;
                       1:   21-block  0
                       -:   22:
                       1:   23:  counter.inc();
                       1:   23-block  0
                       1:   24:  counter.inc();
                       1:   24-block  0
                       1:   25:  total = 0;
                       -:   26:
                      11:   27:  for (i = 0; i < 10; i++)
                       1:   27-block  0
                      11:   27-block  1
                      10:   28:    total += i;
                      10:   28-block  0
                       -:   29:
                      1*:   30:  int v = total > 100 ? 1 : 2;
                       1:   30-block  0
                   %%%%%:   30-block  1
                       1:   30-block  2
                       -:   31:
                       1:   32:  if (total != 45)
                       1:   32-block  0
                   #####:   33:    printf ("Failure\n");
                   %%%%%:   33-block  0
                       -:   34:  else
                       1:   35:    printf ("Success\n");
                       1:   35-block  0
                       1:   36:  return 0;
                       1:   36-block  0
                       -:   37:}

so in this mode, every basic block only gets shown on one line — specifically the last line of the block. If a block spans multiple lines, only that last line eats the execution count, and the other lines won't be shown as containing code, unless some earlier block happens to end on them. The line's total execution count gets printed, and then the lines after it show the execution counts for each individual block that ends on that line. And after each block? If you passed -b, you also get that block's branch and call counts. 💅

Because of the way GCC instruments calls, a call count can totally show up after a line that has no individual blocks at all. And look — line 33 has a basic block that just never got executed. not a single run. 😭

When you use the -b option, your output looks like this:

                       -:    0:Source:tmp.cpp
                       -:    0:Working directory:/home/gcc/testcase
                       -:    0:Graph:tmp.gcno
                       -:    0:Data:tmp.gcda
                       -:    0:Runs:1
                       -:    0:Programs:1
                       -:    1:#include <stdio.h>
                       -:    2:
                       -:    3:template<class T>
                       -:    4:class Foo
                       -:    5:{
                       -:    6:  public:
                      1*:    7:  Foo(): b (1000) {}
               ------------------
               Foo<char>::Foo():
               function Foo<char>::Foo() called 0 returned 0% blocks executed 0%
                   #####:    7:  Foo(): b (1000) {}
               ------------------
               Foo<int>::Foo():
               function Foo<int>::Foo() called 1 returned 100% blocks executed 100%
                       1:    7:  Foo(): b (1000) {}
               ------------------
                      2*:    8:  void inc () { b++; }
               ------------------
               Foo<char>::inc():
               function Foo<char>::inc() called 0 returned 0% blocks executed 0%
                   #####:    8:  void inc () { b++; }
               ------------------
               Foo<int>::inc():
               function Foo<int>::inc() called 2 returned 100% blocks executed 100%
                       2:    8:  void inc () { b++; }
               ------------------
                       -:    9:
                       -:   10:  private:
                       -:   11:  int b;
                       -:   12:};
                       -:   13:
                       -:   14:template class Foo<int>;
                       -:   15:template class Foo<char>;
                       -:   16:
                       -:   17:int
               function main called 1 returned 100% blocks executed 81%
                       1:   18:main (void)
                       -:   19:{
                       -:   20:  int i, total;
                       1:   21:  Foo<int> counter;
               call    0 returned 100%
               branch  1 taken 100% (fallthrough)
               branch  2 taken 0% (throw)
                       -:   22:
                       1:   23:  counter.inc();
               call    0 returned 100%
               branch  1 taken 100% (fallthrough)
               branch  2 taken 0% (throw)
                       1:   24:  counter.inc();
               call    0 returned 100%
               branch  1 taken 100% (fallthrough)
               branch  2 taken 0% (throw)
                       1:   25:  total = 0;
                       -:   26:
                      11:   27:  for (i = 0; i < 10; i++)
               branch  0 taken 91% (fallthrough)
               branch  1 taken 9%
                      10:   28:    total += i;
                       -:   29:
                      1*:   30:  int v = total > 100 ? 1 : 2;
               branch  0 taken 0% (fallthrough)
               branch  1 taken 100%
                       -:   31:
                       1:   32:  if (total != 45)
               branch  0 taken 0% (fallthrough)
               branch  1 taken 100%
                   #####:   33:    printf ("Failure\n");
               call    0 never executed
               branch  1 never executed
               branch  2 never executed
                       -:   34:  else
                       1:   35:    printf ("Success\n");
               call    0 returned 100%
               branch  1 taken 100% (fallthrough)
               branch  2 taken 0% (throw)
                       1:   36:  return 0;
                       -:   37:}

For every function, you get a line telling you how many times the function was called, how many times it returned, and what percentage of that function's blocks actually executed. the receipts, basically ✨

For every basic block, there's a line printed after the last line of the block describing the branch or call that ends it. And plot twist: you can get multiple branches and calls listed for one single source line, if multiple basic blocks end on that line. When that happens, each branch and call gets its own number. Ngl, there is no simple way to map those branches and calls back to the source constructs. But in general? The lowest-numbered branch or call lines up with the leftmost construct on that source line. 🫶

For a branch: if it ran at least once, you get a percentage — times the branch was taken divided by times the branch was executed. If it never ran? You get the message "never executed". flatline energy 💀

For a call: if it ran at least once, you get a percentage — times the call returned divided by times the call was executed. Usually that's 100%, but it can be lower for functions that call "exit" or "longjmp", since those cuties might not return every single time they get called. they ghost sometimes, it's not personal 🙈

The execution counts are cumulative. So if you ran the example program again without deleting the .gcda file, the count for how many times each source line ran would get added to the results from the previous run(s). And honestly? That's useful in several ways. For example, it could accumulate data across a bunch of program runs as part of a test verification suite, or give you more accurate long-term info across a huge number of program runs. 👑

The data in the .gcda files gets saved immediately before the program exits. For each source file compiled with -fprofile-arcs, the profiling code first tries to read in an existing .gcda file; and if that file doesn't match the executable (like, differing number of basic block counts), it just ignores the contents of the file. Then it adds in the new execution counts, and finally writes the data out to the file. read, merge, write, slay 💖

---

🌈 Using gcov with GCC Optimization 🌈

If you're planning to use gcov to help optimize your code, you must first compile your program with a special GCC option: --coverage. Aside from that one, you can use any other GCC options you want — go off. But fair warning: if you want to prove that every single line in your program got executed, you should not compile with optimization at the same time. On some machines the optimizer will eliminate some simple code lines by merging them with other lines. For example, code like this:

        if (a != b)
          c = 1;
        else
          c = 0;

can get compiled into one single instruction on some machines. And in that case, there is no way for gcov to calculate separate execution counts for each line, because there isn't separate code for each line. So if you compiled the program with optimization, the gcov output ends up looking like this:

              100:   12:if (a != b)
              100:   13:  c = 1;
              100:   14:else
              100:   15:  c = 0;

The output shows that this whole block of code, combined by optimization, executed 100 times. And in one sense that result is correct, because there was only one instruction representing all four of these lines. math is math ✨ But here's the thing — the output does not tell you how many times the result was 0 and how many times the result was 1. the lore is lost, bestie 😭

Inlineable functions can also create unexpected line counts. Line counts get shown for the source code of the inlineable function, but what actually shows up depends on where the function is inlined — or whether it's not inlined at all. chaotic behavior, honestly iconic 🦋

Okay so real talk bestie, this next bit is the inline-function tea and it's a whole situation, so buckle up 🎀

If a function is not inlined, the compiler has to emit an out-of-line copy of it, and it does that in every object file that needs one. So if fileA.o and fileB.o both contain out-of-line bodies of the same inlineable function, they're both also carrying coverage counts for that function. Now link fileA.o and fileB.o together and — on many systems — the linker will pick one of those out-of-line bodies for all calls to that function, and remove or ignore the other. Which sounds fine, except... it does not clean up the coverage counters for the unused function body. 😭 So once you instrument, all but one use of that function will show zero counts. Not a vibe.

And if the function is inlined in several places? Then the block structure at each of those locations might not even be the same. Like, a condition might suddenly be calculable at compile time in some instances. And because the coverage of all the uses of that inline function gets shown for the same source lines, the line counts themselves might look inconsistent. It's giving chaos but it's just how inlining works, no cap. 🦋

---

✨ Now for the long-running-app glow-up ✨

If your application is the type to just. keep. running. (main character energy, honestly), you can use the __gcov_reset and __gcov_dump facilities to restrict profile collection to just the program region you actually care about.

• Calling __gcov_reset(void) clears all run-time profile counters to zero.
• Calling __gcov_dump(void) dumps the profile information collected at that point into .gcda output files.

Instrumented applications use a static destructor with priority 99 to invoke the __gcov_dump function. Which means __gcov_dump runs after all user defined static destructors, and also after any handlers registered with atexit. Order matters, bestie. 💅

Heads up: if an executable loads a dynamic shared object via dlopen functionality, you need -Wl,--dynamic-list-data to dump all the profile data. Don't skip it, fr fr.

---

💀 Errors, because of course 💀

The profiling run-time library reports various errors related to profile manipulation and profile saving. Those errors get printed to standard error output, or to the GCOV_ERROR_FILE file if that environment variable is in use.

And if you want things to just stop immediately the second an error occurs, set the GCOV_EXIT_AT_ERROR environment variable. Honestly? Kind of iconic. It can help you find profile clashing, which is what leads to a misleading profile in the first place. 🔍

---

👀 SEE ALSO 👀

• gpl(7)
• gfdl(7)
• fsf-funding(7)
• gcc(1)
• and the Info entry for gcc.

Go read them, iykyk. 📚

---

💖 COPYRIGHT 💖

Copyright (c) 1996-2024 Free Software Foundation, Inc.

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being "GNU General Public License" and "Funding Free Software", the Front-Cover texts being (a) (see below), and with the Back-Cover Texts being (b) (see below). A copy of the license is included in the gfdl(7) man page.

(a) The FSF's Front-Cover Text is:

A GNU Manual

(b) The FSF's Back-Cover Text is:

You have freedom to copy and modify this GNU Manual, like GNU
software.  Copies published by the Free Software Foundation raise
funds for GNU development.

---

And that's the whole page, bestie! 🌈 This one came from gcc-14 and it's dated 2026-07-24 — GCOV(1), periodt. 💅✨ Go forth and profile responsibly, ily 🫶💖