gcov - GNU C coverage tool
gcov [-bflnv] [-o dir] srcfile ...
The gcov(1) utility produces profiling information about code coverage. It works on programs compiled with the gcc options -fprofile-arcs and -ftest-coverage. With these options, the compiler generates additional files with the extensions .bband .bbg in the source directory. Before running gcov(1), run the program to be tested, in the source directory. Running the program creates files with the extension .da; these files are needed by gcov(1). (Execution counts in the .da data files is cumulative; if the program is executed while there is an existing .da file in the directory, the new execution counts are added to the existing ones.)
While running, gcov(1) creates a logfile (unless the -n option is given) which contains the results of the analysis. A description of the logfile format is given later.
Results are less reliable if the code is compiled with the optimization flag. The gcov(1) program matches code on a line-by-line basis; by combining operations, the optimizer weakens the relationship between the code and the executable.
The logfile is a copy of the source file. Each line is prefixed by a frequency count, ###### if it was never executed, or two tab characters. For example, after running this program four times:
#include <stdio.h>
main()
{
4 int i, odd, even;
4 odd = even = 0;
404 for (i=0; i<100; i++)
{
400 if (i%2)
200 odd++;
else
200 even++;
400 if (i==100)
###### printf("Impossible!0);
400 }
4 if (i==100)
4 printf("Certain!0);
4 printf("there are %d odd numbers0, odd);
4 printf("there are %d even numbers0, even);
4 return(0);
4}
The -b option changes this output:
#include <stdio.h>
main()
{
4 int i, odd, even;
4 odd = even = 0;
404 for (i=0; i<100; i++)
branch 0 taken = 99%
branch 1 taken = 100%
branch 2 taken = 100%
{
400 if (i%2)
branch 0 taken = 50%
200 odd++;
branch 0 taken = 100%
else
200 even++;
400 if (i==100)
branch 0 taken = 100%
###### printf("Impossible!0);
call 0 never executed
400 }
4 if (i==100)
branch 0 taken = 0%
4 printf("Impossible!0);
call 0 returns = 100%
4 printf("there are %d odd numbers0, odd);
call 0 returns = 100%
4 printf("there are %d even numbers0, even);
call 0 returns = 100%
4 return(0);
branch 0 taken = 100%
4}
call 0 returns = 0%
call 1 returns = 100%
A line is output after each basic block of code. If more than one
block of code ends on a line of code, that line of code will have
more than one output line after it.
Each branch is numbered. In general, the left-most branch on a line gets numbered first, but there is no simple way to map the numbers to the source. If a branch is executed, the -b option causes gcov(1) to print the number of times it was taken divided by the number of times the branch was executed (as a percentage). In four executions of the program, the for line was executed 404 times and the branch was taken 400 times, or 99%.
The percentage for function calls is calculated in a similar way: the number of times the call returned divide by the number of times the call was executed. (Usually only calls such as exit(3) or longjmp(3) show a value other than 100%.)
The gcov(1) utility exits with status 0 for success, and >0 if an error occurred.
The gcov(1) command makes use of the following files:
gcc(1)