Invoking gcov

gcov [-b] [-v] [-n] [-l] [-f] [-o directory] sourcefile

-b

Write branch frequencies to the output file. Write branch summary info to standard output. This option allows you to see how often each branch was taken.

-v

Display the gcov version number (on the standard error stream).

-n

Do not create the gcov output file.

-l

Create long file names for included source files. For example, if the header file `x.h' contains code, and was included in the file `a.c', then running gcov on the file `a.c' will produce an output file called `a.c.x.h.gcov' instead of `x.h.gcov'. This can be useful if `x.h' is included in multiple source files.

-f

Output summaries for each function in addition to the file level summary.

-o

The directory where the object files live. Gcov will search for .bb, .bbg, and .da files in this directory.

To use gcov, first compile your program with two special GNU CC options: `-fprofile-arcs -ftest-coverage'. Then run the program. Then run gcov with your program's source file names as arguments. For example, if your program is called `tmp.c', this is what you see when you use the basic gcov facility:

$ gcc -fprofile-arcs -ftest-coverage tmp.c
$ a.out
$ gcov tmp.c
 87.50% of 8 source lines executed in file tmp.c
Creating tmp.c.gcov.

The file `tmp.c.gcov' contains output from gcov. Here is a sample:

                main()
                {
           1      int i, total;
                
           1      total = 0;
                
          11      for (i = 0; i < 10; i++)
          10        total += i;
                
           1      if (total != 45)
      ######        printf ("Failure\n");
                  else
           1        printf ("Success\n");
           1    }

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

$ gcov -b tmp.c
 87.50% of 8 source lines executed in file tmp.c
 80.00% of 5 branches executed in file tmp.c
 80.00% of 5 branches taken at least once in file tmp.c
 50.00% of 2 calls executed in file tmp.c
Creating tmp.c.gcov.

Here is a sample of a resulting `tmp.c.gcov' file:

                main()
                {
           1      int i, total;
                
           1      total = 0;
                
          11      for (i = 0; i < 10; i++)
branch 0 taken = 91%
branch 1 taken = 100%
branch 2 taken = 100%
          10        total += i;
                
           1      if (total != 45)
branch 0 taken = 100%
      ######        printf ("Failure\n");
call 0 never executed
branch 1 never executed
                  else
           1        printf ("Success\n");
call 0 returns = 100%
           1    }

For each basic block, a line is printed after the last line of the basic block describing the branch or call that ends the basic block. There can be multiple branches and calls listed for a single source line if there are multiple basic blocks that end on that line. In this case, the branches and calls are each given a number. There is no simple way to map these branches and calls back to source constructs. In general, though, the lowest numbered branch or call will correspond to the leftmost construct on the source line.

For a branch, if it was executed at least once, then a percentage indicating the number of times the branch was taken divided by the number of times the branch was executed will be printed. Otherwise, the message "never executed" is printed.

For a call, if it was executed at least once, then a percentage indicating the number of times the call returned divided by the number of times the call was executed will be printed. This will usually be 100%, but may be less for functions call exit or longjmp, and thus may not return everytime they are called.