gcov.texi

GCC

      ######        printf ("Failure\n");
                  else
           1        printf ("Success\n");
           1    @}
@end smallexample

@need 450
When you use the @option{-b} option, your output looks like this:

@smallexample
$ 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.
@end smallexample

Here is a sample of a resulting @file{tmp.c.gcov} file:

@smallexample
                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    @}
@end smallexample

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 @code{exit} or @code{longjmp},
and thus may not return every time they are called.

The execution counts are cumulative.  If the example program were
executed again without removing the @file{.da} file, the count for the
number of times each line in the source was executed would be added to
the results of the previous run(s).  This is potentially useful in
several ways.  For example, it could be used to accumulate data over a
number of program runs as part of a test verification suite, or to
provide more accurate long-term information over a large number of
program runs.

The data in the @file{.da} files is saved immediately before the program
exits.  For each source file compiled with @option{-fprofile-arcs}, the profiling
code first attempts to read in an existing @file{.da} file; if the file
doesn't match the executable (differing number of basic block counts) it
will ignore the contents of the file.  It then adds in the new execution
counts and finally writes the data to the file.

@node Gcov and Optimization
@section Using @command{gcov} with GCC Optimization

If you plan to use @command{gcov} to help optimize your code, you must
first compile your program with two special @sc{gnu} CC options:
@samp{-fprofile-arcs -ftest-coverage}.  Aside from that, you can use any
other @sc{gnu} CC options; but if you want to prove that every single line
in your program was executed, you should not compile with optimization
at the same time.  On some machines the optimizer can eliminate some
simple code lines by combining them with other lines.  For example, code
like this:

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

@noindent
can be compiled into one instruction on some machines.  In this case,
there is no way for @command{gcov} to calculate separate execution counts
for each line because there isn't separate code for each line.  Hence
the @command{gcov} output looks like this if you compiled the program with
optimization:

@smallexample
      100  if (a != b)
      100    c = 1;
      100  else
      100    c = 0;
@end smallexample

The output shows that this block of code, combined by optimization,
executed 100 times.  In one sense this result is correct, because there
was only one instruction representing all four of these lines.  However,
the output does not indicate how many times the result was 0 and how
many times the result was 1.
@c man end

@node Gcov Data Files
@section Brief description of @command{gcov} data files

@command{gcov} uses three files for doing profiling.  The names of these
files are derived from the original @emph{source} file by substituting
the file suffix with either @file{.bb}, @file{.bbg}, or @file{.da}.  All
of these files are placed in the same directory as the source file, and
contain data stored in a platform-independent method.

The @file{.bb} and @file{.bbg} files are generated when the source file
is compiled with the @sc{gnu} CC @option{-ftest-coverage} option.  The
@file{.bb} file contains a list of source files (including headers),
functions within those files, and line numbers corresponding to each
basic block in the source file.

The @file{.bb} file format consists of several lists of 4-byte integers
which correspond to the line numbers of each basic block in the
file.  Each list is terminated by a line number of 0.  A line number of @minus{}1
is used to designate that the source file name (padded to a 4-byte
boundary and followed by another @minus{}1) follows.  In addition, a line number
of @minus{}2 is used to designate that the name of a function (also padded to a
4-byte boundary and followed by a @minus{}2) follows.

The @file{.bbg} file is used to reconstruct the program flow graph for
the source file.  It contains a list of the program flow arcs (possible
branches taken from one basic block to another) for each function which,
in combination with the @file{.bb} file, enables gcov to reconstruct the
program flow.

In the @file{.bbg} file, the format is:
@smallexample
        number of basic blocks for function #0 (4-byte number)
        total number of arcs for function #0 (4-byte number)
        count of arcs in basic block #0 (4-byte number)
        destination basic block of arc #0 (4-byte number)
        flag bits (4-byte number)
        destination basic block of arc #1 (4-byte number)
        flag bits (4-byte number)
        @dots{}
        destination basic block of arc #N (4-byte number)
        flag bits (4-byte number)
        count of arcs in basic block #1 (4-byte number)
        destination basic block of arc #0 (4-byte number)
        flag bits (4-byte number)
        @dots{}
@end smallexample

A @minus{}1 (stored as a 4-byte number) is used to separate each function's
list of basic blocks, and to verify that the file has been read
correctly.

The @file{.da} file is generated when a program containing object files
built with the @sc{gnu} CC @option{-fprofile-arcs} option is executed.  A
separate @file{.da} file is created for each source file compiled with
this option, and the name of the @file{.da} file is stored as an
absolute pathname in the resulting object file.  This path name is
derived from the source file name by substituting a @file{.da} suffix.

The format of the @file{.da} file is fairly simple.  The first 8-byte
number is the number of counts in the file, followed by the counts
(stored as 8-byte numbers).  Each count corresponds to the number of
times each arc in the program is executed.  The counts are cumulative;
each time the program is executed, it attempts to combine the existing
@file{.da} files with the new counts for this invocation of the
program.  It ignores the contents of any @file{.da} files whose number of
arcs doesn't correspond to the current program, and merely overwrites
them instead.

All three of these files use the functions in @file{gcov-io.h} to store
integers; the functions in this header provide a machine-independent
mechanism for storing and retrieving data from a stream.